Address Autocomplete API

The address finder and autocompletion API provides a JSON interface to extract address suggestions for a complete or partial address query.

This API can be used to power realtime address finders and autofills.

If you wish to quickly add address autocompletion on your address forms, see our Address Autocomplete plugin and associated demos.

Implementing Address Autocomplete

Retrieving addresses using Address Autocomplete is a 2 step process.

  1. Retrieve partial address suggestions via /autocomplete/addresses
  2. Retrieve the entire address by following the URL provided by the suggestion

Step 2 will decrement your lookup balance.

Please note, this API is not intended to be a free standalone resource.


Address Autocomplete

GET /autocomplete/addresses?query=

Returns a list of address suggestions that match the query ordered by relevance score.

Query Parameters

Property Description
api_key Required unless authenticating with Authorization HTTP Header
query Required. Specifies the address you wish to query. Query can be shortened to q=
licensee Only required if you are using a sublicensed key. This parameter will associate the request with your licensee
limit Specifies the maximum number of suggestions to retrieve. Range must be 1-100. By default the limit is 10, unless a postcode is queried (then all addresses at that postcode will be returned). Limit can be shortened to l=

Filters

You can strictly narrow your result by adding filters to your querystring 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 maximum of 5 terms are allowed across all filters.

Property Description
postcode_outward Filter by outward code
postcode Filter by postcode.
postcode_area Filter by postcode area, the first one or two non-numeric characters of a postcode. E.g. The postcode area of SW1A 2AA and N1 6RT are SW and N respectively
postcode_sector Filter by postcode sector, the outward code plus first numeric of the inward code. E.g. The postcode sector of SW1A 2AA is SW1A 2
post_town Filter by town
thoroughfare Filter by street name
country Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man. See our guide on supported territories for more information

Request

https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&query=10%20downing
 # Or in your terminal
curl -k -G 'https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses' \
    -d 'api_key=iddqd' \
    --data-urlencode 'query=10 downing'

Response

{
    "result": {
        "hits": [
            {
                "suggestion": "10 Downings, London, E6",
                "urls": {
                    "udprn": "/v1/udprn/7944730"
                },
                "udprn": 7944730
            },
            {
                "suggestion": "10 Downing Grove, Hull, HU9",
                "urls": {
                    "udprn": "/v1/udprn/11168744"
                },
                "udprn": 11168744
            },
            {
                "suggestion": "10 Downing Path, Slough, SL2",
                "urls": {
                    "udprn": "/v1/udprn/22341024"
                },
                "udprn": 22341024
            },
            {
                "suggestion": "10 Downing Drive, Leicester, LE5",
                "urls": {
                    "udprn": "/v1/udprn/13209396"
                },
                "udprn": 13209396
            },
            {
                "suggestion": "10 Downing Street, Preston, PR1",
                "urls": {
                    "udprn": "/v1/udprn/19531519"
                },
                "udprn": 19531519
            },
            {
                "suggestion": "10 Downing Avenue, Guildford, GU2",
                "urls": {
                    "udprn": "/v1/udprn/10093397"
                },
                "udprn": 10093397
            },
            {
                "suggestion": "10 Downing Close, Ipswich, IP2",
                "urls": {
                    "udprn": "/v1/udprn/11520985"
                },
                "udprn": 11520985
            },
            {
                "suggestion": "10 Downing Close, Harrow, HA2",
                "urls": {
                    "udprn": "/v1/udprn/10445693"
                },
                "udprn": 10445693
            },
            {
                "suggestion": "10 Downing Avenue, Newcastle, ST5",
                "urls": {
                    "udprn": "/v1/udprn/23547463"
                },
                "udprn": 23547463
            },
            {
                "suggestion": "10 Downing Street, Llanelli, SA15",
                "urls": {
                    "udprn": "/v1/udprn/21302857"
                },
                "udprn": 21302857
            }
        ]
    },
    "code": 2000,
    "message": "Success"
}
Property Description
suggestion string Suggestion for your given query, represented as a partial address
urls.udprn string URL to retrieve the entire details for a given address suggestion
urls.umprn string Optionally returned field, to retrieve the entire details for a suggested Multiple Residence household
udprn number Represents the UDPRN of a premise
umprn number Optionally returned field, representing the UMPRN of a Multiple Residence household

JavaScript Example

Step 1. Retrieve a list of suggestions


const { Client } = require("@ideal-postcodes/core-node");
const client = new Client({});

// Autocomplete using a lower level Resource method
const response = await client.autocomplete.list({ 
    query: {
        query: "221b bake",
        api_key: "iddqd"
    }
});

response.body.result.hits;

Step 2. Resolve a suggestion retrieved above for a full address


const { Client } = require("@ideal-postcodes/core-node");
const client = new Client({ api_key: "iddqd" });
const udprn = 17646242;

// Retrieve an address by UDPRN
await client.lookupUdprn({ udprn });

JavaScript client method documentation

Testing

ID1 1QD will return address suggestions, that when retrieved via /udprn/:id will not affect your balance.

Notes

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.

Querying with a Postcode

  • If a postcode is passed as a query, all addresses for that postcode will be listed as the result if the limit parameter is not supplied
  • If a postcode forms only part of the query, your autocomplete results will be filtered by that postcode

Querying Multiple Residence

For Multiple Residence enabled keys, any Multiple Residence households will also return a UMPRN id, which can be retrieved with the /umprn/:id endpoint. Note that Multiple Residence households will always have a parent premise with a UDPRN, and a single UDPRN premise may have many Multiple Residence households with different UMPRNs. For instance:

{
    "result": {
        "hits": [
            {
                "suggestion": "10 Downings, London, E6",
                "urls": {
                    "udprn": "/v1/udprn/7944730"
                },
                "udprn": 7944730
            },
            {
                "suggestion": "10 Downing Grove, Hull, HU9",
                "urls": {
                    "udprn": "/v1/udprn/11168744",
                    "umprn": "/v1/umprn/882919"
                },
                "udprn": 11168744,
                "umprn": 882919
            }
        ]
    },
    "code": 2000,
    "message": "Success"
}

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.

Header Description
X-RateLimit-Limit The maximum number of requests that can be made in 5 minutes
X-RateLimit-Remaining The remaining requests within the current rate limit window
X-RateLimit-Reset The 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, subsequent searches require a paid request (e.g. a UDPRN search). This paid request, will yield the complete address.

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.

Data Source

Royal Mail (Postcode Address File).