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

  1. Choose a plan on the pricing page. Your keys appear on your dashboard (and in your email) as soon as payment is confirmed.
  2. 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 URLKey starts with
Livehttps://api.savvycreations.co.uk/v1pl_live_
Testhttps://api-test.savvycreations.co.uk/v1pl_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.

Using a key in a web page? Anyone can read it from the page source. On your dashboard, add your site under Allowed websites (for example 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:

HeaderMeaning
X-Allowance-LimitLookups included per month
X-Allowance-RemainingLookups 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." } }
HTTPcodeWhat to do
400invalid_postcode, invalid_outcode, invalid_query, invalid_location, invalid_body, too_many_postcodesFix the request. Not counted as a lookup.
401missing_api_key, invalid_api_key, key_revoked, wrong_environmentCheck the key, and that a pl_live_ key goes to the live URL and pl_test_ to the test URL.
403subscription_endedRenew from your dashboard.
403origin_not_allowedAdd the website to the key's allowed websites.
404not_found, postcode_terminatedNo such (current) postcode. Counted as a lookup.
429rate_limitedToo many requests per second - wait for the Retry-After seconds.
429monthly_allowance_usedThis month's lookups are used up. Resets on the 1st, or upgrade.
503data_not_loadedTemporary - 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.