How do I add UK address autocomplete with the Postio API?

Call GET /address/search?q= on each keystroke to get suggestions, each with a UDPRN. When the user selects one, call GET /address/udprn/{udprn} to fetch the full structured address. /address/search is free; the resolve step is billable on a hit.

Where does Postio address data come from?

Postio address data is Royal Mail PAF (Postcode Address File), enriched with OS Code-Point geographic coordinates and ONS administrative geography (district and ward). It is not derived from open data.

Does the Postio address API return a county?

No. Royal Mail removed the postal county from PAF in 2000, so Postio does not return one. It returns district and ward from ONS administrative geography instead, both flagged as non-postal fields.

Endpoints

Address

Postio address lookup covers the whole flow: search as the user types, then resolve the single full address they pick by its UDPRN, or list every delivery point on a postcode. Data is Royal Mail PAF.

The typical flow

Most integrations use two calls. First, /address/search turns what the user has typed into a short list of suggestions (free, and fast enough for keystroke-level typeahead). Each suggestion carries a udprn. When the user picks one, call /address/udprn/{udprn} to get the full, structured address. If you only have a postcode, use /address/postcode/{postcode} to list every address on it.

Search (typeahead)

GET/address/search?q={query}

Free. Returns typeahead suggestions for a partial address or postcode. Each result is a udprn and a single-line suggestion label. Pass the query as q; an optional max_results caps how many come back (default 10, max 50).

Search is free because it exists to feed a billable lookup: the user picks a suggestion and you resolve it by UDPRN. We monitor that relationship — a high volume of /address/search calls with no matching billable resolves is treated as abuse and can lead to the key being suspended. Use it for genuine address entry, not as a free bulk-search or scraping endpoint.

curl "https://api.postio.co.uk/v1/address/search?q=57+wimpole" \
  -H "x-api-key: pk_..."

{
  "success": true,
  "results": [
    { "udprn": 50905588, "suggestion": "57 Wimpole Street, London, W1G 8YW" }
  ],
  "meta": { "countResults": 1, "requestId": "..." }
}

Resolve by UDPRN

GET/address/udprn/{udprn}

Billable on a hit. Returns the one full address for a UDPRN — the call you make after the user picks a suggestion.

curl "https://api.postio.co.uk/v1/address/udprn/50905588" \
  -H "x-api-key: pk_..."

List by postcode

GET/address/postcode/{postcode}

Billable on a hit. Returns every delivery point on a postcode. A valid postcode with no delivery points is a 200 with an empty results array, and is not charged.

curl "https://api.postio.co.uk/v1/address/postcode/W1G+8YW" \
  -H "x-api-key: pk_..."

The address object

Both /address/udprn and /address/postcode return full address objects with these fields:

Field	Type	Description
udprn	integer	Unique Delivery Point Reference Number — Royal Mail’s per-address ID.
postcode	string	Full postcode, formatted with a space.
postcode_outward	string	Outward code (the part before the space).
postcode_inward	string	Inward code (the part after the space).
postcode_type	string	Small user (S) or large user (L).
address_line_1	string	First formatted address line.
address_line_2	string	Second formatted address line, where present.
address_line_3	string	Third formatted address line, where present.
post_town	string	Royal Mail post town — a mandatory element of a correct UK address.
organisation_name	string	Business at the address, where present.
department_name	string	Department within an organisation, where present.
building_name	string	Named building, e.g. "Trym Lodge".
building_number	string	Numbered building.
sub_building_name	string	Flat or unit within a building.
po_box	string	PO Box number, where the address is a PO Box.
thoroughfare	string	Street name.
dependent_thoroughfare	string	Secondary street, where two share a name.
dependent_locality	string	Locality within the post town.
double_dependent_locality	string	Further locality qualifier, rarely used.
delivery_point_suffix	string	Two-character DPS code for the delivery point.
country	string	Constituent country (England, Scotland, Wales, Northern Ireland).
district	string	Administrative district or unitary authority. ONS administrative geography, not Royal Mail postal data — not part of the postal address.
ward	string	Electoral ward. ONS administrative geography, not Royal Mail postal data — not part of the postal address.
latitude	number	WGS84 latitude of the postcode centroid.
longitude	number	WGS84 longitude of the postcode centroid.
eastings	integer	OS National Grid easting.
northings	integer	OS National Grid northing.

Why there is no county field

Postio does not return a county field, on purpose. Royal Mail removed the Former Postal County from PAF in 2000; post town and postcode are the only mandatory elements of a correct UK postal address, and the incumbents who still licence county data recommend discarding it. We return district and ward instead — ONS administrative geography, useful for analytics and routing, and clearly marked as non-postal.

FAQ

How do I add UK address autocomplete with the Postio API?: Call GET /address/search?q= on each keystroke to get suggestions, each with a UDPRN. When the user selects one, call GET /address/udprn/{udprn} to fetch the full structured address. /address/search is free; the resolve step is billable on a hit.
Where does Postio address data come from?: Postio address data is Royal Mail PAF (Postcode Address File), enriched with OS Code-Point geographic coordinates and ONS administrative geography (district and ward). It is not derived from open data.
Does the Postio address API return a county?: No. Royal Mail removed the postal county from PAF in 2000, so Postio does not return one. It returns district and ward from ONS administrative geography instead, both flagged as non-postal fields.