Endpoint reference · getPostcode

Postcode lookup & explorer

Purpose

Look up a stored postcode with geographic references, coordinates and source freshness. This is a release-backed record, not an address or a real-time location service.

GET /v1/postcodes/{postcode}

Parameters and permissions

postcode is a required string path parameter. Compact, spaced and case-varied UK postcodes are accepted by the transport schema; runtime normalization trims and uppercases, removes spaces and inserts one space before the final three characters. URL-encode spaces as %20. Invalid structure is rejected. This operation has no query parameters or request body.

The contract requires Bearer API-key authentication (BearerAuth, no OAuth scopes listed). An authenticated key still needs permission for the operation.

Response structure

A 200 response is JSON with data and meta. data.id is a UUID; postcode is the normalized postcode. coordinates contains nullable latitude and longitude in WGS84. status is active or terminated, and termination_month is a nullable YYYY-MM value. country, region, local_authority, constituency and ward are nullable references with id, code and name. Missing geography must not be guessed.

Example request

Production contract, illustrative only; not an executed request or a live-data claim. The response schema is linked below; the upstream preview has a different envelope.

curl 'https://api.britdatum.com/v1/postcodes/TN37%206DJ' \
  -H "Authorization: Bearer ${BRITDATUM_API_KEY}"

Errors and retry guidance

400 — validation_failed

Invalid postcode; correct the input before retrying.

401 — authentication_required

Missing or invalid key; correct credentials.

402 — insufficient_credits

Insufficient tenant credits; resolve the balance before retrying.

403 — forbidden

Key lacks permission; resolve access.

404 — not_found

No stored record matches the canonical input; do not repeatedly retry unchanged input.

429 — rate_limit_exceeded

Request limit exceeded; back off and consult the rate-limit reset header.

500 — internal_error

Unexpected server failure; use bounded retries with backoff.

503 — dependency_unavailable

Required service unavailable; use bounded retries with backoff.

Errors normally use { "error": { "code": "…", "message": "…" } }. The 402 schema additionally carries required_credits, available_credits and upgrade_url. Preserve X-Request-ID when reporting errors; never include your key.

Credit cost and Test mode

The fixed simple_lookup contract cost is 1 credit. Inspect X-BritDatum-Credits-Used and X-BritDatum-Credits-Remaining; this page does not execute or settle a BritDatum request. The upstream preview is not BritDatum Test mode and does not exercise BritDatum billing or deterministic fixtures. A working persisted-data Test environment is not offered here.

Source, freshness and attribution

The source manifest pins the ONS Postcode Directory August 2026 (AUG_2026), published 1 September 2026. ONS releases are quarterly; this pin is not evidence of a completed production import. In the BritDatum schema, meta.source_release_date identifies the source release date and meta.last_refreshed_at identifies the refresh timestamp, not the time the browser received a response. No current ingestion lag or freshness guarantee is asserted.

The distribution scope excludes Northern Ireland BT records unless the separate Land and Property Services licence is approved. The public postcodes.io preview has its own coverage and licensing; it does not establish BritDatum distribution rights.

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

References: ONS source release, ONS geography licences, Open Government Licence v3.0, and OpenAPI 1.0.0: getPostcode schema and response headers.