Postcodes

Autocomplete UK postcodes by prefix. Returns formatted postcodes with latitude/longitude coordinates and country.

Try it

—

Endpoint

GET/v1/postcode/<query>

Base URL: https://autocomplete.namedone.com

SDK Usage

postcodes()

1import { createClient } from "@namedone/autocomplete"
2
3const nd = createClient("nd_...")
4const { results } = await nd.postcodes("sw1a")

curl

1# Exchange your API key for a token
2curl -X POST https://token.namedone.com/v1 \
3  -H "Content-Type: application/json" \
4  -d '{"apiKey":"nd_..."}'
5
6# Query the postcodes endpoint
7curl "https://autocomplete.namedone.com/v1/postcode/sw1a?token=<jwt>"

Response Format

JSON

{
  "results": [
    {
      "id": "postcode-0",
      "text": "SW1A 1AA",
      "type": "postcode"
      "data": {
        "lat": <number>,
        "lng": <number>,
        "country": <string>
      }
    }
  ],
  "query": "sw1a"
}

Data Fields

Field	Type	Description
lat	number	WGS84 latitude
lng	number	WGS84 longitude
country	string	Country code (E92000001=England, S92000003=Scotland, W92000004=Wales)

API Query Parameters

Sent as query string parameters on the HTTP request to the API.

Parameter	Type	Default	Description
token	string	—	JWT obtained from the token API. Required for authentication.

SDK Options

Passed to the SDK methods (e.g. firstNames(query, opts)). These are processed client-side and never sent to the API.

Option	Type	Default	Description
limit	number	10	Maximum number of results (1–50). Applied client-side by the SDK.
simple	boolean	false	Simplify response: deduplicate by text and strip to {text, type}.
sortByProximity	array	—	Sort results by proximity to coordinates. Client-side only.

Examples

Query: sw1a

{
  "results": [
    {
      "id": "postcode-0",
      "text": "SW1A 1AA",
      "type": "postcode",
      "data": {
        "lat": 51.5074,
        "lng": -0.1278,
        "country": "E92000001"
      }
    },
    {
      "id": "postcode-1",
      "text": "SW1A 2AA",
      "type": "postcode",
      "data": {
        "lat": 51.5072,
        "lng": -0.1276,
        "country": "E92000001"
      }
    },
    {
      "id": "postcode-2",
      "text": "SW1A 0AA",
      "type": "postcode",
      "data": {
        "lat": 51.5071,
        "lng": -0.1275,
        "country": "E92000001"
      }
    }
  ],
  "query": "sw1a"
}

Notes

Postcodes are normalised to lowercase with no spaces in the URL (e.g. /v1/postcode/sw1a1aa). The SDK handles this automatically.
The postcode CF Function validates the postcode format at the edge and returns 400 for invalid postcodes before reaching Lambda.
postcodeArea and postcodeDistrict are derived on the fly from the formatted postcode text, not stored in DynamoDB.