@ideal-postcodes/openapi

openapi: 3.0.3 info: version: 4.0.0 license: name: AGPLv3 url: https://opensource.org/licenses/AGPL-3.0 title: API Reference termsOfService: https://terms.ideal-postcodes.co.uk description: | ## Getting Started All API methods are either a `GET`, `POST` or `OPTIONS` request. The API communicates over both HTTPS and plain HTTP using IPv4 and IPv6. We recommend using HTTPS only although HTTP is available. We use appropriate HTTP status codes where possible to indicate the request status. ## Rate Limiting Each IP address is rate limited at 30 requests per second. Tripping the rate limit will result in a 503 response. The autocomplete API also has an additional rate limit. If you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit. ## Authentication Most requests require an **API key** for authentication. Authenticate by passing an `api_key` as part of the query string. For example: ``` api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=parkside ``` Alternatively, authentication can be transmitted via the `Authorization` header using the following scheme: ``` Authorization: api_key="iddqd" [other_key="foo"] ``` ## Versioning This API is versioned with a simple prefix in the URL. The current version is `/v1/`. We will maintain backwards-compatibility by releasing breaking changes under a new version. Please note that the following changes are backwards-compatible: - Adding new properties to existing API responses - Adding new API endpoints - Adding new optional request parameters to existing API endpoints - Changing the order of properties in existing API responses - Changing the autocomplete address suggestion format ## Error Handling A successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body). An error has occurred if the HTTP status code is not 200. Errors can range from a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc). ## Testing Each new account comes with a free test balance. Contact us if you need more for testing and integration. ## Metadata Requests that affect your balance may be annotated with arbitrary metadata. This data is stored along with your lookup history and can be queried at a later date via the API or the dashboard. We call the ability to label your requests [tagging](https://docs.ideal-postcodes.co.uk/docs/guides/tags). ## Response Codes The API returns two indicators to help you to determine the status of each HTTP request. The first is the **HTTP Status**, which is found in the status-line of all HTTP requests. The API will return status codes that adhere to HTTP /1.1 Specifications wherever possible. `2XX` status codes indicates success while `4XX` and `5XX` indicate client and server errors respectively. The second is the **API response code**, which can be found in the `code` property of the response body. This code will provide a more specific reason if a failure has occurred and can point you in the right direction when debugging. Please use the glossary of code numbers and HTTP status codes below when debugging your requests. ### 200 Request Success | HTTP Code | API Code | Description | | --------- | -------- | -------------------------------------------- | | 200 | 2000 | Success. Request was completed successfully. | ### 400 Bad Request The request could not be understood due to some input error. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | 400 | 4000 | Invalid syntax submitted. Some part of your request was malformed or did not match our specifications. | | 400 | 4001 | Validation failed on your submitted data. Some of the data you provided did not meet our validation requirements, e.g. string length. | | 400 | 4005 | Invalid start date. Please ensure start dates are provided as a UTC Timestamp in milliseconds. | | 400 | 4006 | Invalid end date. Please ensure end dates are provided as a UTC Timestamp in milliseconds. | | 400 | 4007 | Invalid date range. Check if your start and end dates are in the right order. | | 400 | 4008 | Invalid date range. Check that your date range is 90 days or less. | | 400 | 4009 | Too many tags. Please specify no more than 3 tags to query. | ### 401 Unauthorised Authorization credentials are not valid. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 401 | 4010 | Invalid Key. The `api_key` you provided is not valid. | | 401 | 4011 | Requesting URL not on whitelist. The cross domain request is not coming from a whitelisted URL. You can update or disable your allowed URLs via your Key settings. | | 401 | 4012 | Failed user authentication. Invalid `user_token` presented. | | 401 | 4013 | Licensee Key is required. Sublicensed keys require you need to present licensee credentials via the `licensee` parameter. | ### 402 Request Failed Your request is well-formed but are not able to complete your request for another reason. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 402 | 4020 | Key balance depleted. You're out of lookups on your API Key. | | 402 | 4021 | Limit reached. One of your lookup limits has been breached for today. This could either be your total daily limit on your key or the individual IP limit. You can either wait for for the limit to reset (after a day) or manually disable or increase your limit. | ### 404 Resource Not Found The resource you requested does not exist. | HTTP Code | API Code | Description | | --------- | -------- | --------------------------------------------------------------------------------------------- | | 404 | 4040 | Postcode not found. The postcode you have submitted does not exist. | | 404 | 4041 | User not found. Your user could not be identified given the credentials you presented. | | 404 | 4042 | Key not found. Your key could not be identified given the credentials you presented. | | 404 | 4044 | No UDPRN found. No address is associated with the UDPRN queried | | 404 | 4045 | No licensee found. Your licensee could not be identified given the credentials you presented. | | 404 | 4046 | No UMPRN found. No Multiple Residence premise is associated with the UMPRN queried. | ### 500 Server Error A error occurred on our server. | HTTP Code | API Code | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 500 | 5000 | An error occurred on our end. These errors are logged and queued so we can understand what went wrong. However, if you need speedy resolution please email support | | 500 | 5001 | Akin to 5000. | | 500 | 5002 | The server took too long to process on our end, so we aborted the request. You may retry the request. | contact: email: support@ideal-postcodes.co.uk name: Support url: https://ideal-postcodes.co.uk/support servers: - url: https://api.ideal-postcodes.co.uk/v1 description: API Server variables: {} tags: - name: Address Search description: Global address autocomplete, for search-as-you-type - name: Place Search description: Global places search to identify geographical names and places - name: UK description: UK Address and Postcode Search - name: Keys description: Monitor and manage API Keys - name: Licensees description: | The Licensee resource represents an alternate legal End User of our data who may not be same entity as the owners of the account. The concept of Licensees underpins our sublicensing platform, which allows users to license multiple external organisations or individuals to access data under the same account. Sublicensing is ideal for platform vendors, who provide services to multiple clients who in turn each have their own users. - name: Configs description: | The Config resource allows users to assign serialised configuration data to API Keys. The payloads assigned to a Config object can later be retrieved to dynamically configure your integration. Useful if you need to configure your integration remotely rather than editing code in situ. - name: suggestion x-displayName: Address Suggestion description: | Address Suggestions are simple, human readable representations of an address. This format is sufficient tfor a user to determine an address match in an address autocomplete interface. A second request must be made to the API to gather fully validated address. See our Address Search APIs for more information on address autocompletion. <SchemaDefinition schemaRef="#/components/schemas/AddressSuggestion" /> - name: usps_address x-displayName: US Address description: | Standard US Address format as reported by USPS. <SchemaDefinition schemaRef="#/components/schemas/UspsAddress" /> - name: uk_address x-displayName: UK Address description: | Standard UK Address format as reported by Royal Mail's Postcode Address File (PAF). PAF is the most complete and up-to-date address database in the UK. <SchemaDefinition schemaRef="#/components/schemas/PafAddress" /> - name: ecaf_address x-displayName: IE Address description: | Standard Republic of Ireland Address format as reported by the Eircode ECAF file. <SchemaDefinition schemaRef="#/components/schemas/EcafAddress" /> - name: ecad_address x-displayName: IE Address (ECAD) description: | ECAF file including additional data for each address. <SchemaDefinition schemaRef="#/components/schemas/EcadAddress" /> - name: ab_address x-displayName: AddressBase Core description: | AddressBase Core Address. An alternative to UK PAF dataset from Ordnance Survey. Please contact us to have this enabled on your account. <SchemaDefinition schemaRef="#/components/schemas/AddressBaseCore" /> - name: geonames_place x-displayName: GeoNames Place description: | GeoNames place record <SchemaDefinition schemaRef="#/components/schemas/GeonamesPlace" /> externalDocs: description: More on our APIs, libraries with guides and examples url: https://docs.ideal-postcodes.co.uk paths: /postcodes/{postcode}: get: tags: - UK summary: Lookup Postcode operationId: Postcodes description: | Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive. The Postcode Lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power Postcode Lookup driven address searches, like [Postcode Lookup](/postcode-lookup). ## Postcode Not Found Lookup balance is unaffected by invalid postcodes. The API returns a `404` response with response body: ```json { "code": 4040, "message": "Postcode not found", "suggestions": ["SW1A 0AA"] } ``` ### Suggestions If a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up `O` and `0` or `I` and `1`). If the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches. The suggestion list will be empty if the postcode has deviated too far from a valid postcode format. ## Multiple Residence A small number of postcodes will return more than 100 premises. These may require pagination. Use `page` to paginate the result set. parameters: - name: postcode in: path description: Postcode to retrieve required: true style: simple explode: false example: SW1A 2AA schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/FilterParam' - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PostcodeResponse' examples: Postcode Found: value: result: - postcode: SW1A 2AA postcode_inward: 2AA postcode_outward: SW1A post_town: London dependant_locality: '' double_dependant_locality: '' thoroughfare: Downing Street dependant_thoroughfare: '' building_number: '10' building_name: '' sub_building_name: '' po_box: '' department_name: '' organisation_name: Prime Minister & First Lord Of The Treasury udprn: 23747771 postcode_type: L su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Prime Minister & First Lord Of The Treasury line_2: 10 Downing Street line_3: '' premise: '10' longitude: -0.12767 latitude: 51.503541 eastings: 530047 northings: 179951 country: England traditional_county: Greater London administrative_county: '' postal_county: London county: London district: Westminster ward: St. James's uprn: '100023336956' id: paf_23747771 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: '' dataset: paf code: 2000 message: Success limit: 100 page: 0 total: 1 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '404': description: Postcode Not Found content: application/json: schema: $ref: '#/components/schemas/PostcodeNotFoundResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA?api_key=iddqd - lang: cURL label: CLI source: | curl -G -k \ --url 'https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA' \ --d "api_key=iddqd" /udprn/{udprn}: get: tags: - UK summary: Retrieve by UDPRN operationId: UDPRN description: | Returns an address as identified by its Unique Delivery Point Reference Number (UDPRN). You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a deleted address. UDPRNs are an eight digit unique numeric code (e.g. `25962203`) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database. ## Testing To test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request. They are the following: - `0` Returns a successful UDPRN lookup response `2000` - `-1` Returns "UDPRN not found", error `4044` - `-2` Returns "no lookups remaining", error `4020` - `-3` Returns "daily (or individual) lookup limit breached", error `4021` Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup. parameters: - name: udprn in: path description: UDPRN to be retrieved required: true style: simple explode: false schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/FilterParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/UDPRNResponse' examples: Valid UDPRN: value: result: postcode: SW1A 2AA postcode_inward: 2AA postcode_outward: SW1A post_town: London dependant_locality: '' double_dependant_locality: '' thoroughfare: Downing Street dependant_thoroughfare: '' building_number: '10' building_name: '' sub_building_name: '' po_box: '' department_name: '' organisation_name: Prime Minister & First Lord Of The Treasury udprn: 23747771 postcode_type: L su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Prime Minister & First Lord Of The Treasury line_2: 10 Downing Street line_3: '' premise: '10' longitude: -0.12767 latitude: 51.503541 eastings: 530047 northings: 179951 country: England traditional_county: Greater London administrative_county: '' postal_county: London county: London district: Westminster ward: St. James's uprn: '100023336956' id: paf_23747771 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: '' dataset: paf code: 2000 message: Success '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/udprn/0?api_key=iddqd - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/udprn/0 \ -d "api_key=iddqd" /umprn/{umprn}: get: tags: - UK summary: Retrieve by UMPRN operationId: UMPRN description: | Returns a multiple occupancy address identifited via its UMPRN (Multiple Residence Unique ID). UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset. ## Testing To test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following - `0` Returns a successful UMPRN lookup response `2000` - `-1` Returns "UMPRN not found", error `4044` - `-2` Returns "no lookups remaining", error `4020` - `-3` Returns "daily (or individual) lookup limit breached", error `4021` Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup. ### Pricing Per lookup charges apply. Empty responses are not charged. parameters: - name: umprn in: path description: UMPRN to be retrieved required: true style: simple explode: false schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/FilterParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/UMPRNResponse' examples: Valid UMPRN: value: result: postcode: CV4 7AL postcode_inward: 7AL postcode_outward: CV4 post_town: Coventry dependant_locality: '' double_dependant_locality: '' thoroughfare: Gibbet Hill Road dependant_thoroughfare: '' building_number: '' building_name: Block 1 Arthur Vick sub_building_name: Room 249a po_box: '' department_name: '' organisation_name: '' udprn: 5770157 postcode_type: S su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Room 249a, Block 1 Arthur Vick line_2: Gibbet Hill Road line_3: '' premise: Room 249a, Block 1 Arthur Vick longitude: -1.5648072 latitude: 52.3858227 eastings: 429716 northings: 276509 country: England traditional_county: Warwickshire administrative_county: '' postal_county: West Midlands county: West Midlands district: Coventry ward: Wainbody uprn: '200001572050' id: mr_50906058 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: 50906058 dataset: mr code: 2000 message: Success '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/umprn/0?api_key=iddqdmr - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/umprn/0 \ -d "api_key=iddqdmr" /keys/{key}: get: tags: - Keys summary: Availability operationId: KeyAvailability description: | Returns public information on your API Key. This endpoint can be used for the following: - Determine if the key is currently useable via the `available` property - Determine available contexts for a an API Key - Identify the currently likely context of a user given their location You may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`). parameters: - $ref: '#/components/parameters/ApiKeyPathParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyResponse' '404': description: Invalid Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /keys/{key}/details: get: tags: - Keys summary: Details operationId: KeyDetails description: | Returns private data on the key including remaining lookups, available datasets and usage limits. parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyDetailsResponse' '401': description: Unauthorised content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' deprecated: false put: tags: - Keys summary: Update Details description: Update API Key Details operationId: UpdateKeyDetails parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiKeyDetailsEditable' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyDetailsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorised content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /keys/{key}/usage: get: tags: - Keys summary: Usage Stats operationId: KeyUsage description: | Reports the number of lookups consumed on a key for a range of days. A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval. If no `start` time is provided, the start time will be set to 21 days prior to the current time. If no `end` time is provided, the current time will be used. Append `tags` to scope the number of lookups to those with matching tag values. E.g. `tags=foo,bar` will only count transactions that match `foo` and `bar`. parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' - $ref: '#/components/parameters/StartParam' - $ref: '#/components/parameters/EndParam' - $ref: '#/components/parameters/TagsParam' - $ref: '#/components/parameters/LicenseeParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyUsageResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage?user_token=my_secret_token - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage \ -d "user_token=my_secret_token" /keys/{key}/lookups: get: tags: - Keys summary: Logs (CSV) operationId: KeyLogs description: | Reports lookup information on a key for paid lookups. This method requires a `user_token`, which can be found on your [accounts page](https://ideal-postcodes.co.uk/account). A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval. ## Download Usage History (CSV) `GET /keys/:key/lookups` Returns a CSV download of lookups performed and associated information. Note that the Content-Type returned will be CSV (text/csv). For a non 200 response, the `Content-Type` will revert to JSON with the error code and message embedded. ## Data Redaction Personally Identifiable Data (PII) caught in this your usage log (including IP, search term and URL data) will be redacted on a weekly basis. By default, PII will be redacted if it is older than 21 days. This timeframe can be configured from your dashboard. You may prevent PII collection altogether by setting the interval to `0` days. parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' - $ref: '#/components/parameters/StartParam' - $ref: '#/components/parameters/EndParam' - $ref: '#/components/parameters/LicenseeParam' responses: '200': description: Success content: text/csv: example: | 2015-02-21T16:05:22.991Z,82.85.128.18,SW12AA,https://www.example.com/,Postcode Lookup, 2015-02-21T16:05:38.298Z,82.85.128.18,10 Downing Street London,https://www.example.com/,Address Lookup,CRM 2015-02-21T16:06:49.227Z,82.85.128.18,OX44PP,https://www.example.com/,Postcode Lookup,"Website,Live" 2015-02-21T16:07:02.706Z,82.85.128.18,PL9 9HE,https://www.example.com/,Postcode Lookup, schema: type: string description: Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups?user_token=my_secret_token - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups \ -d "user_token=my_secret_token" /cleanse/addresses: post: tags: - UK summary: Cleanse Address description: | The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse. ## Confidence Score The confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score. ### Deciding on an Acceptable Confidence Score Threshold Different address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organistation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals. When determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine: - Which confidence scores indicate ambigious matches (i.e. up to building level only) - Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address) Depending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the throroughfare or building name only? Are accurate organisation names an important feature? operationId: AddressCleanse parameters: - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/TagsParam' - name: context in: query schema: type: string description: | Identify the country of the address to cleanse. Defaults to UK (GBR) example: usa requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: | Freeform address input to cleanse example: 10 Downing Street, London, SW2A 2BN postcode: type: string description: | Optionally specify postal code for the address. example: SW1A 2BN post_town: type: string description: | Optionally specify the city or town of the address. For UK verifications, this should be the "post town" of the address. For USA verifications, this should be the city of the address. example: London county: type: string description: | Optionally specify the county or state of the address. For UK verifications, we recommend omitting this field as county data is unreliable. For USA verifications, this should be the state of the address. example: Kent responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CleanseResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '429': description: Rate Limited content: application/json: schema: $ref: '#/components/schemas/RateLimitedResponse' x-codeSamples: - lang: cURL label: CLI source: | curl -k -G 'https://api.ideal-postcodes.co.uk/v1/cleanse/addresses' \ -H 'Authorization: api_key="ak_test"' -H 'Content-Type: application/json' -d '{"query": "10 downing street sw1a"}' /verify/addresses: post: tags: - US summary: Verify Address description: | The address verify API validates, corrects, and standardizes individual addresses based on USPS's Coding Accuracy Support System (CASS). The address verify API accepts the 3 combination of inputs: - Free-form address submitted as a single string in `query` - Example: "123 Main St, Springfield, CO 81073-1119" - Only free-form and zip code address components submitted as separate parameters: - `query` for the street address - `zip_code` for the ZIP code - Example: - `query`: "123 Main St, Springfield CO" - `zip_code`: "81073-1119" - Only free-form, city and state address components submitted as separate parameters: - `query` for the street address - `city` for the city - `state` for the state - Example: - `query`: "123 Main St" - `city`: "Springfield" - `state`: "CO" operationId: AddressVerify parameters: - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/TagsParam' - name: context in: query schema: type: string description: | Identify the country of the address to verify. Defaults to United States (USA) example: usa requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: | Freeform address input to verify. Can be submitted standalone, or with the following address components: - `zip_code` - `city` and `state` example: 123 Main St, Springfield, CO 81073 zip_code: type: string description: | Specify the zip code of an address. The following formats are accepted: `81073-1119`, `810731119`, `81073`. example: 81073-1119 city: type: string description: | City of an address. For the US, this should be the city name. example: Springfield state: type: string description: | State of an address. For the US, this should be in the 2 letter state abbreviation format. example: CO responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/VerifyResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '429': description: Rate Limited content: application/json: schema: $ref: '#/components/schemas/RateLimitedResponse' x-codeSamples: - lang: cURL label: CLI source: | curl -k -G 'https://api.ideal-postcodes.co.uk/v1/verify/addresses' \ -H 'Authorization: api_key="ak_test"' -H 'Content-Type: application/json' -d '{"query": "123 Main St, Springfield, IL 62701" }' /autocomplete/addresses: get: tags: - Address Search summary: Find Address description: | The Address Autocomplete API delivers address suggestions in order of relevance based on a provided query. It aids real-time address autofill implementations. Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments rather than interacting with this API directly. ## API Usage Implementing our Address Autocomplete API involves: 1. Fetch address suggestions with `/autocomplete/addresses` 2. Acquire the complete address using the ID from the suggestion Step 2 will decrement your lookup balance. Note that step 1 is not a free standalone resource. Integrations that consistently make autocomplete requests without a paid Step 2 request will be rate limited and then suspended. ## Query Filters Refine results by appending filters to your querystring, e.g., `postcode=sw1a2aa` for postcode `SW1A 2AA`. Invalid filters return an empty set without affecting your lookup count. To apply multiple filter terms, use a comma-separated list, e.g., `postcode_outward=e1,e2,e3` combines result sets for E1, E2, and E3. Unless otherwise specified, all filters support multiple terms. Combine filters by `AND` logic, for instance, `su_organisation_indicator=Y&postcode_area=n`. The maximum allowed filter terms is **10**. ## Address Bias Preface bias searches with `bias_` to boost certain address results. Unlike filters, biasing allows unmatched addresses to appear with lower priority. For example, use `bias_postcode_area=SW,SE` to favor addresses in the `SW` and `SE` postcode areas. Invalid bias terms have no effect. Multiple bias terms are allowed unless stated otherwise, with a combined maximum of **5**. ## Suggestion Format The suggestion format is subject to change. We recommend using the suggestion as-is to prevent potential integration issues. ## Rate Limiting and Cost The rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit. Autocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension. operationId: FindAddress parameters: - $ref: '#/components/parameters/ApiKeyParam' - name: query description: | **Address Query** The partial address string entered by the user to autocomplete. example: 10 downing street lo explode: false in: query schema: type: string maxLength: 150 style: form - $ref: '#/components/parameters/ContextParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/BiasLonLatParam' - $ref: '#/components/parameters/BiasIpParam' - $ref: '#/components/parameters/BoxParam' - $ref: '#/components/parameters/PostcodeOutwardParam' - $ref: '#/components/parameters/PostcodeParam' - $ref: '#/components/parameters/PostcodeAreaParam' - $ref: '#/components/parameters/PostcodeSectorParam' - $ref: '#/components/parameters/PostTownParam' - $ref: '#/components/parameters/UPRNParam' - $ref: '#/components/parameters/CountryParam' - $ref: '#/components/parameters/PostcodeTypeParam' - $ref: '#/components/parameters/SmallUserParam' - $ref: '#/components/parameters/BiasPostcodeOutwardParam' - $ref: '#/components/parameters/BiasPostcodeParam' - $ref: '#/components/parameters/BiasPostcodeAreaParam' - $ref: '#/components/parameters/BiasPostcodeSectorParam' - $ref: '#/components/parameters/BiasPosttownParam' - $ref: '#/components/parameters/BiasThoroughfareParam' - $ref: '#/components/parameters/BiasCountryParam' responses: '200': description: Success headers: X-RateLimit-Limit: description: The maximum number of requests that can be made in 5 minutes schema: type: number format: int32 X-RateLimit-Remaining: description: The remaining requests within the current rate limit window schema: type: number format: int32 X-RateLimit-Reset: description: | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds. schema: type: number format: int32 content: application/json: schema: $ref: '#/components/schemas/AutocompleteResponse' examples: GBR: summary: Example response for GBR context value: result: hits: - id: paf_23747771 suggestion: Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A udprn: 23747771 urls: udprn: /v1/udprn/23747771 - id: paf_26245117 suggestion: Flat 10, Downing Court, Grenville Street, London, WC1N udprn: 26245117 urls: udprn: /v1/udprn/26245117 code: 2000 message: Success USA: summary: Example response for USA context value: result: hits: - suggestion: 10 Downing St, Montpelier, VT, 05602 urls: {} id: usps_V210079628|10||3797 - suggestion: 10 Ten Downing St, Fountain Inn, SC, 29644 urls: {} id: usps_X219061579|10||5031 - suggestion: 10 Downing St Apt 1, Montpelier, VT, 05602 urls: {} id: usps_V210079629|10|1|3798 - suggestion: 2100 N Downing St Unit 10, Denver, CO, 80205 urls: {} id: usps_Z125260298|2100|10|5272 - suggestion: 10 S Downing St, Denver, CO, 80209 urls: {} id: usps_Z105732754|10||2411