Find Address

GET/v1/autocomplete/addresses

Returns address suggestions for a partial address, ordered by relevance. Use it to power real-time address autofill.

Consider our address autocomplete JavaScript libraries, which add address lookup to a form without calling 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 decrements your lookup balance.

Step 1 is not a free standalone resource. We rate limit and then suspend integrations that repeatedly make autocomplete requests without a paid Step 2 request.

Context

context limits the search, usually to a single country. It defaults to GBR, and an unrecognised context falls back to that default. If your key is not licensed for the datasets covering the context, the request is rejected.

Querying a full postcode within a supported context returns the entire address list for that postcode.

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.

Filters combine with AND logic, for instance su_organisation_indicator=Y&postcode_area=n. The maximum is 8 filter terms.

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 favour 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 avoid integration issues.

Rate Limiting and Cost

The default rate limit is 3,000 requests per 5 minutes, counted per key and IP address. The X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers report where you stand.

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 lead to rate limiting or suspension.

Query parameters

api_key string optional: API Key

Your unique identifier that allows access to our APIs.

Begins ak_. Available from your dashboard.
Example ak_test
query string optional: Address Query

The partial address string entered by the user to autocomplete.
Example 10 downing street lo
dataset array optional: Filter by Dataset

Comma-separated list of datasets to search within.

Filters results to only include addresses from the specified datasets. Useful for keys with multiple overlapping datasets enabled (e.g. paf and abp).
Example paf,nyb
context string optional: Context

Limits search results, typically within a country.
Example GBR
limit integer optional: Limit

Specifies the maximum number of records to retrieve.

By default the limit is 10. Requesting a larger result set adds latency.
Format int32Default 10Example 5
bias_lonlat string optional: Bias by Geolocation

Bias search to a geospatial circle determined by an origin and radius in metres. 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 optional: Bias by Geolocation of IP

Biases search based on approximate geolocation of IP address.

Set bias_ip=true to enable.
Enum
"true"
box string optional: Filter by Bounding Box

Restrict search to a geospatial box determined by the "top-left" and "bottom-right" geolocations.

Supply 4 comma separated values ordered top_left_lon,top_left_lat,bottom_right_lon,bottom_right_lat. The top-left longitude must be less than the bottom-right longitude, and the top-left latitude greater than the bottom-right latitude. A box which fails either check is ignored.

Only one geospatial box can be provided.
Example -2.096,57.15,-2.095,57.14
postcode_outward string optional: 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 optional: 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 optional: 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 optional: 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 optional: Filter by Town or City

Restrict addresses to matching town, city or other locality identifier.
Example London
uprn integer optional: Filter by UPRN

Does not accept comma separated terms. Only a single term is permitted.
Example 100023336956
country string optional: Filter by country

Filters by country name.

In the GBR context, the country is never United Kingdom. It is England, Scotland, Wales, Northern Ireland, Jersey, Guernsey or Isle of Man.
Example England
postcode_type string optional: Filter by Postcode Type

Useful for separating organisational and residential addresses.
su_organisation_indicator string optional: Filter by Organisation Indicator

Useful for separating organisational and residential addresses.
Example Y
bias_postcode_outward string optional: Bias by Outward Code Boosts addresses with a matching outward code. The outward code is the first half of a postcode. For instance, the outward code of SW1A 2AA is SW1A.
Example SW1A
bias_postcode string optional: 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 optional: Bias by Postcode Area

Boosts if the first one or two non-numeric characters of a postcode match

The postcode areas of SW1A 2AA and N1 6RT are SW and N respectively.
Example SW
bias_postcode_sector string optional: 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 optional: Bias by Town or City

Biases results to matching town, city or other locality name.
bias_thoroughfare string optional: Bias by Street

Bias by street or thoroughfare name.
bias_country string optional: Bias by Country

Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
postal_code string optional: Filter by postal code

Restrict results to addresses with a matching full postal code. Case, spaces and hyphens are ignored. For US addresses the full postal code is the nine digit ZIP+4 (941021234); filter on postal_code_3 for a five digit ZIP. For UK addresses use postcode.
Example 94102-1234
postal_code_2 string optional: Filter by postal code prefix

Restrict results to addresses whose postal code starts with the given segment. For US addresses this is the three digit ZIP prefix (sectional center), e.g. 941 for San Francisco.
Example 941
postal_code_3 string optional: Filter by short postal code

Restrict results to addresses with a matching short postal code. For US addresses this is the five digit ZIP code.
Example 94102
city string optional: Filter by city

Restrict results to addresses in the named city, town or locality. Case, spaces and accents are ignored, so San Francisco and sanfrancisco match the same addresses. For UK addresses use post_town.
Example San Francisco
state string optional: Filter by state

Restrict results to addresses in the named state, province or region, e.g. California. Case and spaces are ignored.
Example California
state_code string optional: Filter by state code

Restrict results to addresses with a matching state or region code, e.g. the two letter USPS state abbreviation CA. Case is ignored.
Example CA
bias_postal_code string optional: Bias by postal code

Boost addresses with a matching full postal code (nine digit ZIP+4 for US addresses). Unmatched addresses still appear, ranked lower.
Example 94102-1234
bias_postal_code_2 string optional: Bias by postal code prefix

Boost addresses whose postal code starts with the given segment (three digit ZIP prefix for US addresses).
Example 941
bias_postal_code_3 string optional: Bias by short postal code

Boost addresses with a matching short postal code (five digit ZIP for US addresses).
Example 94102
bias_city string optional: Bias by city

Boost addresses in the named city, town or locality. Case, spaces and accents are ignored. For UK addresses use bias_posttown.
Example San Francisco
bias_state string optional: Bias by state

Boost addresses in the named state, province or region.
Example California
bias_state_code string optional: Bias by state code

Boost addresses with a matching state or region code, e.g. CA.
Example CA
is_pobox string optional: Filter by PO Box

true restricts results to PO Box addresses; false excludes them. For US addresses this is derived from the USPS record type (P).
Example true
Enum
"true"
"false"
is_business string optional: Filter by business address

true restricts results to business addresses; false excludes them. For US addresses this is derived from the USPS record type (F, a firm record).
Example true
Enum
"true"
"false"

Response

result contains a hits array of address suggestions. Each suggestion includes an ID for resolving the full address in a follow-up request. The array sits inside the standard { result, code, message } envelope; see the API reference for the wrapper format.

result object
- hits object[]
  - AddressSuggestion
    Represents an address suggestion for any address in the world
    id string
    Global unique internally generated identifier for an address
    suggestion string
    Address Suggestion to be displayed to the user
    urls object
    Always an empty object ({}). Retrieve the full address with id
  - UkAddressSuggestion
    Represents a possible address given an autocomplete query.
    
    UK Address Suggestions will return a UDPRN attribute if it references a deliverable endpoint found on Royal Mail's Postcode Address File dataset.
    
    UK Address Suggestion will return a UMPRN if it references a multiple occupancy premise found on Royal Mail's Multiple Residence dataset.
    id string
    Global unique internally generated identifier for an address
    suggestion string
    Address suggestion for a given query.
    udprn integer
    UDPRN stands for 'Unique Delivery Point Reference Number'. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires.
    
    Up to 8-digit numeric code.
    
    A new UDPRN is automatically assigned to each new Delivery Point added to PAF.
    Format
    int32
    umprn integer optional
    Optionally returned field, representing the UMPRN of a Multiple Residence household
    Format
    int32
    urls object
    udprn string
    URL to retrieve the entire details for a given address suggestion by the UDPRN
    umprn string optional
    Optionally returned field, to retrieve the entire details for a suggested Multiple Residence household

Request

https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=ak_test&query=10 downing

curl -G 'https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses' \
  -d 'api_key=ak_test' \
  --data-urlencode 'query=10 downing'

const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?' +
  new URLSearchParams({
    api_key: 'ak_test',
    query: '10 downing',
  })
);

const { result } = await response.json();

import requests

response = requests.get(
    "https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses",
    params={
        "api_key": "ak_test",
        "query": "10 downing",
    },
)
result = response.json()["result"]

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses")
uri.query = URI.encode_www_form(api_key: "ak_test", query: "10 downing")
result = JSON.parse(Net::HTTP.get(uri))["result"]

<?php
$response = file_get_contents(
  "https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?" .
  http_build_query([
    "api_key" => "ak_test",
    "query" => "10 downing",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "result": {
    "hits": [
      {
        "id": "paf_23747771",
        "suggestion": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A",
        "udprn": 23747771,
        "urls": {
          "udprn": "/v1/udprn/23747771"
        }
      },
      {
        "id": "paf_26245117",
        "suggestion": "Flat 10, Downing Court, Grenville Street, London, WC1N",
        "udprn": 26245117,
        "urls": {
          "udprn": "/v1/udprn/26245117"
        }
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}

API Usage

Context

Query Filters

Address Bias

Suggestion Format

Rate Limiting and Cost

Query parameters​

Response​

Query parameters

Response