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.
Query parameters
API Key
Your unique identifier that allows access to our APIs.
Begins ak_. Available from your dashboard
Specifies the address you wish to query.
Limit
Specifies the maximum number of records to retrieve.
By default the limit is 10. Requesting a larger result set will result in more latency
Page
0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0.
A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).
Restrict Result Fields
Comma separated whitelist of address elements to return.
E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response
Longitude
Longitude query for reverse geocoding.
An accompanying latitude (lat=) query must be submitted for a valid reverse geocode query.
Latitude
Latitude query for reverse geocoding.
An accompanying longitude (lon=) query must be submitted for a valid reverse geocode query.
Filter by Outward Code
Restrict result set to addresses with a matching outward code.
The outward code is the first half of a postcode. E.g. the outward code for SW1A 2AA is SW1A.
Filter by postcode Restrict result set to matching postcodes only. Can be combined with query to perform a postcode and building number or name search.
Filter by Postcode Area
Postcode area represents the first one or two non-numeric characters of a postcode. E.g. the postcode area of SW1A 2AA is SW.
Can be combined with query to perform a postcode and building search.
Filter by Postcode Sector
Postcode sector is the outward code plus first numeric of the inward code. E.g. postcode sector of SW1A 2AA is SW1A 2
Filter by Town or City
Restrict addresses to matching town, city or other locality identifier.
Filter by UPRN
Does not accept comma separated terms. Only a single term is permitted
Filter by country
Filters by country name.
In the context of GBR, country values are not United Kingdom. Instead they are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
Filter by Postcode Type
Filter by Postcode Type. Useful for separating organisational and residential addresses
Filter by Organisation Indicator
Useful for separating organisational and residential addresses
Filter by Bounding Box
Restrict search to a geospatial box determined by the "top-left" and "bottom-right" gelocations.
Only one geospatial box can be provided.
Bias by Outward Code Boosts addresses with a matching outward code. Outward code is the first have of a postcode. For instance, the outward code of SW1A 2AA is SW1A
Bias by postcode Boost addresses which match postcode. Can be combined with query to perform a postcode and building number or name search.
Bias by Postcode Area
Boosts if the first one or two non-numeric characters of a postcode match
The postcode area of SW1A 2AA and N1 6RT are SW and N respectively
Bias by Postcode Sector
Boost postcode sector matches. The postcode sector comprises the outward code plus first numeric of the inward code.
Bias by Town or City
Biases results to matching town, city or other locality name.
Bias by Street
Bias by street or thoroughfare name.
Bias by Country
Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
Bias by Geolocation
Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is 50000. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres] Only one geospatial bias may be provided
** Tags ** A comma separated list of tags to query over.
Useful if you want to specify the circumstances in which the request was made.
If multiple tags are specified, the response will only comprise of requests for which all the tags are satisfied - i.e. searching "foo,bar" will only query requests which tagged both "foo" and "bar".
Response
Success
Example response
{
"result": {
"hits": [
{
"id": "paf_8387729",
"country": "England",
"line_1": "Prime Minister & First Lord of Treasury",
"line_2": "10 Downing Street",
"post_town": "London",
"postcode": "SW1A 2AA",
"county": "London",
"udprn": 23747771,
"umprn": 983729,
"postcode_outward": "SW1A",
"postcode_inward": "2AA",
"thoroughfare": "Downing Street",
"building_number": "10",
"sub_building_name": "Flat 1",
"po_box": "100",
"organisation_name": "Prime Minister & First Lord Of The Treasury",
"su_organisation_indicator": "Y",
"delivery_point_suffix": "1A",
"premise": "10",
"postal_county": "London",
"traditional_county": "Greater London",
"district": "Westminster",
"ward": "St. James'",
"longitude": 0.002823,
"latitude": 52.938278,
"eastings": 9382,
"northings": 123932
}
],
"limit": 10
}
}