Documentation

Postcodes

A postcode instance resource represents a single UK postcode. Use this resource to query for addressing data related to a specific 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.

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

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)