API Reference

Stable

Complete reference for the SnapAddress API — endpoints, authentication, and request format.

Base URL

https://api.snapaddress.io/v1

All API requests must use HTTPS. The getAddress.io and Loqate compatibility endpoints are mounted at the root (https://api.snapaddress.io), not under /v1.

Authentication

Pass your API key using the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" "https://api.snapaddress.io/v1/postcodes/SW1A2AA"

The native /v1 endpoints accept the key in the x-api-key header only. The compatibility endpoints additionally accept a query-parameter key (api-key for getAddress.io, Key for Loqate) to match the APIs they replace.

Keep your key server-side — passing it in the header keeps it out of browser history and access logs.

You can generate API keys from the dashboard. Each key is scoped to your account and can be revoked at any time.

Warning

Do not expose your API key in client-side code. Make API calls from your server and return the results to your frontend.

Endpoints

Which endpoints spend a credit

A lookup is one completed address search: a full postcode lookup, or an address selected from autocomplete. Searching as the customer types is free, so one completed address search uses exactly one lookup.

Charged — 1 credit	Free — needs a key with a balance above zero
`GET /v1/postcodes/{postcode}`	`GET /v1/autocomplete`
`GET /v1/addresses/{udprn}`	`GET /autocomplete/{query}` (getAddress.io-compatible)
`GET /find/{postcode}` (getAddress.io-compatible)	Loqate `Find`
`GET /get/{id}` (getAddress.io-compatible)
Loqate `Retrieve`

GET /plan is read-only: it never spends a credit and works at a zero balance.

A charged request that returns no match (404) still spends a credit — Royal Mail's Transaction definition covers the verification of a query, not just the data it returns. Requests rejected before the search runs (400, 401, 429, 402) never spend one. Full detail in Rate Limits & Errors.

Find addresses by postcode

GET /v1/postcodes/{postcode}

Returns all addresses at the given UK postcode. Spends one credit. Up to 100 addresses are returned per request; postcodes holding more are paged with page, and each page is a separate lookup.

Parameters:

Parameter	Type	Required	Description
`postcode`	path	Yes	UK postcode (spaces optional, case insensitive)
`x-api-key`	header	Yes	Your API key
`page`	query	No	Page number, starting at `1` (default `1`)
`limit`	query	No	Addresses per page, `1`–`100` (default `100`)

Example request:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.snapaddress.io/v1/postcodes/SW1A2AA"

Example response:

{
  "postcode": "SW1A 2AA",
  "count": 1,
  "page": 1,
  "limit": 100,
  "addresses": [
    {
      "line_1": "Prime Minister & First Lord Of The Treasury",
      "line_2": "10 Downing Street",
      "line_3": "",
      "town": "LONDON",
      "county": "",
      "postcode": "SW1A 2AA",
      "country": "England",
      "udprn": "23747771",
      "formatted_address": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, LONDON, SW1A 2AA"
    }
  ]
}

Autocomplete

GET /v1/autocomplete?q={query}

Search by partial postcode, street, building, or business name (minimum 2 characters). Free — this endpoint does not spend a credit, but it does require a key with a balance above zero. The response shape depends on the query:

Postcode-shaped queries (e.g. SW1A, PL1) return suggestions grouped by postcode — each suggestion is one postcode with its address_count. Up to 15 are returned.
Street, building, or business name queries (e.g. Armada, Iceland) return individual matching addresses, each with an address_count of 1. Up to 12 are returned.

Parameters:

Parameter	Type	Required	Description
`q`	query	Yes	Search text — minimum 2 characters. Shorter queries return a `400` error.
`limit`	query	No	Maximum suggestions, `1`–`20` (default `10`)
`x-api-key`	header	Yes	Your API key

Tip

Check q.length >= 2 before calling the API. Autocomplete is free, so this costs you nothing either way — it just avoids a pointless round-trip on the first keystroke. Show a hint like "Keep typing for results..." instead.

Example request:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.snapaddress.io/v1/autocomplete?q=SW1A"

Example response:

{
  "query": "SW1A",
  "count": 2,
  "suggestions": [
    {
      "postcode": "SW1A 2AA",
      "summary": "SW1A 2AA - Downing Street, LONDON",
      "address_count": 4
    },
    {
      "postcode": "SW1A 2AB",
      "summary": "SW1A 2AB - Whitehall, LONDON",
      "address_count": 12
    }
  ]
}

Use the returned postcode to fetch full addresses via the Find addresses by postcode endpoint above.

Get address by UDPRN

GET /v1/addresses/{udprn}

Retrieve a single address by its Royal Mail UDPRN (Unique Delivery Point Reference Number). Spends one credit. Useful for looking up a specific address you have previously stored.

Parameters:

Parameter	Type	Required	Description
`udprn`	path	Yes	The UDPRN of the address
`x-api-key`	header	Yes	Your API key

Example request:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.snapaddress.io/v1/addresses/23747771"

Example response:

{
  "line_1": "Prime Minister & First Lord Of The Treasury",
  "line_2": "10 Downing Street",
  "line_3": "",
  "town": "LONDON",
  "county": "",
  "postcode": "SW1A 2AA",
  "country": "England",
  "udprn": "23747771",
  "formatted_address": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, LONDON, SW1A 2AA"
}

Check your credit balance

GET /plan

Returns the spendable credit balance for your account, plus the expiry of the soonest-to-expire credit pack. Mounted at the root, not under /v1. Read-only — this endpoint does not consume a credit.

Parameters:

Parameter	Type	Required	Description
`x-api-key`	header	Yes	Your API key

Example request:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.snapaddress.io/plan"

Example response:

{
  "balance": 447,
  "soonest_expiry": "2027-06-01T00:00:00+00:00"
}

balance is the total of all non-expired credits. soonest_expiry is when the pack spent next (under FIFO) expires, or null if you have no live credits.

Postcode formatting

The API accepts postcodes with or without spaces, in any case. All of these are equivalent:

SW1A 2AA
sw1a2aa
SW1A2AA
sw1a 2aa

The response always returns the postcode in its correctly formatted form.

Content type

All responses are returned as application/json with UTF-8 encoding.

CORS

The API supports CORS, so requests can be made directly from a browser. However, this exposes your API key in client-side code. For production use, we recommend proxying requests through your own server to keep your key secure.

Compatibility endpoints

SnapAddress provides drop-in compatible endpoints for teams migrating from other providers. Change your base URL — keep your existing integration. These endpoints are mounted at the root (https://api.snapaddress.io), not under /v1.

getAddress.io compatibility

These endpoints mirror the getAddress.io request paths and response shapes. Auth uses the api-key query parameter (the x-api-key header also works).

Endpoint	Description
`GET /autocomplete/{query}?api-key=KEY`	Address autocomplete. Free — no credit spent. Returns `{ suggestions: [{ id, address, url }] }`
`GET /find/{postcode}?api-key=KEY`	Find addresses by postcode. Spends one credit. Returns `{ postcode, addresses }`, where `addresses` is an array of comma-separated strings
`GET /find/{postcode}?api-key=KEY&expand=true`	Same, but `addresses` is an array of structured objects (`line_1`–`line_4`, `locality`, `town_or_city`, `county`, `district`, `country`, `building_number`, `building_name`, `thoroughfare`, `residential`)
`GET /get/{id}?api-key=KEY`	Retrieve a single address by ID (the `id` is the UDPRN). Spends one credit.

Latitude and longitude are not returned (the underlying PAF data has no geo component). See the getAddress.io migration guide for a step-by-step walkthrough.

Loqate compatibility

These endpoints mirror the Loqate Capture Interactive API. Auth uses the Key query parameter (the api-key query parameter or x-api-key header also work).

Endpoint	Description
`GET /Capture/Interactive/Find/v1.1/json3.ws?Key=KEY&Text=query&Countries=GB`	Search for addresses. Free — no credit spent. Returns `{ Items: [{ Id, Type, Text, Highlight, Description }] }`
`GET /Capture/Interactive/Retrieve/v1.1/json3.ws?Key=KEY&Id=id`	Retrieve a full address by ID. Spends one credit. Returns `{ Items: [{ Line1, Line2, City, PostalCode, ... }] }`

The Find endpoint supports the Container parameter for drill-down searches. When a result has Type: "Postcode", its Id is the postcode itself — pass that value as Container to expand it into individual addresses. See the Loqate migration guide for the full flow.