Find Address
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:
- Fetch address suggestions with /autocomplete/addresses
- 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.
Query parameters
API Key
Your unique identifier that allows access to our APIs.
Begins ak_. Available from your dashboard
Address Query
The partial address string entered by the user to autocomplete.
Filter by Dataset
Comma-separated list of datasets to search within.
Filters autocomplete results to only include addresses from the specified datasets.
Context
Limits search results, typically within a country.
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
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
Bias by Geolocation of IP
Biases search based on approximate geolocation of IP address.
Set bias_ip=true to enable.
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.
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
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.
Response
Success
Example response
{
"result": {
"hits": [
{
"id": "usps_V210079628|10||3797",
"suggestion": "10 Downing St, Montpelier, VT, 05602",
"urls": null
}
]
}
}