Skip to main content

Find Address

GET 
/autocomplete/addresses

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.

HeaderDescription
X-RateLimit-LimitThe maximum number of requests that can be made in 5 minutes
X-RateLimit-RemainingThe remaining requests within the current rate limit window
X-RateLimit-ResetThe 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.

Request​

Query Parameters

    api_key API Key
    query string

    Specifies the address you wish to query. Query can be shortened to q=

    context Context
    limit int32

    Possible values: >= 1 and <= 100

    Default value: 10

    Limits number of address suggestions unless a postcode is detected. In this instance entire list of addreses for that postcode is returned.

    postcode_outward Postcode Outward
    postcode Postcode
    postcode_area Postcode Area
    postcode_sector Postcode Sector
    post_town Post Town
    uprn UPRN
    country Country
    postcode_type Country
    su_organisation_indicator SU Organisation Indicator
    box Box
    bias_postcode_outward Bias Postcode Outward
    bias_postcode Bias Postcode
    bias_postcode_area Bias Postcode Area
    bias_postcode_sector Bias Postcode Sector
    bias_post_town Bias Post Town
    bias_thoroughfare Bias Thoroughfare
    bias_country Bias County
    bias_lonlat Bias Lon/Lat
    bias_ip Bias query by Geolocation of IP

    Possible values: [true]

Responses​

Success

Response Headers
  • X-RateLimit-Limit number

    The maximum number of requests that can be made in 5 minutes

  • X-RateLimit-Remaining number

    The remaining requests within the current rate limit window

  • X-RateLimit-Reset number

    The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds.

Schema
    result objectrequired
    hits object[]required
  • Array [
    • oneOf
    id IDrequired

    Global unique internally generated identifier for an address

    suggestion stringrequired

    Address Suggestion to be displayed to the user

    urls objectrequired
  • ]
    • code int32required

    Possible values: [2000]

    message stringrequired

    Possible values: [Success]

Loading...