Response Format

Top-level response

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

Example:

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

Address object

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

Example:

{
  "line_1": "Prime Minister & First Lord Of The Treasury",
  "line_2": "10 Downing Street",
  "line_3": "",
  "town": "LONDON",
  "county": "Greater London",
  "postcode": "SW1A 2AA",
  "country": "England",
  "udprn": "23747771",
  "formatted_address": "Prime Minister & First Lord Of The Treasury, 10 Downing Street, LONDON, SW1A 2AA",
  "organisation": "Prime Minister & First Lord Of The Treasury",
  "department": "",
  "sub_building": "",
  "building_name": "",
  "building_number": "10",
  "street": "Downing Street",
  "dependent_street": "",
  "double_locality": "",
  "locality": "",
  "po_box": "",
  "parent_udprn": null,
  "type": "commercial",
  "label": "Prime Minister & First Lord Of The Treasury\n10 Downing Street\nLONDON\nSW1A 2AA\nUNITED KINGDOM",
  "barcode": "(SW1A2AA1AM)"
}

Empty fields

Fields that do not apply to a given address are returned as empty strings (""). The one exception is parent_udprn, which is null for standard addresses. 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(", ");

Multiple addresses

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.

Pagination

Results are paginated. total is the number of addresses at the postcode and count the number on this page; page and limit describe the page you received, and next_page is the page to request next, or null on the last page. Follow next_page rather than counting pages: a page beyond the last one returns no addresses and is not charged. 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:

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:

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

Example:

{
  "query": "SW1A",
  "suggestions": [
    {
      "type": "postcode",
      "postcode": "SW1A 1RJ",
      "summary": "SW1A 1RJ - Arlington Street, LONDON",
      "address_count": 57,
      "udprn": null
    }
  ],
  "count": 1
}

A street, building or business-name query returns "address" suggestions instead, each with its own udprn:

{
  "type": "address",
  "postcode": "E6 6WP",
  "summary": "10 Downings, LONDON, E6 6WP",
  "address_count": 1,
  "udprn": "7944730"
}

When the user selects a suggestion:

• "postcode" — call /v1/postcodes/{postcode} to list its addresses.
• "address" — call /v1/addresses/{udprn} to fetch that one address. Two calls from typing to a full address.