Your customer types three letters. We finish the address.

Two steps, so typing stays free.

Autocomplete is split in two. The list step runs on every keystroke and is free — it returns labels and an opaque id, no coordinates and no components. The retrieve step runs once, when your customer picks an address, and is the only call that counts as a lookup.

# 1. list — free, fires as they type
curl 'https://paf.acuris-geo.com/suggest?country=gbr&q=10+downing&v=2' \
  -H 'X-Acuris-Key: YOUR_KEY'

{"suggestions": [
  { "id": "eyJ2IjozLCJjIjoiZ2Jy…",
    "formatted_address": "10 DOWNING STREET\nLONDON\nSW1A 2AA\nUNITED KINGDOM" }
], "v": 2}

# 2. retrieve — the one billable call, on selection
curl 'https://paf.acuris-geo.com/suggest/retrieve?id=eyJ2IjozLCJjIjoiZ2Jy…' \
  -H 'X-Acuris-Key: YOUR_KEY'

{"address": {
  "street": "DOWNING STREET", "house_number": "10",
  "city": "LONDON", "postcode": "SW1A 2AA",
  "udprn": "23747771", "uprn": "100023336956",
  "lat": 51.503541, "lng": -0.12767
}}

UK autocomplete is served from paf.acuris-geo.com, our dedicated Royal Mail PAF host — a separate endpoint from the 240-country international API.

One endpoint. JSON in, JSON out.

Send a POST request to /postcode-lookup with the postcode and country. UK addresses are served from paf.acuris-geo.com, our dedicated Royal Mail PAF host. The response is a single JSON document with the array of addresses and a count.

Request

# curl
curl -X POST 'https://paf.acuris-geo.com/postcode-lookup' \
  -H 'X-Acuris-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"postcode":"SW1A 2AA","country":"gbr"}'

Response

{
  "postcode": "SW1A2AA",
  "country": "gbr",
  "count": 1,
  "addresses": [
    {
      "street": "DOWNING STREET",
      "house_number": "10",
      "organisation_name": "PRIME MINISTER & FIRST LORD OF THE TREASURY",
      "city": "LONDON",
      "county": "MIDDLESEX",
      "administrative_county": "WESTMINSTER",
      "dependent_locality": "",
      "double_dependent_locality": "",
      "postcode": "SW1A2AA",
      "lat": 51.503541,
      "lng": -0.12767,
      "accuracy_type": "rooftop",
      "udprn": "23747771",
      "uprn": "100023336956",
      "uprn_match_m": 0.0
    }
  ]
}

What’s not included

Honesty about scope:

• No PAF redistribution. Our licence covers querying — you can integrate the API into your product, but you can’t bulk-download our PAF data and resell it.
• Postcode-only Large User addresses — buildings like 10 Downing Street and Buckingham Palace are encoded as postcode-without-street in PAF; those return a postcode-level position, and the response says so.
• Channel Islands & Isle of Man — covered under separate ISO codes (jey, ggy, imn) on the global API, not the UK product.