postio_
Guides

GetAddress.io Alternatives: Direct Royal Mail PAF vs Open-Data APIs (with Migration Code)

Looking for a getAddress.io alternative? Side-by-side API diffs, drop-in Node.js and Python migration code, and direct Royal Mail PAF vs open-data compared.

·

Looking for a getAddress.io alternative? UK address APIs fall into two groups: direct Royal Mail Postcode Address File (PAF) licensees and providers built on other data, such as compiled open datasets. A PAF licensee returns Royal Mail's own delivery-point records; other providers return whatever their source data holds.

This guide covers the differences in data source and pricing model, then gives drop-in Node.js and Python migration code for switching from getAddress.io to Postio.

Summary Comparison

FeaturePostiogetAddress.io
Data sourceRoyal Mail Postcode Address File (PAF), licensed directNo PAF licence claimed
CompanyOnno Group Limited, England & WalesGetAddress, LLC — Dover, Delaware
Billing modelPay as you go, per lookupMonthly or yearly subscription
AutocompleteYes — search is free, the picked address is billedYes (autocomplete + get step)

Data Source Differences

1. Royal Mail PAF (direct licence)

Royal Mail maintains the Postcode Address File (PAF), its database of UK postal delivery points. Every PAF record carries a UDPRN, Royal Mail's own identifier for that delivery point.

  • Sub-building detail: flat and unit names (e.g. Flat 2B) come back in their own sub_building_name field.
  • Organisations: business names at an address come back in organisation_name.
  • Freshness: Royal Mail's updates to PAF are applied daily, so new addresses appear as Royal Mail adds them.

2. Open-data and compiled datasets

Providers without a PAF licence build their address lists from other sources, such as open datasets. getAddress.io now operates as GetAddress, LLC (Dover, Delaware) and does not claim a PAF licence.

  • What to check: whether flats, business names and newly built addresses you care about are present and formatted the way you need them.
  • Update timing: open datasets are refreshed on their publishers' release schedules rather than daily.

Response Schema Diff: getAddress.io vs Postio

The two APIs model an address differently. getAddress.io returns a flat object with a formatted_address array. Postio returns structured PAF fields. Postio also returns ONS district and ward administrative geography alongside the postal fields.

Field-by-field mapping

getAddress.io fieldPostio fieldNote
postcodepostcodeSame, formatted with a space
formatted_address[0..2]address_line_1 / address_line_2 / address_line_3Array becomes named lines
formatted_address[3] / town_or_citypost_townRoyal Mail post town
formatted_address[4](no equivalent — see note below)Postio returns district and ward (ONS geography) instead
thoroughfarethoroughfareSame name
building_numberbuilding_numberSame name
latitude, longitudelatitude, longitudePostio adds eastings, northings
(none)udprnRoyal Mail per-delivery-point ID
(none)organisation_name, sub_building_name, po_boxPAF premise detail

getAddress.io response (from their published examples)

{
  "postcode": "NN1 3ER",
  "latitude": 52.245937,
  "longitude": -0.891636,
  "formatted_address": ["10 Watkin Terrace", "", "", "Northampton", "Northamptonshire"],
  "thoroughfare": "Watkin Terrace",
  "building_number": "10",
  "town_or_city": "Northampton",
  "country": "England"
}

Postio response (per the Postio address docs)

{
  "success": true,
  "results": [
    {
      "udprn": 50905588,
      "postcode": "W1G 8YW",
      "postcode_outward": "W1G",
      "postcode_inward": "8YW",
      "address_line_1": "57 Wimpole Street",
      "post_town": "London",
      "building_number": "57",
      "thoroughfare": "Wimpole Street",
      "country": "England",
      "latitude": 51.5173,
      "longitude": -0.1459
    }
  ],
  "meta": { "countResults": 1, "requestId": "..." }
}

Postio wraps results in a success / results envelope; getAddress.io returns the address object bare. Every Postio result carries a udprn, which is what you resolve a picked suggestion against.

Endpoint Mapping

getAddress.io callPostio callNotes
GET api.getAddress.io/autocomplete/{term}?api-key={key}GET api.postio.co.uk/v1/address/search?q={query} with x-api-key headerPostio search is free; key goes in a header, not the query string
GET api.getAddress.io/get/{id}?api-key={key}GET api.postio.co.uk/v1/address/udprn/{udprn}Billable resolve; the Postio suggestion's udprn replaces getAddress's suggestion id
GET api.getAddress.io/find/{postcode}?api-key={key}GET api.postio.co.uk/v1/address/postcode/{postcode}Lists every delivery point on a postcode
cdn.getaddress.io/scripts/getaddress-autocomplete-*.jsDirect REST calls from your own codeNo vendor script tag required

Drop-in Migration Code

Node.js — before (getAddress.io)

const res = await fetch(
  `https://api.getAddress.io/autocomplete/${encodeURIComponent(term)}?api-key=${KEY}`
);
const { suggestions } = await res.json();

// on user pick:
const picked = await fetch(
  `https://api.getAddress.io/get/${suggestions[0].id}?api-key=${KEY}`
);
const address = await picked.json();
form.town_or_city.value = address.town_or_city;
form.postcode.value = address.postcode;

Node.js — after (Postio)

const BASE = 'https://api.postio.co.uk/v1';
const headers = { 'x-api-key': process.env.POSTIO_API_KEY };

// 1. Typeahead — free, safe for keystrokes
async function search(q, maxResults = 10) {
  const res = await fetch(`${BASE}/address/search?q=${encodeURIComponent(q)}&max_results=${maxResults}`, { headers });
  const body = await res.json();
  return body.results; // [{ udprn, suggestion }]
}

// 2. Resolve the picked suggestion — billable on a hit
async function resolve(udprn) {
  const res = await fetch(`${BASE}/address/udprn/${udprn}`, { headers });
  const body = await res.json();
  return body.results[0];
}

// 3. Or list every delivery point on a postcode
async function byPostcode(postcode) {
  const res = await fetch(`${BASE}/address/postcode/${encodeURIComponent(postcode)}`, { headers });
  const body = await res.json();
  return body.results; // empty array (not an error) if no delivery points
}

// Field mapping from the getAddress.io shape you had before:
function mapLegacy(a) {
  return {
    line1: a.address_line_1,
    line2: a.address_line_2,
    town: a.post_town,        // was town_or_city
    postcode: a.postcode
  };
}

Python — before (getAddress.io)

import requests

r = requests.get(
    f"https://api.getAddress.io/autocomplete/{term}",
    params={"api-key": KEY},
)
suggestions = r.json()["suggestions"]

addr = requests.get(
    f"https://api.getAddress.io/get/{suggestions[0]['id']}",
    params={"api-key": KEY},
).json()

Python — after (Postio)

import requests

BASE = "https://api.postio.co.uk/v1"
HEADERS = {"x-api-key": POSTIO_API_KEY}

def search(q: str, max_results: int = 10) -> list:
    """Typeahead — free."""
    r = requests.get(f"{BASE}/address/search", headers=HEADERS,
                     params={"q": q, "max_results": max_results})
    r.raise_for_status()
    return r.json()["results"]  # [{"udprn": int, "suggestion": str}]

def resolve(udprn: int) -> dict:
    """Resolve a picked suggestion — billable on a hit."""
    r = requests.get(f"{BASE}/address/udprn/{udprn}", headers=HEADERS)
    r.raise_for_status()
    return r.json()["results"][0]

def by_postcode(postcode: str) -> list:
    """Every delivery point on a postcode. Empty list if none."""
    r = requests.get(f"{BASE}/address/postcode/{postcode}", headers=HEADERS)
    r.raise_for_status()
    return r.json()["results"]

The fifth formatted_address element

getAddress.io's fifth formatted_address element has no Postio equivalent. Royal Mail removed that field from PAF in 2000; post town and postcode are the only mandatory elements of a correct UK postal address. Postio returns district and ward (ONS administrative geography) instead — useful for analytics and routing, but not part of the postal address. Either drop the column, or map it from district with that caveat.

Pricing: Pay As You Go vs Subscription Tiers

Subscription plans sell a monthly bucket of lookups: you pay for the bucket whether you use it or not, and you have to move plan when traffic grows. Postio is pay as you go — from as little as 1p a lookup, with current rates on the pricing page.

  • Pay for what you use: you're billed per resolved lookup, with no unused allowance.
  • No plan ceiling: you top up a balance, or turn on auto top-up, rather than hitting a monthly cap.
  • Free search: Postio's /address/search typeahead is free; you are billed only when a suggestion is resolved.

Migration Checklist

  1. Audit current endpoints: Identify all frontend widgets (cdn.getaddress.io) and backend API calls (api.getAddress.io).
  2. Map the schema: Use the field table above — formatted_address array → named address_line_* fields, town_or_city → post_town, and decide what to do with the fifth formatted_address element.
  3. Verify sub-building requirements: Test edge cases such as multi-occupancy flats, business parks, and newly assigned postcodes.
  4. Switch API keys and endpoints: Replace the getAddress.autocomplete or /find JavaScript script tags with the Node.js or Python calls above, key in the x-api-key header.
  5. Validate address line formatting: Ensure your database schema correctly receives address_line_1, address_line_2, post_town, postcode.

Ready in under a minute.

Sign up, grab a key, paste it in. Your first hundred lookups are on us.