# OpenPostcodes data guide

OpenPostcodes serves every live UK postcode from the ONS Postcode Directory,
with the Channel Islands and the Isle of Man, under the Open Government
Licence v3.0. This guide explains what it holds, how records are
identified, where to start and how far to rely on each part. It is written
for AI assistants using the OpenPostcodes MCP server at https://openpostcodes.uk/mcp, and
for anyone else reading the data.

## What it holds

For each live postcode, from the ONS Postcode Directory and the sources
added to it (each listed, with its licence, at https://openpostcodes.uk/sources):

- **Location**: the centroid's latitude and longitude, OS grid reference and
  eastings and northings, Universal Transverse Mercator, Open Location Code
  and Maidenhead locator, elevation, time zone, today's sunrise, solar noon
  and sunset, magnetic declination, the bearing to Mecca and the antipode.
- **Geographies**: country, region, local authority, ward, Westminster
  constituency, county, parish, census output areas (2011 and 2021), NHS
  areas, police force area, travel to work area, national park, built-up area
  and county electoral division, each as a GSS code and, where there is one,
  a name.
- **Classification**: the rural or urban class, the 2011 Output Area
  Classification, the deprivation rank and whether it is a small (mostly
  residential) or large user postcode.
- **Nearest places**: the nearest railway station, hospital, GP, school,
  airport, bus stop, food bank, defibrillator, pharmacy, post office and
  library, with straight-line distances, and the distance to the coast and to
  central London.
- **Utilities**: the electricity distribution network operator, the water and
  sewerage companies, and Ofcom's broadband coverage figures.
- **Neighbours**: the bordering postcodes, and an approximate boundary
  polygon (Great Britain only).

Above each postcode are three levels, each a listing: its **sector** (the
postcodes in it), its **district** (the sectors) and its **area** (the
districts), each with a count of live postcodes and the local authorities
covering it.

The sources and the editions served:

- ONS Postcode Directory (postcodes, coordinates and geography codes): ONSPD May 2026. Quarterly (February, May, August, November), each edition loaded by hand.
- ONS Names and Codes registers, and House of Commons Library MSOA names: ONSPD May 2026. With each ONS Postcode Directory edition.
- Nearest places (stations, hospitals, GPs, schools, airports, bus stops, food banks, defibrillators, pharmacies, post offices, libraries and the coast): Varies by source (see /sources). Refreshed now and then, not on a fixed cycle.
- Postcode boundaries (Mark Longair, from ONS address points): 2021. A single snapshot, not refreshed.
- Electricity, water and sewerage supply areas (NESO, Ofwat): NESO 2024-05-03; Ofwat v1.5, April 2024. When NESO or Ofwat publish a revision.
- Fixed broadband coverage (Ofcom Connected Nations): Connected Nations 2024. When Ofcom publish, about twice a year.
- World Magnetic Model, for magnetic declination: WMM2025, valid 2025 to 2030. Every five years.

Not held:

- Addresses, or how many addresses a postcode has
- Terminated (retired) postcodes
- A search from a point or a place name to its postcode
- Boundaries for Northern Ireland, the Channel Islands and the Isle of Man
- Schools in Wales and Northern Ireland, and hospitals and GPs in Scotland and Wales
- Property sales (openproperties.uk) and the companies registered at a postcode (opencompanies.uk)

The count of postcodes, and the edition of each source, are in
https://openpostcodes.uk/mcp/status.json and the get_dataset_status tool.

## Identifiers

A postcode is its own identifier, in any spelling: "EX11 1RE", "ex111re"
and "EX11-1RE" are the same postcode. Its parts:

- the **outward code** before the space ("EX11"), which is its **district**;
- the **area**, the outward code's leading letters ("EX");
- the **sector**, the outward code and the first digit after the space ("EX11 1").

Some outward codes end in a letter ("EC1A", "SW1A"): the record's
part.district drops it ("EC1") and part.subdistrict keeps it, while the
district listings use the whole outward code.

Every postcode and every level above it is a page, and every page is also
JSON at the same URL with `.json` appended (or Markdown with `.md`), with no
key and no registration:

- https://openpostcodes.uk/EX11%201RE: one postcode
- https://openpostcodes.uk/EX11%201: the postcodes in a sector
- https://openpostcodes.uk/EX11: the sectors in a district
- https://openpostcodes.uk/EX: the districts in an area

Without a space, "N11" is the district N11; the sector N1 1 is written with
its space. The JSON URLs are this server's resource URIs, and https://openpostcodes.uk/schema.json
describes every field of a postcode's JSON. The search and fetch tools use ids
of the form `postcode:EX11 1RE`, `sector:EX11 1`, `district:EX11` and `area:EX`.

## Where to start

- One postcode: get_postcode, which has every field.
- Many postcodes: lookup_postcodes, up to 100 at once, with their
  coordinates and administrative areas.
- Two postcodes: compare_postcodes, for the distance, the bearing and the
  geographies they share.
- Browsing: get_postcode_area, get_postcode_district and get_postcode_sector.
- Freshness and coverage: get_dataset_status.

Tools: `get_postcode`, `lookup_postcodes`, `compare_postcodes`, `get_postcode_area`, `get_postcode_district`, `get_postcode_sector`, `get_dataset_status`, `search`, `fetch`, `send_feedback`. Prompts: `postcode_report`, `area_overview`, `compare_two_postcodes`, `nearest_services`.

Lists are capped and paged: pass `next_cursor` back as `cursor` for the next
page. Every list here is short (the longest, a sector, holds about 400
postcodes), and none pages past 1,000 rows. Each database query may run
for 8 seconds and each call for 20, and a request that runs out of time
says what to do. Tool results are capped at
60,000 characters.

## Caveats

- Live postcodes only: terminated postcodes are left out, so a postcode that is not found may have been retired.
- Coordinates are the centroid of the postcode, not any one building. The Channel Islands, the Isle of Man and GIR 0AA have none, so their location fields are null.
- Deprivation (classification.imd) is a rank on each country's own index (England's IMD, Scotland's SIMD, Wales's WIMD, Northern Ireland's NIMDM), 1 being the most deprived. Ranks do not compare across countries.
- Nearest places are straight-line distances from the centroid, and coverage varies: schools for England and Scotland only, hospitals and GPs for England and Northern Ireland only (its hospitals a hand-compiled list of major sites).
- Boundaries are approximate (a 2021 Voronoi diagram of address points), Great Britain only, missing for postcodes introduced since, and not legal boundaries.
- Electricity, water and sewerage companies come from supply-area maps: approximate, not a record of supply, and new-build connections in particular may differ.
- Broadband figures are Ofcom's percentages of premises, for Great Britain and Northern Ireland, and null where Ofcom has no record for the postcode.
- sun (sunrise, solar noon, sunset) and magnetic_declination are for today and change daily; declination is null outside the World Magnetic Model's 2025 to 2030 window.
- Northern Ireland postcodes (BT) are under the Northern Ireland End User Licence: commercial re-use may need a licence from Land & Property Services.

## Licence and attribution

The postcodes, their coordinates and their geographies come from the ONS
Postcode Directory, reused under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
Anything built with it should give this attribution:

Contains OS data © Crown copyright and database right 2026. Contains Royal Mail data © Royal Mail copyright and database right 2026. Source: Office for National Statistics licensed under the Open Government Licence v3.0.

The fields added to it come from further sources, each with its own licence,
listed at https://openpostcodes.uk/sources. Nearest pharmacies, post offices and libraries are
OpenStreetMap data, under the Open Database Licence: credit them "©
OpenStreetMap contributors". Every tool result carries the attribution that
applies to it.

OpenPostcodes is an independent project and is not affiliated with the Office
for National Statistics, Ordnance Survey or Royal Mail. The ONS Postcode
Directory itself is the authoritative source: where anything here differs from
it, the ONS's own release takes precedence.

## Feedback

send_feedback lets an assistant send the people who run OpenPostcodes a short note about these tools: something no tool could answer, an answer that was wrong or confusing, or an error that did not say what would work. Its description tells the assistant to show you the note and send it only once you agree.

What is kept: the note, its kind, the tool it names, the client's name and version, the protocol and server versions, and the time. Never your IP address: only a keyed hash of it, to limit each address to 10 notes a day. A note holding an email address, an IP address or a web address with a query string is refused. Notes are read only by the people who run OpenPostcodes, and deleted after 365 days.

## OpenCommons

OpenPostcodes is one of the OpenCommons sites. Their MCP servers keep one contract (identity, paging, results, errors and feedback), so an assistant connected to more than one finds the same conventions in each. Where a record has a counterpart on another of the sites, its result links to it under external_links.

- OpenCharities, UK charities from the three regulators' registers: England and Wales, Scotland and Northern Ireland: https://opencharities.uk/mcp
- OpenCompanies, UK companies, officers, owners and accounts from Companies House: https://opencompanies.uk/mcp
- OpenProperties, residential property sales in England and Wales from HM Land Registry's Price Paid Data: https://openproperties.uk/mcp