UK Data AtlasAPI

Find a postcode's areas

Look up a full UK postcode and find the areas containing its centroid, including its local authority, ward and constituency by default. The response includes the postcode's status, source edition and positional quality so you can judge how precise the placement is.

get
/postcodes/{postcode}

Good to know

  • A postcode centroid is one point; addresses in that postcode can fall on both sides of a boundary. Check nearBoundary and the positional caution before treating the result as exact.
  • Northern Ireland postcodes are not available because of licensing restrictions. Use Find areas at a point when you already have coordinates.

Path parameters

  • postcodestringrequired

    A full unit postcode, such as SW1A 1AA or sw1a1aa.

Query parameters

  • geographystring[]optional

    A geography to look the point up in. Repeat it or give a comma-separated list, up to four in total. A geography named only in a pinned release need not be repeated here.

  • releasestring[]optional

    A release to pin, as {geography}/{release}, such as ward/2025-12-uk-bgc, or ward/latest for its newest unambiguous published release. A bare release id is accepted when exactly one geography is requested. A pinned release is used whatever date says.

  • datestringoptional

    A calendar date as YYYY-MM-DD, or a month as YYYY-MM. Every geography without a pinned release uses the latest release dated on or before it; without a date it uses the newest unambiguous published release. The country boundaries used to place a point that matches nothing are chosen the same way.

  • viewstringoptional

    full explains each answer: the centroid's positional quality, the transformation, each release's selection, resolution and provenance, and each match's distance to its boundary. compact gives only the postcode, its WGS 84 point, each area's id, code, name and nearBoundary, any caution, and the source's attribution.

    One offullcompact
    Defaultfull

Returns

PostcodeLookupEnvelope

The postcode, its centroid and the areas containing it.

  • apiVersionv1required
  • atlasReleasestringrequired

    The immutable /atlas-release releaseId for the artifacts that produced this response.

  • metaobjectrequired
    Show1 child field
    • nextCursorstring | nullrequired

      Opaque cursor for the next page, or null at the end.

  • dataPostcodeLookup | CompactPostcodeLookuprequired

When it goes wrong

  • 400The postcode is not a UK postcode, or names a district or sector rather than a unit; or the geography, release or date is malformed as for /areas:contains.
  • 404The postcode is not in the directory edition served, or a pinned release or geography is unknown.
  • 451The postcode is in Northern Ireland, which this API is not licensed to serve.
  • 503The referenced build artifact has not been built yet.

Every error has the same shape. See Errors for how to handle them.

Technical notes

Show the precise behaviour

Looks a unit postcode up in the ONS Postcode Directory and places its centroid in each requested geography, through the same point lookup as /areas:contains. The postcode is read in any case, with or without its space.

With no geography or release, the postcode is placed in its local authority, ward and Westminster constituency. With no date, each release is the latest dated on or before the directory's edition, and dateBasis says which was used. Terminated postcodes are served, with the month they were terminated.

A postcode is placed by a single centroid, and its addresses can fall on both sides of a boundary. The centroid's positional quality comes from the directory; where the directory states an accuracy it becomes the point's uncertainty and counts towards positionalToleranceM. Where it does not, as for centroids ONS imputed or set at a postcode sector's mean, caution says that nearBoundary may understate the risk. A postcode with no grid reference, such as one in the Channel Islands or the Isle of Man, is described but placed in no area.

Northern Ireland postcodes are licensed by Land and Property Services for internal business use only and are refused with 451. The source's required attribution is returned with every answer.

view=compact returns only the postcode, its WGS 84 point, each area it is placed in and the attribution, for callers that do not need the provenance and tolerances; it is a fraction of the size.