UK Data AtlasAPI

Find areas for postcodes

Look up up to 100 full UK postcodes in one request and find the areas containing each postcode's centroid. The response gives every lookup the same source edition and boundary settings, making it easier to tag a list consistently.

post
/postcodes:batch

Good to know

  • Give each postcode as a repeated postcode parameter. The request accepts full unit postcodes only.
  • Each postcode is still placed by one centroid, so its addresses may span a boundary. Check the positional quality and nearBoundary fields.

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

PostcodeBatchEnvelope

Each postcode's entry, and a summary of the batch.

  • 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.

  • dataPostcodeBatch | CompactPostcodeBatchrequired

When it goes wrong

  • 400No postcode is given, more than 100 are, or the geography, release or date is malformed as for /areas:contains.
  • 404A pinned release or a geography is unknown.
  • 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

The /postcodes/{postcode} lookup for up to 100 postcodes at once. Send them in the JSON body's postcodes array. The releases are chosen once for the whole batch, as for a single postcode: the default geographies as at the directory's edition unless query geography, release or date say otherwise.

Each postcode has its own entry, in the order given, with a status: placed, with its areas; not-placed, for a postcode the directory gives no grid reference; invalid, for text that is not a unit postcode; not-found, for one the directory edition does not hold; and not-served, for a Northern Ireland postcode, which this API is not licensed to serve. None of these fails the batch. Only a problem with the request itself does, such as no postcodes, too many, or a malformed date.

Placed centroids are tested together, so each release's geometry is read once for the batch, and release-wide provenance is given once in releases. summary counts each postcode status and each lookup outcome. view=compact keeps the entries and summary but gives each postcode only its record, point and areas, as for a single postcode.