Response Format

Stable

Detailed breakdown of the SnapAddress API response object and address fields.

Top-level response

Every successful response from the /v1/postcodes/{postcode} endpoint returns a JSON object with these fields:

Field	Type	Description
`postcode`	string	The postcode in its correctly formatted form (e.g. `"SW1A 2AA"`)
`addresses`	array	Array of address objects at this postcode
`count`	number	Total number of addresses at this postcode (across all pages)
`page`	number	Current page number (starts at `1`)
`limit`	number	Addresses per page (default and maximum `100`)

Example:

{
  "postcode": "SW1A 2AA",
  "count": 1,
  "page": 1,
  "limit": 100,
  "addresses": [...]
}

Address object

Each entry in the addresses array is a structured object with the following fields:

Field	Type	Description
`line_1`	string	Primary address line (building name, number, or organisation)
`line_2`	string	Secondary address line (street name)
`line_3`	string	Tertiary address line (locality or additional detail)
`town`	string	Post town
`county`	string	County (may be empty for addresses in metropolitan areas)
`postcode`	string	Postcode for this address
`country`	string	Country within the UK: `"England"`, `"Scotland"`, `"Wales"`, or `"Northern Ireland"`
`udprn`	string	Royal Mail UDPRN (Unique Delivery Point Reference Number) — a stable identifier for this address
`formatted_address`	string	Full address as a single comma-separated string

Example:

{
  "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"
}

Empty fields

Fields that do not apply to a given address are returned as empty strings (""), never null. You can also use the formatted_address field directly, or build your own:

const fullAddress = [
  address.line_1,
  address.line_2,
  address.line_3,
  address.town,
  address.county,
  address.postcode,
].filter(Boolean).join(", ");

Most postcodes return multiple addresses. The addresses array is ordered as delivered by Royal Mail PAF. A typical residential postcode may return 10-30 addresses, while a business postcode may return fewer.

Note

Some postcodes (e.g. large organisations with a dedicated postcode) may return only a single address.

Pagination

Results are paginated. count is the total number of addresses at the postcode; page and limit describe the page you received. The default limit is 100 (also the maximum), so most postcodes return everything in one call. Request further pages with the page and limit query parameters:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.snapaddress.io/v1/postcodes/SW1A2AA?page=2&limit=50"

Mapping to form fields

A common use case is populating an address form. Here is a typical mapping:

Form field	Source
Address line 1	`line_1`
Address line 2	`line_2`
City / Town	`town`
County	`county`
Postcode	`postcode`
Country	`country`

line_3 can be appended to line 2 or placed in a separate field depending on your form layout. The udprn field is useful for deduplication or as a stable identifier when storing addresses.

Autocomplete response

The /v1/autocomplete endpoint returns a different shape. The top-level object is:

Field	Type	Description
`query`	string	The query you sent
`count`	number	Number of suggestions returned
`suggestions`	array	Array of suggestions (see below)

Each suggestion represents either a postcode (for postcode-shaped queries — many addresses grouped under one postcode) or a single address (for street, building, or business-name queries):

Field	Type	Description
`postcode`	string	The postcode of this suggestion
`summary`	string	Display label. For postcode suggestions: `"<postcode> - <street>, <town>"`. For individual addresses: the full formatted address.
`address_count`	number	Number of addresses represented — greater than 1 for postcode suggestions, always `1` for individual addresses

Example:

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

After the user selects a suggestion, use its postcode value to call /v1/postcodes/{postcode} and retrieve full addresses.

Top-level response

Address object

Empty fields

Multiple addresses

Pagination

Mapping to form fields

Autocomplete response