{ "openapi": "3.1.0", "info": { "title": "OpenPostcodes", "version": "1.0.0", "summary": "Fast, free UK postcode lookup", "description": "Look up any live UK postcode - its location, administrative areas, census geographies, nearest points of interest, utilities and approximate boundary. Currently serving ONSPD May 2026, refreshed quarterly.\n\nEvery postcode has one URL: `/{postcode}` is an HTML page for people, and the same path ending `.json` or `.md` is the same data for machines. There's no key or sign-up, and every response sends `access-control-allow-origin: *`. The `.json` response is also described on its own, as a JSON Schema, at [/schema.json](https://openpostcodes.uk/schema.json).", "license": { "name": "Open Government Licence v3.0, with some fields under other open licences", "url": "https://openpostcodes.uk/sources" } }, "externalDocs": { "description": "Data sources & licences", "url": "https://openpostcodes.uk/sources" }, "servers": [ { "url": "https://openpostcodes.uk" } ], "security": [], "paths": { "/{postcode}.json": { "get": { "operationId": "getPostcode", "summary": "Look up a postcode as JSON", "parameters": [ { "name": "postcode", "in": "path", "required": true, "description": "A UK postcode in any spelling - case, spaces and hyphens are ignored, so `EX11 1RE`, `ex111re` and `ex11-1re` are the same postcode. Percent-encode a space as `%20`.", "schema": { "type": "string" }, "example": "EX11 1RE" } ], "responses": { "200": { "description": "The postcode", "headers": { "x-cache": { "description": "`HIT` when served from the Worker's per-location cache, `MISS` when read from the database", "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "x-served-by-region": { "description": "Which database read replica answered", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Postcode" }, "example": { "postcode": "EX11 1RE", "part": { "outcode": "EX11", "incode": "1RE", "area": "EX", "district": "EX11", "subdistrict": null, "sector": "EX11 1", "unit": "RE" }, "latitude": 50.748617, "longitude": -3.288526, "open_location_code": "9C2RPPX6+CH", "maidenhead_locator": "IO80ir", "qibla": 114.9, "magnetic_declination": 0.2, "eastings": 309193, "northings": 95128, "grid_reference": "SY 09193 95128", "utm": "30U 479645 5621910", "antipode": { "latitude": -50.748617, "longitude": 176.711474 }, "elevation": 40, "timezone": "Europe/London", "sun": { "rise": "2026-09-27T07:07:00+01:00", "noon": "2026-09-27T13:04:00+01:00", "set": "2026-09-27T19:01:00+01:00" }, "country": { "name": "England", "code": "E92000001" }, "region": { "name": "South West", "code": "E12000009" }, "admin_district": { "name": "East Devon", "code": "E07000040" }, "ward": { "name": "Ottery St Mary", "code": "E05011801" }, "constituency": { "name": "Honiton and Sidmouth", "code": "E14001291" }, "county": { "name": "Devon", "code": "E10000008" }, "parish_code": "E04012660", "census": { "oa21": "E00180256", "lsoa21": "E01019942", "msoa21": "E02004136", "msoa_name": "Ottery St Mary & West Hill", "oa11": "E00100934", "lsoa11": "E01019942", "msoa11": "E02004136", "workplace_zone_code": "E33048809" }, "classification": { "rural_urban": "Larger rural: nearer to a major town or city", "rural_urban_code": "RLN1", "output_area_classification": { "name": "Rural Residents", "code": "1B1" }, "imd": 19675, "user_type": "Small" }, "health": { "nhs_region_code": "E40000006", "icb_location_code": "E38000230", "integrated_care_board_code": "E54000037", "cancer_alliance_code": "E56000014" }, "travel_to_work_area_code": "E30000206", "police_force_area_code": "E23000035", "national_park_code": null, "built_up_area_code": "E63013817", "county_electoral_division_code": "E58000292", "european_electoral_region": { "name": "South West", "code": "E15000009" }, "date_introduced": "1980-01", "nearest": { "railway_station": { "name": "Feniton", "code": "FNT", "distance": 4277, "latitude": 50.787022, "longitude": -3.285259 }, "hospital": { "name": "Ottery St Mary Hospital", "distance": 271, "latitude": 50.750103, "longitude": -3.291587 }, "gp": { "name": "Coleridge Medical Centre", "distance": 488, "latitude": 50.751693, "longitude": -3.283579 }, "school": { "name": "The King's School", "distance": 349, "latitude": 50.750325, "longitude": -3.292684 }, "airport": { "name": "Exeter International Airport", "code": "EXT", "distance": 8971, "latitude": 50.734261, "longitude": -3.413984 }, "bus_stop": { "name": "Hospital", "distance": 215, "latitude": 50.74997, "longitude": -3.29071 }, "foodbank": { "name": "Ottery St Mary", "distance": 794, "latitude": 50.751052, "longitude": -3.277911 }, "defibrillator": { "name": "Ottery St Mary Cricket Club", "distance": 298, "latitude": 50.7462, "longitude": -3.28669 }, "pharmacy": { "name": "Well Pharmacy Ottery St Mary", "distance": 489, "latitude": 50.751596, "longitude": -3.283417 }, "post_office": { "name": "Ottery St Mary Post Office", "distance": 836, "latitude": 50.751063, "longitude": -3.277286 }, "library": { "name": "Ottery St Mary Library", "distance": 786, "latitude": 50.751959, "longitude": -3.278687 }, "coast": { "distance": 8480, "latitude": 50.674547, "longitude": -3.259836 }, "london": { "distance": 236139, "latitude": 51.507412, "longitude": -0.127679 } }, "utilities": { "electricity": { "name": "National Grid Electricity Distribution", "region_code": "L", "mpan_id": 22 }, "water": "South West Water", "sewerage": "South West Water", "broadband": { "gigabit": 85.7, "superfast": 100, "ultrafast": 85.7, "below_uso": 0 } }, "adjacent": [ "EX11 1RD", "EX11 1RF", "EX11 1RG" ], "boundary": { "type": "Polygon", "coordinates": [ [ [ -3.288145, 50.748192 ], [ -3.289545, 50.748733 ], [ -3.288125, 50.749754 ], [ -3.286882, 50.749255 ], [ -3.288145, 50.748192 ] ] ] } } } } }, "400": { "description": "Not a plausible UK postcode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidPostcode" }, "example": { "error": "Invalid postcode format", "input": "EX11 1R.json" } } } }, "404": { "description": "A validly formatted postcode that isn't live in the dataset", "headers": { "x-served-by-region": { "description": "Which database read replica answered", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostcodeNotFound" }, "example": { "error": "Postcode not found", "postcode": "EX11 9ZZ" } } } } } } }, "/{postcode}.md": { "get": { "operationId": "getPostcodeMarkdown", "summary": "Look up a postcode as Markdown", "description": "The same fields as the JSON format, grouped under headings - handy for feeding to an LLM.", "parameters": [ { "name": "postcode", "in": "path", "required": true, "description": "A UK postcode in any spelling - case, spaces and hyphens are ignored, so `EX11 1RE`, `ex111re` and `ex11-1re` are the same postcode. Percent-encode a space as `%20`.", "schema": { "type": "string" }, "example": "EX11 1RE" } ], "responses": { "200": { "description": "The postcode", "headers": { "x-cache": { "description": "`HIT` when served from the Worker's per-location cache, `MISS` when read from the database", "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "x-served-by-region": { "description": "Which database read replica answered", "schema": { "type": "string" } } }, "content": { "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Not a plausible UK postcode", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "A validly formatted postcode that isn't live in the dataset", "headers": { "x-served-by-region": { "description": "Which database read replica answered", "schema": { "type": "string" } } }, "content": { "text/markdown": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Postcode": { "description": "The JSON response from https://openpostcodes.uk/{postcode}.json - see https://openpostcodes.uk for the same fields as a table.", "type": "object", "properties": { "postcode": { "description": "Postcode in canonical format, with the space", "type": "string" }, "part": { "description": "Postcode components", "type": "object", "properties": { "outcode": { "description": "Outward code - before the space, e.g. EC1A", "type": "string" }, "incode": { "description": "Inward code - after the space, e.g. 1BB", "type": "string" }, "area": { "description": "Postcode area - the leading letters, e.g. EC", "type": "string" }, "district": { "description": "Outward code without any trailing sub-district letter, e.g. EC1 (of EC1A)", "type": "string" }, "subdistrict": { "description": "Outward code including the trailing letter, when present, e.g. EC1A; else null", "type": [ "string", "null" ] }, "sector": { "description": "Outward code, a space, and the first inward character, e.g. EC1A 1", "type": "string" }, "unit": { "description": "The last two letters of the postcode, e.g. BB", "type": "string" } }, "required": [ "outcode", "incode", "area", "district", "subdistrict", "sector", "unit" ] }, "latitude": { "description": "Latitude of the postcode centroid (WGS84)", "type": [ "number", "null" ] }, "longitude": { "description": "Longitude of the postcode centroid (WGS84)", "type": [ "number", "null" ] }, "open_location_code": { "description": "Open Location Code (plus code) for the centroid", "type": [ "string", "null" ] }, "maidenhead_locator": { "description": "Maidenhead Locator (amateur radio grid square) for the centroid", "type": [ "string", "null" ] }, "qibla": { "description": "Bearing to Mecca, in degrees clockwise from true north", "type": [ "number", "null" ] }, "magnetic_declination": { "description": "Angle between true and magnetic north, in degrees east (World Magnetic Model 2025)", "type": [ "number", "null" ] }, "eastings": { "description": "OS National Grid easting, in metres", "type": [ "number", "null" ] }, "northings": { "description": "OS National Grid northing, in metres", "type": [ "number", "null" ] }, "grid_reference": { "description": "OS grid reference - British National Grid, or Irish Grid for Northern Ireland", "type": [ "string", "null" ] }, "utm": { "description": "Universal Transverse Mercator coordinate for the centroid - zone, MGRS latitude band, easting and northing, e.g. \"30U 479645 5621910\"", "type": [ "string", "null" ] }, "antipode": { "description": "The point diametrically opposite on the earth's surface", "type": [ "object", "null" ], "properties": { "latitude": { "description": "Latitude of the antipode (WGS84)", "type": "number" }, "longitude": { "description": "Longitude of the antipode (WGS84)", "type": "number" } }, "required": [ "latitude", "longitude" ] }, "elevation": { "description": "Ground elevation at the centroid, in metres (GB mainland; OS Terrain 50)", "type": [ "number", "null" ] }, "timezone": { "description": "IANA timezone (Europe/London, or the Crown Dependency zone)", "type": "string" }, "sun": { "description": "Today's solar times at the centroid, as local ISO 8601 timestamps to the minute", "type": [ "object", "null" ], "properties": { "rise": { "description": "Sunrise - the sun's upper limb at the horizon, allowing for refraction", "type": [ "string", "null" ] }, "noon": { "description": "Solar noon - the sun crossing the meridian, at its highest point of the day", "type": "string" }, "set": { "description": "Sunset", "type": [ "string", "null" ] } }, "required": [ "rise", "noon", "set" ] }, "country": { "description": "Country as { name, code }. name ∈ England, Scotland, Wales, Northern Ireland, Channel Islands, Isle of Man; code is the GSS code", "$ref": "#/components/schemas/named_code" }, "region": { "description": "Region as { name, code } (GSS). England only; both null elsewhere", "$ref": "#/components/schemas/named_code" }, "admin_district": { "description": "Local authority district as { name, code } (GSS)", "$ref": "#/components/schemas/named_code" }, "ward": { "description": "Electoral ward as { name, code } (GSS)", "$ref": "#/components/schemas/named_code" }, "constituency": { "description": "Westminster parliamentary constituency as { name, code } (GSS)", "$ref": "#/components/schemas/named_code" }, "county": { "description": "County as { name, code } (GSS); both null where the postcode is not in a county", "$ref": "#/components/schemas/named_code" }, "parish_code": { "description": "Civil parish (or community) GSS code", "type": [ "string", "null" ] }, "census": { "description": "2011 & 2021 census statistical geographies (GSS codes)", "type": "object", "properties": { "oa21": { "description": "2021 Census Output Area code", "type": [ "string", "null" ] }, "lsoa21": { "description": "2021 Lower Layer Super Output Area code", "type": [ "string", "null" ] }, "msoa21": { "description": "2021 Middle Layer Super Output Area code", "type": [ "string", "null" ] }, "msoa_name": { "description": "MSOA friendly name (House of Commons Library; England & Wales)", "type": [ "string", "null" ] }, "oa11": { "description": "2011 Census Output Area code", "type": [ "string", "null" ] }, "lsoa11": { "description": "2011 Lower Layer Super Output Area code", "type": [ "string", "null" ] }, "msoa11": { "description": "2011 Middle Layer Super Output Area code", "type": [ "string", "null" ] }, "workplace_zone_code": { "description": "2011 Workplace Zone code", "type": [ "string", "null" ] } }, "required": [ "oa21", "lsoa21", "msoa21", "msoa_name", "oa11", "lsoa11", "msoa11", "workplace_zone_code" ] }, "classification": { "description": "Area classifications and indices", "type": "object", "properties": { "rural_urban": { "description": "Rural/urban classification, decoded to text", "type": [ "string", "null" ] }, "rural_urban_code": { "description": "Rural/urban classification code (e.g. RLN1, or 1-6 in Scotland)", "type": [ "string", "null" ] }, "output_area_classification": { "description": "2011 Output Area Classification as { name, code } (UK-wide) - supergroup name and code, e.g. 1B1", "$ref": "#/components/schemas/named_code" }, "imd": { "description": "Deprivation rank on the relevant country's own index and scale - England's IMD, Scotland's SIMD, Wales's WIMD or Northern Ireland's NIMDM (not comparable across countries); 1 = most deprived; null for the Channel Islands and Isle of Man, which have none", "type": [ "number", "null" ] }, "user_type": { "description": "Postcode user type - “Small” (mostly residential) or “Large”", "type": [ "string", "null" ] } }, "required": [ "rural_urban", "rural_urban_code", "output_area_classification", "imd", "user_type" ] }, "health": { "description": "NHS geographies (England; GSS codes)", "type": "object", "properties": { "nhs_region_code": { "description": "NHS England region code", "type": [ "string", "null" ] }, "icb_location_code": { "description": "Integrated Care Board sub-location code", "type": [ "string", "null" ] }, "integrated_care_board_code": { "description": "Integrated Care Board code", "type": [ "string", "null" ] }, "cancer_alliance_code": { "description": "Cancer Alliance code", "type": [ "string", "null" ] } }, "required": [ "nhs_region_code", "icb_location_code", "integrated_care_board_code", "cancer_alliance_code" ] }, "travel_to_work_area_code": { "description": "Travel to Work Area GSS code", "type": [ "string", "null" ] }, "police_force_area_code": { "description": "Police Force Area GSS code", "type": [ "string", "null" ] }, "national_park_code": { "description": "National Park GSS code; null when not in a park", "type": [ "string", "null" ] }, "built_up_area_code": { "description": "Built-Up Area (2024) GSS code", "type": [ "string", "null" ] }, "county_electoral_division_code": { "description": "County Electoral Division code (two-tier county areas)", "type": [ "string", "null" ] }, "european_electoral_region": { "description": "European Electoral Region as { name, code } (legacy geography)", "$ref": "#/components/schemas/named_code" }, "date_introduced": { "description": "Month the postcode was introduced, as YYYY-MM", "type": [ "string", "null" ] }, "nearest": { "type": "object", "properties": { "railway_station": { "description": "Nearest railway station (National Rail, or Translink in Northern Ireland; excludes London Underground and light rail/trams); code is the CRS code where available", "anyOf": [ { "$ref": "#/components/schemas/coded_poi" }, { "type": "null" } ] }, "hospital": { "description": "Nearest hospital (CQC-registered in England, or from a hand-compiled HSC Trust list in Northern Ireland)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "gp": { "description": "Nearest GP surgery (CQC-registered in England, or BSO-registered in Northern Ireland)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "school": { "description": "Nearest school (Get Information About Schools in England, or the Scottish Government's school roll in Scotland); no source in scope for Wales or Northern Ireland, which are null", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "airport": { "description": "Nearest airport; code is the IATA code", "anyOf": [ { "$ref": "#/components/schemas/coded_poi" }, { "type": "null" } ] }, "bus_stop": { "description": "Nearest bus stop (NaPTAN, or Translink in Northern Ireland)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "foodbank": { "description": "Nearest food bank (Give Food)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "defibrillator": { "description": "Nearest public-access defibrillator (The Circuit / BHF)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "pharmacy": { "description": "Nearest pharmacy (OpenStreetMap)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "post_office": { "description": "Nearest post office (OpenStreetMap)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "library": { "description": "Nearest library (OpenStreetMap)", "anyOf": [ { "$ref": "#/components/schemas/poi" }, { "type": "null" } ] }, "coast": { "description": "Nearest point on the coast - { distance, latitude, longitude } or null", "anyOf": [ { "$ref": "#/components/schemas/point" }, { "type": "null" } ] }, "london": { "description": "Straight-line distance to central London (Trafalgar Square) - { distance, latitude, longitude } or null", "anyOf": [ { "$ref": "#/components/schemas/point" }, { "type": "null" } ] } }, "required": [ "railway_station", "hospital", "gp", "school", "airport", "bus_stop", "foodbank", "defibrillator", "pharmacy", "post_office", "library", "coast", "london" ] }, "utilities": { "type": "object", "properties": { "electricity": { "description": "Electricity DNO; null outside GB and Northern Ireland (e.g. Channel Islands, Isle of Man)", "type": [ "object", "null" ], "properties": { "name": { "description": "Distribution Network Operator name", "type": "string" }, "region_code": { "description": "MPAN distributor id, letter form (A-P); null for Northern Ireland, which doesn't use GB's MPAN numbering", "type": [ "string", "null" ] }, "mpan_id": { "description": "MPAN distributor id, number form (10-23) - the same distributor as region_code; null for Northern Ireland", "type": [ "number", "null" ] } }, "required": [ "name", "region_code", "mpan_id" ] }, "water": { "description": "Water supply undertaker", "type": [ "string", "null" ] }, "sewerage": { "description": "Sewerage services undertaker (often, but not always, the same company as utilities.water)", "type": [ "string", "null" ] }, "broadband": { "description": "Fixed broadband coverage (Ofcom Connected Nations, postcode level); null where Ofcom has no matching record for this postcode", "type": [ "object", "null" ], "properties": { "gigabit": { "description": "% of premises with a gigabit-capable service available", "type": "number" }, "superfast": { "description": "% of premises with superfast broadband (SFBB, >=30Mbit/s) available", "type": "number" }, "ultrafast": { "description": "% of premises with ultrafast broadband (UFBB, >=300Mbit/s) available", "type": "number" }, "below_uso": { "description": "% of premises below the Universal Service Obligation (<10Mbit/s download or <1Mbit/s upload, from fixed broadband, a WISP or mobile FWA)", "type": "number" } }, "required": [ "gigabit", "superfast", "ultrafast", "below_uso" ] } }, "required": [ "electricity", "water", "sewerage", "broadband" ] }, "adjacent": { "description": "Bordering postcodes", "type": "array", "items": { "type": "string" } }, "boundary": { "description": "Approximate postcode boundary as a GeoJSON geometry ({ type, coordinates }, WGS84); Great Britain only - null for Northern Ireland, the Channel Islands and Isle of Man", "anyOf": [ { "$ref": "#/components/schemas/geometry" }, { "type": "null" } ] } }, "required": [ "postcode", "part", "latitude", "longitude", "open_location_code", "maidenhead_locator", "qibla", "magnetic_declination", "eastings", "northings", "grid_reference", "utm", "antipode", "elevation", "timezone", "sun", "country", "region", "admin_district", "ward", "constituency", "county", "parish_code", "census", "classification", "health", "travel_to_work_area_code", "police_force_area_code", "national_park_code", "built_up_area_code", "county_electoral_division_code", "european_electoral_region", "date_introduced", "nearest", "utilities", "adjacent", "boundary" ] }, "named_code": { "description": "A geography as { name, code }", "type": "object", "properties": { "name": { "description": "Name, or null where unknown or not applicable", "type": [ "string", "null" ] }, "code": { "description": "ONS GSS code, or null where not applicable", "type": [ "string", "null" ] } }, "required": [ "name", "code" ] }, "point": { "description": "A point, with its distance from the postcode centroid", "type": "object", "properties": { "distance": { "description": "Straight-line distance from the postcode centroid, in metres", "type": "number" }, "latitude": { "description": "Latitude of the point (WGS84)", "type": "number" }, "longitude": { "description": "Longitude of the point (WGS84)", "type": "number" } }, "required": [ "distance", "latitude", "longitude" ] }, "poi": { "description": "A nearby point of interest", "type": "object", "properties": { "name": { "description": "Name of the point of interest", "type": "string" }, "distance": { "description": "Straight-line distance from the postcode centroid, in metres", "type": "number" }, "latitude": { "description": "Latitude of the point (WGS84)", "type": "number" }, "longitude": { "description": "Longitude of the point (WGS84)", "type": "number" } }, "required": [ "name", "distance", "latitude", "longitude" ] }, "coded_poi": { "description": "A nearby point of interest that carries a reference code", "type": "object", "properties": { "name": { "description": "Name of the point of interest", "type": "string" }, "code": { "description": "Reference code, or null where the source has none for this one", "type": [ "string", "null" ] }, "distance": { "description": "Straight-line distance from the postcode centroid, in metres", "type": "number" }, "latitude": { "description": "Latitude of the point (WGS84)", "type": "number" }, "longitude": { "description": "Longitude of the point (WGS84)", "type": "number" } }, "required": [ "name", "code", "distance", "latitude", "longitude" ] }, "geometry": { "description": "A GeoJSON geometry (RFC 7946) in WGS84", "type": "object", "properties": { "type": { "type": "string", "enum": [ "Polygon", "MultiPolygon" ] }, "coordinates": { "type": "array" } }, "required": [ "type", "coordinates" ] }, "InvalidPostcode": { "type": "object", "properties": { "error": { "type": "string", "description": "Always \"Invalid postcode format\"" }, "input": { "type": "string", "description": "The requested path segment, decoded" } }, "required": [ "error", "input" ] }, "PostcodeNotFound": { "type": "object", "properties": { "error": { "type": "string", "description": "Always \"Postcode not found\"" }, "postcode": { "type": "string", "description": "The requested postcode, in canonical format" } }, "required": [ "error", "postcode" ] } } } }