Postcode Lookup API v1
UK postcode data for Great Britain (England, Scotland and Wales): location, council, ward, constituency, police force area, NHS and census areas. Northern Ireland (BT) postcodes are not included.
Quick start
- Choose a plan on the pricing page. Your keys appear on your dashboard (and in your email) as soon as payment is confirmed.
- Try your test key against the Test API:
curl -H "X-Api-Key: pl_test_YOUR_TEST_KEY" \ https://api-test.savvycreations.co.uk/v1/postcodes/SW1A1AA
From JavaScript:
const res = await fetch(
'https://api.savvycreations.co.uk/v1/postcodes/' + encodeURIComponent(postcode),
{ headers: { 'X-Api-Key': 'pl_live_YOUR_KEY' } }
);
if (res.ok) {
const data = await res.json();
console.log(data.local_authority.name); // "Westminster"
} else {
const { error } = await res.json();
console.log(error.code, error.message); // e.g. "not_found"
}From C#:
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Api-Key", "pl_live_YOUR_KEY");
var json = await http.GetStringAsync(
"https://api.savvycreations.co.uk/v1/postcodes/" + Uri.EscapeDataString(postcode));Keys & base URLs
| Base URL | Key starts with | |
|---|---|---|
| Live | https://api.savvycreations.co.uk/v1 | pl_live_ |
| Test | https://api-test.savvycreations.co.uk/v1 | pl_test_ |
Send your key in the X-Api-Key header. Authorization: Bearer <key> also works. ?api_key= is accepted as a last resort, but web addresses end up in logs, so prefer the header.
The Test API has the same data and endpoints as Live, with a small allowance. Build against it, then swap the base URL and key.
https://shop.example.co.uk) so the key only works from there. If a key is ever exposed, regenerate it - the old one stops working immediately. Allowance & limits
Each plan includes a number of lookups per calendar month (UTC) and a number of requests per second. Every response tells you where you stand:
| Header | Meaning |
|---|---|
X-Allowance-Limit | Lookups included per month |
X-Allowance-Remaining | Lookups left this month (before this request) |
One lookup = one postcode, validate, outcode, autocomplete or nearest request, whether or not the postcode exists. A bulk request counts one per postcode. Malformed requests (400) and /v1/status are free.
Look up a postcode
GET/v1/postcodes/{postcode}
Everything about one postcode. Spaces and capitals don't matter: SW1A1AA, sw1a 1aa and SW1A%201AA all work.
- Every field is always present, and is null when it doesn't apply (for example county for a unitary authority, or region outside England).
- location is null for the few postcodes with no grid reference. positional_quality is the ONS indicator: 1 is the most precise.
- user_type is "small" (homes and most businesses) or "large" (a single address that gets lots of post).
- 404 not_found: not a current or past postcode. 404 postcode_terminated: no longer in use - add ?include_terminated=true to get its last known details.
Request
GET /v1/postcodes/SW1A1AA
Response
{
"postcode": "SW1A 1AA",
"outcode": "SW1A",
"incode": "1AA",
"status": "live",
"introduced": "1980-01",
"terminated": null,
"user_type": "large",
"location": {
"latitude": 51.501009,
"longitude": -0.141588,
"eastings": 529090,
"northings": 179645,
"positional_quality": 1
},
"country": { "code": "E92000001", "name": "England" },
"region": { "code": "E12000007", "name": "London" },
"county": null,
"county_electoral_division": null,
"local_authority": { "code": "E09000033", "name": "Westminster" },
"ward": { "code": "E05013806", "name": "St James's" },
"parish": { "code": "E43000236", "name": "Westminster, unparished area" },
"constituency": { "code": "E14001172", "name": "Cities of London and Westminster" },
"european_electoral_region": { "code": "E15000007", "name": "London" },
"police_force_area": { "code": "E23000001", "name": "Metropolitan Police" },
"nhs_region": { "code": "E40000003", "name": "London" },
"integrated_care_board": { "code": "E54000030", "name": "..." },
"sub_icb_location": { "code": "E38000256", "name": "..." },
"itl": { "code": "TLI32", "name": "Westminster" },
"travel_to_work_area": { "code": "E30000234", "name": "London" },
"national_park": null,
"built_up_area": { "code": "E63004851", "name": "London" },
"census_2021": {
"output_area": "E00166756",
"lsoa": { "code": "E01004736", "name": "Westminster 018C" },
"msoa": { "code": "E02000977", "name": "Westminster 018" },
"rural_urban": "UN1"
},
"imd_rank": 21512
}Validate a postcode
GET/v1/postcodes/{postcode}/validate
Is this a real, current postcode? A quick yes/no for form validation.
- reason is invalid_format, not_found or terminated - and is left out when the postcode is valid.
Request
GET /v1/postcodes/pe15%208aa/validate
Response
{ "query": "pe15 8aa", "postcode": "PE15 8AA", "valid": true }
{ "query": "PE15 9ZZ", "postcode": "PE15 9ZZ", "valid": false, "reason": "terminated" }
{ "query": "hello", "valid": false, "reason": "invalid_format" }Bulk lookup
POST/v1/postcodes/bulk
Up to 100 postcodes in one request. Results come back in the same order you sent them.
- Each postcode sent counts as one lookup.
- error is invalid_postcode or not_found. Terminated postcodes are returned with "status": "terminated".
Request
POST /v1/postcodes/bulk
Content-Type: application/json
{ "postcodes": ["PE15 8AA", "SW1A 1AA", "nonsense"] }Response
{
"results": [
{ "query": "PE15 8AA", "result": { "postcode": "PE15 8AA", ... } },
{ "query": "SW1A 1AA", "result": { "postcode": "SW1A 1AA", ... } },
{ "query": "nonsense", "error": "invalid_postcode", "result": null }
]
}Autocomplete
GET/v1/postcodes/autocomplete?q=...&limit=10
Live postcodes starting with what the user has typed so far - for a "type ahead" postcode box.
- q needs at least 2 characters, starting with a letter. limit is 1-50 (default 10).
Request
GET /v1/postcodes/autocomplete?q=PE15%208
Response
{ "query": "PE15 8", "results": ["PE15 8AA", "PE15 8AB", "PE15 8AD"] }Nearest postcodes
GET/v1/postcodes/nearest?lat=...&lon=...
Live postcodes near a point (for example from a phone's location), nearest first.
- radius is in metres, 1-2000 (default 500). limit is 1-50 (default 10). Coordinates are WGS84 decimal degrees.
Request
GET /v1/postcodes/nearest?lat=51.5010&lon=-0.1416&radius=500
Response
{
"results": [
{ "distance_m": 8.4, "postcode": { "postcode": "SW1A 1AA", ... } }
]
}Outcode summary
GET/v1/outcodes/{outcode}
The first half of a postcode (e.g. PE15): how many live postcodes it has, its centre, and the councils it covers.
Request
GET /v1/outcodes/PE15
Response
{
"outcode": "PE15",
"postcode_count": 1342,
"location": { "latitude": 52.548211, "longitude": 0.084102 },
"local_authorities": [ { "code": "E07000010", "name": "Fenland" } ],
"countries": [ { "code": "E92000001", "name": "England" } ]
}Your key and allowance
GET/v1/status
How many lookups you've used this month, and which data release is being served. Free - never counts as a lookup.
Request
GET /v1/status
Response
{
"environment": "live",
"key": {
"prefix": "pl_live_Ab12",
"monthly_allowance": 20000,
"used_this_month": 1234,
"remaining_this_month": 18766,
"rate_per_second": 10,
"valid_until": "2026-11-19T10:00:00+00:00"
},
"data": { "source": "ONSPD_AUG_2026_UK.csv", "live_count": 1789123, ... }
}Errors
Every error has the same shape. Branch on code; show message to people if you like.
{ "error": { "code": "invalid_postcode", "message": "That isn't a valid UK postcode format." } }| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_postcode, invalid_outcode, invalid_query, invalid_location, invalid_body, too_many_postcodes | Fix the request. Not counted as a lookup. |
| 401 | missing_api_key, invalid_api_key, key_revoked, wrong_environment | Check the key, and that a pl_live_ key goes to the live URL and pl_test_ to the test URL. |
| 403 | subscription_ended | Renew from your dashboard. |
| 403 | origin_not_allowed | Add the website to the key's allowed websites. |
| 404 | not_found, postcode_terminated | No such (current) postcode. Counted as a lookup. |
| 429 | rate_limited | Too many requests per second - wait for the Retry-After seconds. |
| 429 | monthly_allowance_used | This month's lookups are used up. Resets on the 1st, or upgrade. |
| 503 | data_not_loaded | Temporary - try again shortly. |
Data & attribution
Data comes from the ONS Postcode Directory, which is updated quarterly. If you display it, please include:
Source: Office for National Statistics licensed under the Open Government Licence v.3.0. Contains OS data © Crown copyright and database right 2026.
Questions or problems? Get in touch from your dashboard.