Postcodes.io API: Get postcode details
Looks up a UK postcode on Postcodes.io, including its location, administrative areas and whether it is still in use. Retired postcodes return location and retirement year only.
Unofficial. Not affiliated with or endorsed by Postcodes.io.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Postcode, required
postcode UK postcode, with or without a space and in any letter case, for example SW1A 1AA.
SW1A 1AA
Input as JSON
{ "postcode": "SW1A 1AA"}Output
{ "ward": "St James's", "county": null, "in_use": true, "parish": "Westminster, unparished area", "region": "London", "country": "England", "eastings": 529090, "latitude": 51.50101, "postcode": "SW1A 1AA", "longitude": -0.141563, "northings": 179645, "page_link": "https://postcodes.io/postcodes/SW1A1AA" , "area_codes": { "ward": "E05013806", "county": null, "parish": "E43000236", "local_council": "E09000033", "integrated_care_board": "E54000071", "parliamentary_constituency": "E14001172" }, "year_retired": null, "local_council": "Westminster", "parliamentary_constituency": "Cities of London and Westminster", "health_board_or_integrated_care_board": "NHS West and North London Integrated Care Board"}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"postcodes.io/get_postcode","input":{"postcode":"SW1A 1AA"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "postcodes.io/get_postcode" , "input": { "postcode": "SW1A 1AA" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "postcodes.io/get_postcode" , "input": { "postcode": "SW1A 1AA" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run postcodes.io/get_postcode# with {"postcode":"SW1A 1AA"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "postcode" ], "properties": { "postcode": { "type": "string", "minLength": 1, "description": "UK postcode, with or without a space and in any letter case, for example SW1A 1AA." } }}Output schema
{ "type": "object", "required": [ "postcode", "country", "region", "county", "local_council", "ward", "parish", "parliamentary_constituency", "health_board_or_integrated_care_board", "latitude", "longitude", "in_use", "year_retired", "page_link", "area_codes", "eastings", "northings" ], "properties": { "ward": { "type": [ "string", "null" ], "description": "Administrative ward." }, "county": { "type": [ "string", "null" ], "description": "Administrative county, if applicable." }, "in_use": { "type": "boolean", "description": "Whether the postcode is currently active." }, "parish": { "type": [ "string", "null" ], "description": "Civil parish or equivalent, if recorded." }, "region": { "type": [ "string", "null" ], "description": "Region, if available." }, "country": { "type": [ "string", "null" ], "description": "UK country." }, "eastings": { "type": [ "integer", "null" ], "description": "British National Grid easting when provided.", "x-fous-developer": true }, "latitude": { "type": [ "number", "null" ], "description": "Latitude in decimal degrees." }, "postcode": { "type": "string", "description": "Postcode with standard spacing and uppercase letters." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude in decimal degrees." }, "northings": { "type": [ "integer", "null" ], "description": "British National Grid northing when provided.", "x-fous-developer": true }, "page_link": { "type": "string", "description": "Link to the postcode record on Postcodes.io." }, "area_codes": { "type": "object", "required": [ "local_council", "county", "ward", "parish", "parliamentary_constituency", "integrated_care_board" ], "properties": { "ward": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "parish": { "type": [ "string", "null" ] }, "local_council": { "type": [ "string", "null" ] }, "integrated_care_board": { "type": [ "string", "null" ] }, "parliamentary_constituency": { "type": [ "string", "null" ] } }, "description": "Official area identifiers supplied for the postcode; null where unavailable.", "x-fous-developer": true, "additionalProperties": false }, "year_retired": { "type": [ "integer", "null" ], "description": "Year the postcode was retired, if known." }, "local_council": { "type": [ "string", "null" ], "description": "Local authority or council area." }, "parliamentary_constituency": { "type": [ "string", "null" ], "description": "UK parliamentary constituency." }, "health_board_or_integrated_care_board": { "type": [ "string", "null" ], "description": "Integrated care board in England or the available health authority or board elsewhere." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
postcodes.io/get_postcode- Returns
- postcode, country, region, council, ward, parish, constituency, health board, coordinates, in_use, year_retired, area codes
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method postcodes.io/get_postcode with the inputs above.
Ask your agent
- What council and ward does the postcode SW1A 1AA fall under?
- Is the UK postcode M1 1AE still active or has it been retired, and if retired, when?
- Give me the constituency, region and coordinates for EH1 2NG on postcodes.io.
- Which parish and health board cover the postcode bs81uh?
- I need the country, latitude and longitude for the UK postcode ls1 4ap, plus its administrative area codes.
See more
All Postcodes.io methodsLists UK postcodes nearest to a postcode or named place, with distance, ward, council and coordinates. For places sharing a name, a city or town is preferred.
postcodes.io/list_nearby_postcodesFinds the neighbourhood policing team for a UK postcode (England, Wales, Northern Ireland) with its force, contacts, officers, priorities and upcoming events.
police.uk/get_neighbourhood_teamLooks up the places, regions and coordinates for a postal code in a supported country on Zippopotam.us.
zippopotam.us/get_postal_codeFinds postal codes, place names and coordinates for a town and state or region in a country covered by Zippopotam.us.
zippopotam.us/search_postal_codesGets crimes reported within one mile of a UK postcode or place in England, Wales or Northern Ireland for a month (latest published by default), with category totals, up to 100 sampled incidents, the previous month's total and the local police.uk crime-map link.
data.police.uk/get_crimes_near_postcodeFinds the public location and network operator of an IPv4 or IPv6 address. Private and reserved addresses have no public location.
ipinfo.io/get_ip_locationLooks up an Indian six-digit PIN code and lists its post offices with branch type, delivery status and postal area.
postalpincode.in/get_pin_codeFinds Indian post offices matching a place name, with PIN codes, branch types, delivery statuses, districts and states. Optionally narrows by state or district.
postalpincode.in/search_pin_codes