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
| Feature | Postio | getAddress.io |
|---|---|---|
| Data source | Royal Mail Postcode Address File (PAF), licensed direct | No PAF licence claimed |
| Company | Onno Group Limited, England & Wales | GetAddress, LLC — Dover, Delaware |
| Billing model | Pay as you go, per lookup | Monthly or yearly subscription |
| Autocomplete | Yes — search is free, the picked address is billed | Yes (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 ownsub_building_namefield. - 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 field | Postio field | Note |
|---|---|---|
postcode | postcode | Same, formatted with a space |
formatted_address[0..2] | address_line_1 / address_line_2 / address_line_3 | Array becomes named lines |
formatted_address[3] / town_or_city | post_town | Royal Mail post town |
formatted_address[4] | (no equivalent — see note below) | Postio returns district and ward (ONS geography) instead |
thoroughfare | thoroughfare | Same name |
building_number | building_number | Same name |
latitude, longitude | latitude, longitude | Postio adds eastings, northings |
| (none) | udprn | Royal Mail per-delivery-point ID |
| (none) | organisation_name, sub_building_name, po_box | PAF 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 call | Postio call | Notes |
|---|---|---|
GET api.getAddress.io/autocomplete/{term}?api-key={key} | GET api.postio.co.uk/v1/address/search?q={query} with x-api-key header | Postio 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-*.js | Direct REST calls from your own code | No 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/searchtypeahead is free; you are billed only when a suggestion is resolved.
Migration Checklist
- Audit current endpoints: Identify all frontend widgets (
cdn.getaddress.io) and backend API calls (api.getAddress.io). - Map the schema: Use the field table above —
formatted_addressarray → namedaddress_line_*fields,town_or_city→post_town, and decide what to do with the fifthformatted_addresselement. - Verify sub-building requirements: Test edge cases such as multi-occupancy flats, business parks, and newly assigned postcodes.
- Switch API keys and endpoints: Replace the
getAddress.autocompleteor/findJavaScript script tags with the Node.js or Python calls above, key in thex-api-keyheader. - Validate address line formatting: Ensure your database schema correctly receives
address_line_1,address_line_2,post_town,postcode.