Skip to main content

Find Address

GET 
/autocomplete/addresses

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:

  1. Fetch address suggestions with /autocomplete/addresses
  2. 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.

Request​

Query Parameters

    api_key string

    API Key

    Your unique identifier that allows access to our APIs.

    Begins ak_. Available from your dashboard

    Example: ak_test
    query string

    Possible values: <= 150 characters

    Address Query

    The partial address string entered by the user to autocomplete.

    Example: 10 downing street lo
    context string

    Context

    Limits search results, typically within g country.

    Example: GBR
    limit int32

    Possible values: >= 1 and <= 100

    Default value: 10

    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

    Example: 5
    bias_lonlat string

    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

    Example: -2.095,57.15,100
    bias_ip string

    Possible values: [true]

    Bias by Geolocation of IP

    Biases search based on approximate geolocation of IP address.

    Set bias_ip=true to enable.

    box string

    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.

    Example: 2.095,57.15,-2.096,57.14
    postcode_outward string

    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.

    Example: SW1A
    postcode string

    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.

    Example: SW1A 2AA
    postcode_area string

    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.

    Example: SW
    postcode_sector string

    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

    Example: SW1A 2
    post_town string

    Filter by Town or City

    Restrict addresses to matching town, city or other locality identifier.

    Example: London
    uprn integer

    Filter by UPRN

    Does not accept comma separated terms. Only a single term is permitted

    Example: 100023336956
    country string

    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.

    Example: England
    postcode_type string

    Filter by Postcode Type

    Filter by Postcode Type. Useful for separating organisational and residential addresses

    su_organisation_indicator string

    Filter by Organisation Indicator

    Useful for separating organisational and residential addresses

    Example: Y
    bias_postcode_outward string

    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

    Example: SW1A
    bias_postcode string

    Bias by postcode Boost addresses which match postcode. Can be combined with query to perform a postcode and building number or name search.

    Example: SW1A2AA
    bias_postcode_area string

    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

    Example: SW
    bias_postcode_sector string

    Bias by Postcode Sector

    Boost postcode sector matches. The postcode sector comprises the outward code plus first numeric of the inward code.

    Example: SW1A 2
    bias_post_town string

    Bias by Town or City

    Biases results to matching town, city or other locality name.

    bias_thoroughfare string

    Bias by Street

    Bias by street or thoroughfare name.

    bias_country string

    Bias by Country

    Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.

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