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/:postcodeReturns 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:
- 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)