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 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 |
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,
"uprn": "2"
},
{
"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": "Basement Flat",
"sub_building_name": "",
"po_box": "",
"department_name": "",
"organisation_name": "",
"udprn": 52618355,
"umprn": "",
"postcode_type": "S",
"su_organisation_indicator": "",
"delivery_point_suffix": "3A",
"line_1": "Basement Flat",
"line_2": "2 Barons Court Road",
"line_3": "",
"premise": "Basement Flat, 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": "3"
},
{
"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": "4",
"building_name": "",
"sub_building_name": "",
"po_box": "",
"department_name": "",
"organisation_name": "",
"udprn": 25962215,
"umprn": "",
"postcode_type": "S",
"su_organisation_indicator": "",
"delivery_point_suffix": "1W",
"line_1": "4 Barons Court Road",
"line_2": "",
"line_3": "",
"premise": "4",
"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": "4"
},
{
"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": "4",
"building_name": "",
"sub_building_name": "Basement",
"po_box": "",
"department_name": "",
"organisation_name": "",
"udprn": 25962189,
"umprn": "",
"postcode_type": "S",
"su_organisation_indicator": "",
"delivery_point_suffix": "2P",
"line_1": "Basement",
"line_2": "4 Barons Court Road",
"line_3": "",
"premise": "Basement, 4",
"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": "5"
},
{
"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": "6",
"building_name": "",
"sub_building_name": "",
"po_box": "",
"department_name": "",
"organisation_name": "",
"udprn": 25962218,
"umprn": "",
"postcode_type": "S",
"su_organisation_indicator": "",
"delivery_point_suffix": "1Y",
"line_1": "6 Barons Court Road",
"line_2": "",
"line_3": "",
"premise": "6",
"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": "6"
},
{
"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": "8",
"building_name": "",
"sub_building_name": "",
"po_box": "",
"department_name": "",
"organisation_name": "",
"udprn": 25962219,
"umprn": "",
"postcode_type": "S",
"su_organisation_indicator": "",
"delivery_point_suffix": "1Z",
"line_1": "8 Barons Court Road",
"line_2": "",
"line_3": "",
"premise": "8",
"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": "7"
},
{
"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,
"uprn": "8"
}
],
"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: "NW1 8SJ"});
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 response2000
ID1 KFA
Returns "postcode not found", error4040
ID1 CLIP
Returns "no lookups remaining", error4020
ID1 CHOP
Returns "daily (or individual) lookup limit breached", error4021
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 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 separated 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:
- Postcode
- Longitude (ETRS89/WGS84)
- Latitude (ETRS89/WGS84)
- Northings (OS National Grid)
- Eastings (OS National Grid)
- Distance in metres from specified point
Testing
This route is free, so you can test with live data.
Pricing
Free
Data Source
Ordnance Survey (Code-Point Open)