Migrating from Loqate

Stable

Switch from Loqate Capture Interactive to SnapAddress. Compatible Find/Retrieve endpoints — change the base URL and key.

Overview

SnapAddress provides Loqate Capture Interactive compatible endpoints for UK addresses. The two-step Find and Retrieve flow, the request parameters and the response fields are the same, so 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.addressy.com
+ https://api.snapaddress.io

Pass your key as the Key query parameter, as with Loqate.

Step 3: Verify

GET /Capture/Interactive/Find/v1.1/json3.ws?Key=KEY&Text=query

Returns matching postcodes and addresses. For a postcode match, Type is "Postcode" and Id is the postcode itself:

{
  "Items": [
    {
      "Id": "SW1A 2AA",
      "Type": "Postcode",
      "Text": "SW1A 2AA",
      "Highlight": "",
      "Description": "Downing Street - 1 Address"
    }
  ]
}

Pass that Id as Container to list the addresses at the postcode:

GET /Capture/Interactive/Find/v1.1/json3.ws?Key=KEY&Text=SW1A 2AA&Container=SW1A 2AA

The drill-down returns Type: "Address" items, each with an Id you pass to Retrieve. As with Loqate, treat any item that isn't an Address as something to drill into with Container.

Retrieve (get full address)

GET /Capture/Interactive/Retrieve/v1.1/json3.ws?Key=KEY&Id=23747771

{
  "Items": [
    {
      "Id": "23747771",
      "DomesticId": "23747771",
      "Language": "ENG",
      "Company": "Prime Minister & First Lord of the Treasury",
      "BuildingNumber": "10",
      "Street": "Downing Street",
      "City": "London",
      "Line1": "10 Downing Street",
      "PostalCode": "SW1A 2AA",
      "CountryName": "United Kingdom",
      "CountryIso2": "GB",
      "Barcode": "(SW1A2AA1AM)",
      "Label": "Prime Minister & First Lord of the Treasury\n10 Downing Street\nLONDON\nSW1A 2AA\nUNITED KINGDOM",
      "Type": "Commercial",
      "DataLevel": "Premise"
    }
  ]
}

(Abridged — every Loqate Retrieve field is returned, in Loqate's order, including Field1–Field20.) As with Loqate, the organisation is in Company and kept out of Line1–Line5.

Id and DomesticId are the address's Royal Mail UDPRN — store either as a stable reference.

BFPO (British Forces) addresses

BFPO addresses are included. Search by BFPO number (BFPO 16 or BFPO16), or drill straight in with Container=BFPO16. Unlike Loqate, Retrieve keeps the BFPO number in Street and Line1 — so a form filled from Line1 keeps it — and Label reads BFPO 16 / BFPO / BF1 0AB.

Pricing

Find (including drilling into a postcode) is free. Each Retrieve uses one credit. Credits come in one-off packs, valid for 12 months — see the pricing page.

Differences to be aware of

  • IDs: an address Id is the numeric Royal Mail UDPRN (e.g. 23747771), not Loqate's GB|RM|B|23747771|ENG. A postcode result's Id is the postcode, and its Type is "Postcode".
  • Single-address postcodes come back as a Postcode item you drill into, where Loqate returns the address directly.
  • Find display: Highlight is always empty; address Text separates its parts with commas (Flat 1, 2 Cavendish Road); a postcode result's Description names the street (Downing Street - 3 Addresses). Postcode-like text such as BF1 is treated as a postcode district (Loqate also fuzzy-matches it as text). As with Loqate, a postcode typed with a letter for a digit (BF1 OAB) is corrected, but only when the text as typed finds nothing, so a name like "Old Inn" is never turned into a postcode.
  • Retrieve fields we don't populate: AdminAreaName (local authority), Province, SortingNumber1/SortingNumber2, Neighbourhood, Block. ProvinceName is a county derived from the postcode and can differ from Loqate's.
  • Large postcodes: a drill-down returns up to 100 addresses. If more remain, the last item has Type: "Container" — pass its Id back as Container for the next page (free, like any Find). Limit counts that item, so Limit=1 on a postcode that needs paging returns 400.
  • Errors use HTTP status codes with a JSON body (400 bad request, 401 invalid key, 402 out of credits, 422 a Container postcode too broad to return complete, 503 temporarily unavailable), not error items inside a 200 response.
  • UK only: Royal Mail PAF data, updated monthly. Countries is accepted but not needed. Validate, Typeahead and international endpoints aren't available.

Going further

Once migrated, consider the native SnapAddress API: autocomplete returns postcode suggestions in a single call — and, for a street or building search, address suggestions whose udprn goes straight to /v1/addresses/{udprn} — and postcode lookup returns up to 100 addresses per request (total and next_page for larger postcodes).