Documentation

Autocomplete

Use /autocomplete to retrieve address suggestions for a partial address string.

Implementing Autocomplete

Retrieving addresses using 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

Note that the first step is free but rate limited, however the second step will decrement your lookup balance.


Address Autocomplete

GET /autocomplete/addresses?query=

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

Query Parameters

PropertyDescription
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 Specify 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=
postcode_outward Comma separated list of outward codes with which to restrict result set.. E.g. postcode_outward=sw1a, postcode_outward=tr8,le18

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 then UMPRN of a Multiple Residence household

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.

Authentication

When using the autocomplete API, low request latency is essentially in delivering a speedy list of suggestions to the user. For this reason we recommend using querystring authentication (i.e. api_key=foo) rather than HTTP Header authentication (i.e. Authorization: IDEALPOSTCODES api_key="foo"). The latter will incur additional latency as most browsers will trigger a preflight OPTIONS request for each key press.

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

Free. However subsequent searches require a paid request to retrieve the complete address.

Data Source

Royal Mail (Postcode Address File)