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.