Returns address suggestions for a partial address, ordered by relevance. Use it to power real-time address autofill.

Consider our address autocomplete JavaScript libraries, which add address lookup to a form without calling 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 decrements your lookup balance.

Step 1 is not a free standalone resource. We rate limit and then suspend integrations that repeatedly make autocomplete requests without a paid Step 2 request.

Context

context limits the search, usually to a single country. It defaults to GBR, and an unrecognised context falls back to that default. If your key is not licensed for the datasets covering the context, the request is rejected.

Querying a full postcode within a supported context returns the entire address list for that postcode.

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.

Filters combine with AND logic, for instance su_organisation_indicator=Y&postcode_area=n. The maximum is 8 filter terms.

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 favour 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 avoid integration issues.

Rate Limiting and Cost

The default rate limit is 3,000 requests per 5 minutes, counted per key and IP address. The X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers report where you stand.

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 lead to rate limiting or suspension.

Returns the complete address for an autocomplete suggestion, identified by its address ID.

This is the step of the autocomplete flow that costs a lookup. Fetching suggestions is free.

The API returns resolved addresses, including addresses outside the UK, in a UK format (up to 3 address lines) using UK nomenclature such as postcode and county.

An ID that matches no address returns 404.

Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.

Each request looks up one postcode. To extract the addresses for several postcodes, send one request per postcode.

Use it to power postcode driven address searches, like Postcode Lookup.

Postcode lookup covers the United Kingdom, the Republic of Ireland, the Netherlands and Singapore. The API detects the format of the postcode you submit. UK and Irish postcodes are searched by default. For a Dutch or Singapore postcode, set context to NLD or SGP, or to GLOBAL to accept any supported format.

UK postcodes need PAF, Multiple Residence, Not Yet Built, PAF Alias, PAF Welsh, AddressBase or AddressBase Premium on your key. Eircodes need ECAD or ECAF. Dutch postcodes need Kadaster. Singapore postcodes need HERE Asia Pacific. Without a matching licence the request is rejected.

An unfound postcode costs no lookup. A postcode that returns addresses costs one.

Postcode Not Found

Invalid postcodes do not affect your lookup balance. The API returns a 404 response with this body:

{
  "code": 4040,
  "message": "Postcode not found",
  "suggestions": ["SW1A 0AA"]
}

Suggestions

If a postcode cannot be found, the API returns up to 5 of the closest matching postcodes. It corrects common errors first (e.g. mixing up O and 0 or I and 1).

If the suggestion list is small (fewer than 3), the correct postcode is likely to be among them. Notify the user or trigger new searches immediately.

The suggestion list is empty if the postcode has deviated too far from a valid postcode format.

Multiple Residence

A small number of postcodes return more than 100 premises. The API returns 100 addresses per page, so use page to paginate the result set.

Testing

• ID1 1QD Returns a successful postcode lookup response 2000
• ID1 KFA Returns "postcode not found" error 4040
• ID1 CLIP Returns "no lookups remaining" error 4020
• ID1 CHOP Returns "daily (or individual) lookup limit breached" error 4021

Test requests undergo the usual authentication and restriction rules. They surface any issues during implementation and do not cost you a lookup.

Returns the full address for a Unique Delivery Point Reference Number (UDPRN).

Storing the UDPRN lets you retrieve the most recent information for an address, and test whether an address has been deleted.

UDPRNs are an eight digit unique numeric code (e.g. 25962203) for any premise on the Postcode Address File, Royal Mail's database of UK addresses. The API searches PAF first, then Not Yet Built if your key is licensed for it. A UDPRN on neither dataset returns 404.

Each address returned costs a lookup.

Testing

We provide test UDPRNs that yield both successful and unsuccessful responses. They are:

• 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 requests undergo the usual authentication and restriction rules. They surface any issues during implementation and do not cost you a lookup.

Returns the address for a multiple occupancy household, identified by its UMPRN (Multiple Residence Unique ID).

UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset. Your key needs that dataset enabled. Without it, and for any UMPRN we cannot find, the API returns 404.

Pricing

Per lookup charges apply. We do not charge for empty responses.

Testing

We provide test UMPRNs that yield both successful and unsuccessful responses. They are:

• 0 Returns a successful UMPRN lookup response 2000
• -1 Returns "UMPRN not found", error 4046
• -2 Returns "no lookups remaining", error 4020
• -3 Returns "daily (or individual) lookup limit breached", error 4021

Test requests undergo the usual authentication and restriction rules. They surface any issues during implementation and do not cost you a lookup.

Returns the closest matching address for a freeform address input, with Match Level indicators describing how closely each element of the suggested address matches the input. The more impaired the input address, the harder it is to cleanse.

A cleanse that returns a match costs a lookup. A no-match response is free.

Confidence Score

Each incorrect, missing or misspelled element subtracts from the overall confidence score.

Deciding on an Acceptable Confidence Score Threshold

Inputs differ widely between address cleanse projects. Within a project, though, they tend to repeat the same errors. Some datasets are keyed in by hand and prone to typos. Others have a persistently missing datapoint such as organisation name or postcode. There is no absolute Confidence Score threshold. Set the acceptable score project by project, based on the systematic errors in the data and your business goals.

To set a threshold, load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top to bottom shows matches from best to worst. As you reach the lower quality searches you can judge roughly:

• Which confidence scores indicate ambiguous 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. You may need to match only up to the thoroughfare or building name, or accurate organisation names may matter.

Returns a list of UK addresses matching the query, ordered by relevance score. limit defaults to 10 and caps at 100. page defaults to 0.

You may only extract a single address from each request. To extract multiple addresses, you must perform an individual request for each address.

If the query is a valid postcode, the API returns the whole address list for that postcode and raises the limit to 100. Use page to reach the rest of a postcode holding more than 100 premises. You cannot page beyond 10,000 results.

Your key needs at least one of PAF, Multiple Residence, Not Yet Built, PAF Alias, PAF Welsh, AddressBase or AddressBase Premium. Without one the request is rejected.

A request that returns at least one address costs a lookup. Empty result sets are free.

Reverse Geocoding

Return the addresses around a point with the lon= and lat= querystring arguments. The search radius is 100m and the API sorts addresses by distance from the point.

Filters

Narrow your results by adding filters to your query string that 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, the API returns an empty result set and charges no lookup.

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 8 terms is allowed across all filters.

Biases

You can boost address results that correspond with a given address attribute. All bias searches are prefixed with bias_.

Biased searches, unlike filtered searches, still allow unmatched addresses to appear. They 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 is applied.

You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Prefer results in the 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 is 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.

Using a filter means a postcode mismatch returns no results and costs no lookup.

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 requests undergo the usual authentication and restriction rules. They surface any issues during implementation and do not cost you a lookup.

Returns place suggestions for a query, ranked by relevance. Places cover countries, administrative areas, capitals and other administrative seats.

Implementing Place Autocomplete

Retrieving a full place takes two requests:

1. Fetch suggestions from /places
2. Fetch the place using the id on a suggestion

A query returns at most 10 suggestions. An empty query returns an empty result set. Show users the descriptive_name. The API drops suggestions that share one, so each name in a response identifies a single place.

Rate Limiting and Cost

The rate limit is 3,000 requests per 5 minutes.

/places does not decrement your lookup balance, but resolving a suggestion to a full place does. We rate limit and then suspend integrations that repeatedly call /places without resolving.

Returns the full place for a place ID taken from a /places suggestion.

On top of the fields carried by the suggestion, the response adds coordinates, language and the underlying dataset record.

Each request decrements your lookup balance. An unknown ID returns 404.

Returns public information on an API Key: whether it can be used right now (available), the search contexts the key is licensed for (contexts) and the context that best matches the caller's IP address (context).

The endpoint accepts API Keys (beginning ak_) and sub-licensed keys (beginning sl_), and needs no user_token.

A key that exists but cannot be used, because it has no lookups left or has breached a limit, returns 200 with "available": false. An unknown or malformed key returns an error.

Supply a valid user_token and the endpoint returns the key's private details instead, as GET /keys/{key}/details does. A user_token that does not own the key is rejected.

Returns private data on a key: remaining lookups, licensed datasets, usage limits, notification settings and the search contexts the key can serve.

Updates a key's settings and returns its private details. Only the fields you send change. A key on an unlimited plan ignores changes to datasets, daily_limit and monthly_limit.