---
title: "List every address at a UK postcode (Royal Mail PAF)"
method: POST
path: "/postcode-lookup"
tags: ["Postcode lookup"]
---

# List every address at a UK postcode (Royal Mail PAF)

`POST /postcode-lookup`

## Request

- Base URL: `https://api.acuris-geo.com`
- URL: `https://api.acuris-geo.com/postcode-lookup`
- Auth: one of:
  - API key in header `X-Acuris-Key`
  - HTTP bearer
  - API key in header `X-API-Key`
  - API key in query parameter `key`
  - none

Returns every delivery point at a given UK postcode, backed by the official
Royal Mail Postcode Address File (PAF). **UK-only** (`country: "gbr"`). Each
address carries the Royal Mail `udprn`, the Ordnance Survey `uprn` (with its
`uprn_match_m` match distance), the full printable PAF element set
(`post_town`, dependent localities, `address_lines`, `administrative_county`),
and rooftop coordinates when available.

**UK host:** call this endpoint on `https://paf.acuris-geo.com`. Requests
sent to `api.acuris-geo.com` return **400**
`{"error": "country_not_served_by_this_endpoint", "use_instead": "https://paf.acuris-geo.com"}`.

Charges **1 validation transaction per call**, regardless of how many addresses
are returned. Anonymous callers use the free tier (per-IP daily cap). The
number of addresses returned is capped (default 100); when the cap is hit
the response sets `truncated: true`. A per-IP velocity cap also applies to
protect the licensed dataset.

## Request body

- object
  - `postcode` string, required
  - `country` string: Only `gbr` is supported.

## Response `200`

All addresses at the postcode.

- object
  - `postcode` string
  - `country` string
  - `count` integer
  - `truncated` boolean: Present and `true` when the result set was capped.
  - `addresses` PostcodeAddress[]
    - `street` string
    - `house_number` string
    - `building_name` string
    - `organisation_name` string
    - `dependent_street` string
    - `dependent_locality` string: PAF village / dependent locality.
    - `double_dependent_locality` string: PAF sub-locality below `dependent_locality`.
    - `post_town` string: The PAF post town; `city` duplicates it for backward compatibility.
    - `city` string
    - `postcode` string
    - `address_lines` string[]: Printable Royal Mail address lines, in order.
    - `formatted_address` string: Single-line join of `address_lines`.
    - `county` string: Traditional county (PAF postcode → county map).
    - `administrative_county` string: PAF Administrative County (local authority). On some postcodes (e.g. M1 1AE) it is the only county held — `county` blank. Present when extended UK fields are enabled (on by default).
    - `udprn` string: Royal Mail Unique Delivery Point Reference Number.
    - `uprn` string: Ordnance Survey Unique Property Reference Number.
    - `uprn_match_m` number: Distance in metres between the PAF delivery point and the matched OS Open UPRN coordinate (0.0 is a real and best value). Present when extended UK fields are enabled (on by default).
    - `lat` number: Omitted when no coordinate is available for the delivery point.
    - `lng` number: Omitted when no coordinate is available for the delivery point.
    - `accuracy_type` string: `rooftop` when an address-level coordinate is available, otherwise `postcode` (postcode-unit centroid). Omitted (along with `lat`/`lng`) when the delivery point has no coordinate. Open set — see AccuracyType; do not treat an unrecognized value as a failure.
  - `validation_credits_remaining` integer: Present only for authenticated (keyed) callers. Omitted for anonymous free-tier requests.
  - `geocode_credits_remaining` integer: Present only for authenticated (keyed) callers. Omitted for anonymous free-tier requests.

## Other responses

- `400`: Missing postcode, or a non-UK `country`.
- `401`: Invalid or inactive API key.
- `403`: Insufficient validation transactions, or expired trial. Key-level 403s: `{"error": "key_blocked", "message"}` when the API key has been blocked (the `message` says why), and `{"error": "ip_not_allowed", "message", "ip"}` when the key is restricted to approved source IP addresses and this request came from another one (`ip` is the address we saw). Source-IP restriction is optional and set up per key on request via support.
- `404`: Postcode not found.
- `429`: Free-tier daily cap or per-IP velocity cap reached.

---

[API](https://skmtc.dev/acuris-geo/apis/acuris-geo-api.md) · [All operations](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/revisions/8547b31dd96a?raw)