Address Search API

Addresses

An address instance resource represents a single UK address.


Address Search

GET /addresses?query=

Returns a list of addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).

If a valid postcode is passed as the query string, the entire address list for that postcode is returned as the result. Note, in these cases, limit parameter is ignored and fixed at 100. If your key is configured to return Multiple Residence data, you may need to query more pages to return the entire list as more than 100 delivery points or residences may be returned.

Query Parameters

Property Description
api_key Required unless authenticating with Authorization HTTP Header
query Specifies the address you wish to query. Query can be shortened to q=. As of September 2020, this attribute is no longer required. It is possible to search other parameters exclusively (such as filters)
limit Specifies the upper limit on the number of address results to be returned. Max is 100 addresses. Query can be shortened to l=
page Specifies the page of results to be returned. Query can be shortened to p=
filter Comma separated whitelist of address elements to return. E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response
licensee Only required if you are using a Sublicensing Key. This parameter will associate the request with your Licensee

Filters

You can strictly narrow your result by adding filters to your query string 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. Can be combined with query to perform a postcode + building number/name search. E.g. /addresses?postcode=SW1A2AA&q=10
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
uprn Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted
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/addresses?api_key=iddqd&query=10%20downing%20street%20london
 # Or in your terminal
curl -k -G 'https://api.ideal-postcodes.co.uk/v1/addresses' \
    -d 'api_key=iddqd' \
    --data-urlencode 'query=10 downing street london'

Response

{
  "result": {
    "total": 2,
    "limit": 10,
    "page": 0,
    "hits": [
        {
            "postcode": "SW1A 2AA",
            "post_town": "LONDON",
            "dependant_locality": "",
            "double_dependant_locality": "",
            "thoroughfare": "Downing Street",
            "dependant_thoroughfare": "",
            "building_number": "10",
            "building_name": "",
            "sub_building_name": "",
            "po_box": "",
            "department_name": "",
            "organisation_name": "Prime Minister & First Lord Of The Treasury",
            "udprn": 23747771,
            "umprn": "",
            "postcode_type": "L",
            "su_organisation_indicator": "",
            "delivery_point_suffix": "1A",
            "postcode_inward": "2AA",
            "postcode_outward": "SW1A",
            "line_1": "Prime Minister & First Lord Of The Treasury",
            "line_2": "10 Downing Street",
            "line_3": "",
            "premise": "10",
            "longitude": -0.12767,
            "latitude": 51.503541,
            "eastings": 530047,
            "northings": 179951,
            "country": "England",
            "traditional_county": "Greater London",
            "administrative_county": "",
            "postal_county": "London",
            "county": "London",
            "district": "Westminster",
            "ward": "St James's",
            "uprn": "100023336956"
        },
        {
            "postcode": "WC1N 1LX",
            "post_town": "LONDON",
            "dependant_locality": "",
            "double_dependant_locality": "",
            "thoroughfare": "Grenville Street",
            "dependant_thoroughfare": "",
            "building_number": "",
            "building_name": "Downing Court",
            "sub_building_name": "Flat 10",
            "po_box": "",
            "department_name": "",
            "organisation_name": "",
            "udprn": 26245117,
            "umprn": "",
            "postcode_type": "S",
            "su_organisation_indicator": "",
            "delivery_point_suffix": "1B",
            "postcode_inward": "1LX",
            "postcode_outward": "WC1N",
            "line_1": "Flat 10",
            "line_2": "Downing Court",
            "line_3": "Grenville Street",
            "premise": "Flat 10, Downing Court",
            "longitude": -0.122599,
            "latitude": 51.5234868,
            "eastings": 530342,
            "northings": 182178,
            "country": "England",
            "traditional_county": "Greater London",
            "administrative_county": "",
            "postal_county": "London",
            "county": "London",
            "district": "Camden",
            "ward": "Bloomsbury",
            "uprn": "5027008"
        }
        ]
    },
    "code": 2000,
    "message": "Success"
}

The result object contains the following attributes.

  • total The total number of addresses matching your search query.
  • limit The maximum number of addresses returned by this request.
  • page The current page number of results. If the total number of addresses exceeds the limit, there will be total / limit pages you can search through.
  • hits An array of address objects ordered by search relevance.

JavaScript Example


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

const client = new Client({ api_key: "iddqd" });

await client.lookupAddress({ query: "10 Brompton Rd"});

JavaScript client method documentation

Testing

  • ID1 1QD Returns a successful query response 2000
  • ID1 KFA Returns an empty query response 2000
  • ID1 CLIP Returns "no lookups remaining" error 4020
  • ID1 CHOP Returns "daily (or individual) lookup limit breached" error 4021

Test requests will undergo usual authentication and restriction rules (individual and daily lookup limits) to surface any problems you may have during implementation. However, it will not count towards a postcode lookup on your key.

Search Methods

By Postcode and Building Name or Number

Search by postcode and building attribute with the postcode filter and query argument. E.g. For "SW1A 2AA Prime Minister" /v1/addresses?postcode=sw1a2aa&q=prime minister.

The advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned.

By UPRN

Search by UPRN using the uprn filter and excluding the query argument. E.g. /v1/addresses?uprn=100.

Notes

This is not an address autocomplete method. Each request that returns an address incurs a lookup charge.

If a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.

Pricing

Per lookup charges apply. Queries which find no match are not charged.


UDPRN (Address ID) to Address

GET /addresses/:udprn

Returns an address identified via its Unique Delivery Point Reference Number (UDPRN).

UDPRNs are an eight digit unique numeric code (e.g. 25962203) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database.

You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a "decommissioned" address.

Query Parameters

Property Description
api_key Required unless authenticating with Authorization HTTP Header
filter Comma separated whitelist of address elements to return. E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response
licensee Only required if you are using a Sublicensing Key. This parameter will associate the request with your Licensee

Examples

Request

https://api.ideal-postcodes.co.uk/v1/addresses/0?api_key=iddqd

 # Or in your terminal
curl -k -G https://api.ideal-postcodes.co.uk/v1/addresses/0 \
        -d "api_key=iddqd"

Response

{
    "result": {
        "postcode": "ID1 1QD",
        "postcode_inward": "1QD",
        "postcode_outward": "ID1",
        "post_town": "LONDON",
        "dependant_locality": "",
        "double_dependant_locality": "",
        "thoroughfare": "Barons Court Road",
        "dependant_thoroughfare": "",
        "building_number": "2",
        "building_name": "",
        "sub_building_name": "",
        "po_box": "",
        "department_name": "",
        "organisation_name": "",
        "udprn": 0,
        "umprn": "",
        "postcode_type": "S",
        "su_organisation_indicator": "",
        "delivery_point_suffix": "1G",
        "line_1": "2 Barons Court Road",
        "line_2": "",
        "line_3": "",
        "premise": "2",
        "country": "England",
        "county": "Greater London",
        "administrative_county": "",
        "postal_county": "",
        "traditional_county": "Greater London",
        "district": "Hammersmith and Fulham",
        "ward": "North End",
        "longitude": -0.208644362766368,
        "latitude": 51.4899488390558,
        "eastings": 524466,
        "northings": 178299,
        "uprn": "2"
    },
    "code": 2000,
    "message": "Success"
}

A single address object is returned in the result attribute.

JavaScript Example


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

const client = new Client({ api_key: "iddqd" });

await client.lookupUdprn({ udprn: 0 });

JavaScript client method documentation

Testing

To test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request. They are the following

  • 0 Returns a successful UDPRN lookup response 2000
  • -1 Returns "UDPRN not found" error 4044
  • -2 Returns "no lookups remaining" error 4020
  • -3 Returns "daily (or individual) lookup limit breached" error 4021

Test requests will undergo usual authentication and restriction rules (individual and daily lookup limits) to surface any problems you may have during implementation. However, it will not count towards a postcode lookup on your key.

Pricing

Per lookup charges apply. Empty responses are not charged.

Data Source

Royal Mail (Postcode Address File), Ordnance Survey (Code-Point Open)


Address Model Overview

The Address Model or Object has the following attributes: