API Reference - Ideal Postcodes

Find Address The address autocomplete API returns a list of address suggestions that match the query ordered by relevance. This API can be used to power realtime address finders, also known as address autofill or address autocomplete. Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments. ## Implementing Address Autocomplete Rapid address autocompletion using our Address Autocomplete API is a 2 step process. 1. Retrieve partial address suggestions via `/autocomplete/addresses` 2. Retrieve the entire address with the ID provided in the suggestion Step 2 will decrement your lookup balance. Please note, this API is not intended to be a free standalone resource. ## Filters You can strictly narrow your result by adding filters to your querystring. For instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`. If a filter term is invalid, e.g. `postcode=SW1A2AAA`, then an empty result set is returned and no lookup is incurred. You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined. All filters can accept multiple terms unless stated otherwise below. Filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set. A maximum of **10** terms are allowed across all filters. ## Biases You can boost certain addresses results that match specific address criteria. All bias searches are prefixed with `bias_`. Biasing (unlike filtering) also allow unmatched addresses to appear with lower precedence. For instance, can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`. No bias effect applies to bias terms that are invalid. e.g. `bias_postcode=SW1A2AAA` You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to `E1`, `E2` and `E3` outward codes: bias_postcode_outward=e1,e2,e3. All biases can accept multiple terms unless stated otherwise below. A combined maximum of **5** terms are allowed across all biases. ## Suggestion Format The suggestion format is prone to change over time. Attempts to parse the suggestion may result in your integration breaking. Instead use the suggestion as-is. ## Rate Limiting You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit. | Header | Description | | ----------------------- | -------------------------------------------------------------------------------------- | | `X-RateLimit-Limit` | The maximum number of requests that can be made in 5 minutes | | `X-RateLimit-Remaining` | The remaining requests within the current rate limit window | | `X-RateLimit-Reset` | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds | ## Pricing This API currently does not affect your balance. However, resolving a suggestion into a full address requires a paid request. Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an address may be disrupted via tightened rate limits. Continued misuse will result in account suspension.

Cleanse 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?

Extract Addresses Extract a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively). If a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored. This API is designed as a multi-purpose tool for generating address lists, cleansing and wholesale data extraction according to specific parameters. For address autocomplete, see our address finder API - which is designed for speed and address completion. ## Reverse Geocoding Return a list of addresses around a point using the lon= and lat= querystring arguments. Addresses will be sorted in order of distance to the point. The search radius is 100m. ## Filters You can strictly narrow your result by adding filters to your query string which correspond with an address attribute. For instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`. If a filter term is invalid, e.g. `postcode=SW1A2AAA`, then an empty result set is returned and no lookup is incurred. You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined. All filters can accept multiple terms unless stated otherwise below. Multiple filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set. A combined maximum of 5 terms are allowed across all filters. ## Biases You can boost certain addresses results that correspond with a certain address attribute. All bias searches are prefixed with `bias_`. Biased searches, unlike filtered searches, also allow unmatched addresses to appear . These will rank lower. For instance, you can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`. If a bias term is invalid, e.g. `bias_postcode=SW1A2AAA` no bias effect is applied. You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to `E1`, `E2` and `E3` outward codes: `bias_postcode_outward=e1,e2,e3`. All biases can accept multiple terms unless stated otherwise below. A combined maximum of 5 terms are allowed across all biases. ## Search by Postcode and Building Name or Number Search by postcode and building attribute with the postcode filter and query argument. E.g. For "SW1A 2AA Prime Minister" `/v1/addresses?postcode=sw1a2aa&q=prime minister`. The advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned. #### Search By UPRN Search by UPRN using the `uprn` filter and excluding the query argument. E.g. `/v1/addresses?uprn=100`. ## Testing - **ID1 1QD** Returns a successful query response `2000` - **ID1 KFA** Returns an empty query response `2000` - **ID1 CLIP** Returns "no lookups remaining" error `4020` - **ID1 CHOP** 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.

Create a config

Create a licensee for the specified API Key.

Delete Permanently deletes a configuration object.

Cancels a licensee key. This renders a licensee unusable. This action can be reversed if you get in contact with us.

Email Validation Query for and validate email addresses.

Find Place Query for geographical places across countries. Each query will return a list of place suggestions, which consists of a place name, descriptive name and id. This API returns geographical information such as countries, capitals, administrative areas and more. It is ideal for correctly identifying a place along with any other details like geolocation. ## Implementing Place Autocomplete Extracting the full information of a place is a 2 step process: 1. Retrieve place suggestions via /places 2. Retrieve the entire place with the ID provided in the suggestion ## Suggestion Format Each place suggestion contains a descriptive name which you can provide to users to uniquely idenfity a place. ## Rate Limiting You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit. | Header | Description | | ----------------------- | -------------------------------------------------------------------------------------- | | `X-RateLimit-Limit` | The maximum number of requests that can be made in 5 minutes | | `X-RateLimit-Remaining` | The remaining requests within the current rate limit window | | `X-RateLimit-Reset` | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds | ## Pricing This API currently does not affect your balance. However, resolving a suggestion into a full place requires a paid request. Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an place may be disrupted via tightened rate limits.

Availability Returns public information on key. Currently only returns whether the key is currently useable via the `available` property. Use this to discover if the key is useable before making further requests. You may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`). ## Testing To test your implementation of our API, you may use the following test keys. - **iddqd** Availability will return as `true` - **idkfa** Availability will return as `false`

Details Returns private data on the key including remaining lookups, available datasets and usage limits.

Logs (CSV) 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.

Usage Stats 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.

Lists configurations associated with a key

List Returns a list of licensees for a key.

Phone Number Validation Query for and validate phone numbers.

Lookup Postcode 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.

Resolve Address (GBR) Resolves an address autocompletion by its address ID. Resolved addresses (including global addresses) are returned in a UK format (up to 3 address lines) using UK nomenclature (like postcode and county).

Resolve Place Resolves a place autocompletion by its place ID.

Resolve Address (USA) Resolves an address autocompletion by its address ID. Resolved addresses (including global addresses) are returned in a US format (up to 2 address lines) using US nomenclature (like zipcode, state and city).

Retrieve config object by name

Retrieve Returns licensee information as identified by the licensee key.

Retrieve by UDPRN 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.

Retrieve by UMPRN 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.

Updates configuration object

Update Licensee