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 Postcode Lookup.

Experiment with the HTTP API with our JavaScript library below.

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

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

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

🧪 Experiment

This API models postcodes as a HTTP resource. The above example provides a thin JavaScript abstraction 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`	Optional. 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
`page`	Optional. 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page `0`. A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises). Defaults to `0`
`page`	Return nth page of results. . Default is `0`

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/SW1A2AA \
 -d "api_key=iddqd"

Response

{
    "result":[
        {
            "postcode":"SW1A 2AA",
            "postcode_inward":"2AA",
            "postcode_outward":"SW1A",
            "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",
            "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"
        }
    ],
    "code":2000,
    "message":"Success",
    "total":1,
    "page":0,
    "limit":100
}

Property	Description
`result`	`array` Contains an array of address objects representing every address in the postcode.
`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

JavaScript Example


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

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

await lookupPostcode({ client, postcode: "NW1 8SJ"});

JavaScript client method documentation

Postcode Not Found

Lookup balance is unaffected by invalid postcodes. The API returns a 404 response with response body:

{
  "code": 4040,
  "message": "Postcode not found",
  "suggestions": [
    "SW1A 0AA"
  ]
}

Suggestions

If a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up O and 0 or I and 1).

If the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches.

The suggestion list will be empty if the postcode has deviated too far from a valid postcode format.

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 lookup on your key.

Multiple Residence

A small number of Multiple Residence postcodes will return more than 100 premises and may require pagination. Use page to paginate the result set.


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

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

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

Pricing

Valid postcodes are charged 1 lookup. Empty responses are not charged.

Geolocation to Postcodes

This method is deprecated. If you require geolocation to postcode translation (or vice versa), consider using our free sister API postcodes.io.

Legacy documetation is available here.

Documentation