Postcode Lookup API

The postcode lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power postcode lookup driven address searches, like our postcode finder plugin.

Experiment with the HTTP API with our JavaScript library below.

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

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

await client.postcodes.retrieve("ID1 1QD", { query: { api_key } });

🧪 Experiment

This API models postcodes as a HTTP resource. The above example provides a thin JavaScript abstration and more control over the HTTP request and response. The JavaScript client also provides a number of terser helper methods like client.lookupPostcode

If you wish to quickly add postcode lookup driven address finder on your page, see our postcode lookup plugin and associated demos.

Postcodes Resource

The postcodes resource allows retrieval of addressing data given a postcode.

Postcode to Addresses

GET /postcodes/:postcode

Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.

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 sublicensed key. This parameter will associate the request with your licensee

Request

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

# Or in your terminal
curl -G -k https://api.ideal-postcodes.co.uk/v1/postcodes/ID11QD \
 -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": 25962203,
        "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
    },
    {
        "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": "59",
        "building_name": "",
        "sub_building_name": "",
        "po_box": "",
        "department_name": "",
        "organisation_name": "ID Consulting Limited",
        "udprn": 25946509,
        "umprn": "",
        "postcode_type": "S",
        "su_organisation_indicator": "Y",
        "delivery_point_suffix": "1N",
        "line_1": "ID Consulting Limited",
        "line_2": "59 Barons Court Road",
        "line_3": "",
        "premise": "59",
        "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
    }],
    "code": 2000,
    "message": "Success"
}

Property	Description
`result`	`array` Contains an array of address objects representing every address in the postcode.

JavaScript Example


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

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

await client.lookupPostcode({ postcode: "ID1 1QD"});

JavaScript client method documentation

Postcode not found

Please note: For postcodes that do not exist, your key is not charged, the API returns a 404 response with a response body:

{
    "code": 4040,
    "message": "Postcode not found"
}

Testing

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

ID1 1QD Returns a successful postcode lookup response 2000
ID1 KFA Returns "postcode not found", error 4040
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.

Multiple Residence Dataset & Pagination

For keys which use the Multiple Residence dataset, there are a small number of postcodes which yield more than Royal Mail's maximum allowed return (of 100 addresses) per request. Multiple Residence data users have the option of paginating postcode queries if the limit is reached.

Multiple Residence: Additional Query Parameters

Property	Description
`page`	Optional. 0 indexed indicator of the page of results to receive. Defaults to `0`

Multiple Residence: Additional Response Fields

Property	Description
`page`	`number` Indicates current page number
`total`	`number` Indicates the maximum number of delivery points plus residences at this postcode
`limit`	`number` Maximum number of results per request. Fixed at `100` for this method


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

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

await client.lookupPostcode({
    postcode: "CV4 7AL",
    page: 1
});

Pricing

Per lookup charges are applied. Empty responses are not charged.

Data Source

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

Geolocation to Postcodes

GET /postcodes?lonlat=

Returns a list of postcodes nearest to the specified geolocation.

Query Parameters

Property	Description
`api_key`	Required unless authenticating with Authorization HTTP Header
`lonlat`	Required. Specifies the longitude and latitude of the location you wish to query. Longitude and latitude are decimal and seperated by a single comma with no spaces. E.g. `lonlat=-0.2532632,57.62363744`
`radius`	Determines how close the postcode must be to the location to be returned as a result. Default is 100m. Max is 1000m
`limit`	Specifies the upper limit on the number of postcodes to be returned. Default is 100 postcodes. Max is 150

Request

https://api.ideal-postcodes.co.uk/v1/postcodes?api_key=iddqd&lonlat=-0.20864436,51.48994883

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

Response

{
    "result":[
        {
            "postcode":"W14 9DT",
            "northings":178299,
            "eastings":524466,
            "longitude":-0.208644362766368,
            "latitude":51.4899488390558,
            "distance":0.001025685
        },
        {
            "postcode":"W14 9HP",
            "northings":178250,
            "eastings":524497,
            "longitude":-0.208215353224691,
            "latitude":51.4895016535293,
            "distance":57.992340384
        },
        {
            "postcode":"W14 9DY",
            "northings":178258,
            "eastings":524424,
            "longitude":-0.209263429936064,
            "latitude":51.4895896040625,
            "distance":58.704116372
        },
        {
            "postcode":"W14 9DB",
            "northings":178351,
            "eastings":524497,
            "longitude":-0.208179766575366,
            "latitude":51.4904093484835,
            "distance":60.5508644
        },
        {
            "postcode":"W14 9DS",
            "northings":178315,
            "eastings":524530,
            "longitude":-0.207717383841141,
            "latitude":51.4900785532037,
            "distance":65.981608287
        },
        {
            "postcode":"W14 9HA",
            "northings":178252,
            "eastings":524403,
            "longitude":-0.209567854901873,
            "latitude":51.4895402980472,
            "distance":78.613950761
        },
        {
            "postcode":"W14 9DD",
            "northings":178330,
            "eastings":524392,
            "longitude":-0.209698749475355,
            "latitude":51.4902437086294,
            "distance":80.246098827
        },
        {
            "postcode":"W14 9HQ",
            "northings":178234,
            "eastings":524517,
            "longitude":-0.207933075525138,
            "latitude":51.4893534603178,
            "distance":82.633722864
        },
        {
            "postcode":"W14 9JP",
            "northings":178212,
            "eastings":524461,
            "longitude":-0.208746986755546,
            "latitude":51.4891680625458,
            "distance":87.158307673
        }
    ],
    "code":2000,
    "message":"Success"
}

The result attribute contains an array of postcode objects ordered by distance from the specified geolocation. Each postcode object contains the following data:

Testing

This route is free, so you can test with live data.

Pricing

Free

Data Source

Ordnance Survey (Code-Point Open)

Documentation

Postcode Lookup API

Postcodes Resource

Postcode to Addresses

Query Parameters

Request

Response

JavaScript Example

Postcode not found

Testing

Multiple Residence Dataset & Pagination

Multiple Residence: Additional Query Parameters

Multiple Residence: Additional Response Fields

Pricing

Data Source

Geolocation to Postcodes

Query Parameters

Request

Response

Testing

Pricing

Data Source