API Reference

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.

Endpoints

Find addresses by postcode

GET /v1/postcodes/{postcode}

Returns all addresses at the given UK postcode.

Parameters:

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). 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:

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). Useful for looking up a specific address you have previously stored.

Parameters:

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:

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

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

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.

See also

• Response Format — detailed field breakdown
• Rate Limits & Errors — status codes and troubleshooting
• Migrating from getAddress.io — step-by-step guide
• Migrating from Loqate — step-by-step guide