Skip to main content

Extract Addresses

GET 
/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.

Request​

Responses​

Success