Migrating from getAddress.io

Overview

SnapAddress provides getAddress.io-compatible endpoints for UK addresses: the same paths, parameters and response fields. Most integrations only need a new base URL and key.

Step 1: Get your API key

Sign up for a SnapAddress account. An API key is generated automatically during onboarding.

Step 2: Change your base URL

- https://api.getAddress.io
+ https://api.snapaddress.io

Pass your key as the api-key query parameter, as with getAddress.io (an x-api-key header also works).

Step 3: Verify

Response format

GET /find/SW1A2AA?api-key=KEY:

{
  "postcode": "SW1A 2AA",
  "addresses": [
    "Prime Minister & First Lord Of The Treasury,10 Downing Street,,,,LONDON,Greater London"
  ],
  "page": 1,
  "limit": 100,
  "total": 1,
  "next_page": null
}

With expand=true:

{
  "postcode": "SW1A 2AA",
  "addresses": [
    {
      "formatted_address": [
        "Prime Minister & First Lord Of The Treasury",
        "10 Downing Street",
        "",
        "LONDON",
        "Greater London"
      ],
      "thoroughfare": "Downing Street",
      "building_name": "",
      "sub_building_name": "",
      "sub_building_number": "",
      "building_number": "10",
      "line_1": "Prime Minister & First Lord Of The Treasury",
      "line_2": "10 Downing Street",
      "line_3": "",
      "line_4": "",
      "locality": "",
      "town_or_city": "LONDON",
      "county": "Greater London",
      "district": "",
      "country": "England",
      "residential": false
    }
  ],
  "page": 1,
  "limit": 100,
  "total": 1,
  "next_page": null
}

Large postcodes (paging)

/find returns up to 100 addresses per request, with page, limit, total and next_page (a SnapAddress addition — getAddress.io returned every address at once). When next_page isn't null, request it with ?page=2, and so on. Each page is one lookup.

Every standard postcode has 100 addresses or fewer, so for almost all lookups the first page is the whole postcode. Follow next_page rather than counting pages: a page beyond the last returns no addresses and is not charged.

BFPO (British Forces) addresses

Look up a BFPO address by its number — /find/BFPO16 — and get exactly that address with its real BF1/BF2 postcode. country is "" for BFPO addresses.

Mistyped postcodes

If a postcode as typed finds nothing and has a letter where a digit belongs (BF1 OAB), the corrected postcode is searched and returned in postcode (BF1 0AB). A postcode that finds results is never changed.

Errors and billing

• 404 {"Message":"Not Found"} — no addresses for a valid postcode (uses a credit, as any completed lookup does), or a malformed postcode (rejected before the search, so free).
• 422 postcode_too_broad — a partial postcode (such as a whole district) matches too many addresses to return complete. Use a longer postcode; retrying gives the same answer. The credit it uses is returned to your account within a few days.
• 429 — your credit balance is exhausted. Top up from the pricing page.
• 401 — missing or invalid key.

Differences to be aware of

• county and district: come from a different source than getAddress.io's and can differ; district (local authority) is empty.
• No latitude/longitude: Royal Mail PAF has no coordinates, so these fields aren't returned.
• Paging: /find adds page, limit, total and next_page (above). Clients that ignore unknown fields are unaffected.
• Unsupported getAddress.io features: domain tokens and autocomplete filter objects.
• UK only: Royal Mail PAF data, updated monthly.

Going further

Once migrated, consider the native SnapAddress API: autocomplete suggestions carry a udprn that goes straight to /v1/addresses/{udprn}, and addresses come with structured fields, a postal label and a Royal Mail barcode.