Fast UK Address Autocomplete in Node.js via Royal Mail PAF

# Fast UK Address Autocomplete in Node.js via Royal Mail PAF

Postio's address autocomplete API returns Royal Mail PAF addresses as you type, in a single GET request from Node.js. This guide shows the full implementation: a debounced typeahead input, a call to the free /address/search endpoint, and a second call to resolve the picked suggestion into the full structured address by its UDPRN.

Why PAF

Royal Mail's Postcode Address File (PAF) is the definitive UK address dataset. Postio is a direct PAF licensee, so results come from the source rather than a scraped or open-data-derived copy.

Prerequisites

• Node.js 18+
• A Postio API key — sign up at https://postio.co.uk; every new account gets 100 free lookups on sign-up (pay as you go after — https://postio.co.uk/pricing)

1. Debounced typeahead search

Every Postio endpoint is a GET returning JSON. Send your key in the x-api-key header:

js const input = document.querySelector('#address'); let timer; input.addEventListener('input', (e) => { clearTimeout(timer); timer = setTimeout(() => autocomplete(e.target.value), 250); });

async function autocomplete(q) { if (q.length < 3) return; const url = https://api.postio.co.uk/v1/address/search?q=${encodeURIComponent(q)}; const res = await fetch(url, { headers: { 'x-api-key': process.env.POSTIO_KEY } }); const { results } = await res.json(); // results: [{ udprn: 50905588, suggestion: '57 Wimpole Street, London, W1G 8YW' }] renderSuggestions(results); }

/address/search is free and not billed — it exists to feed the billable resolve. Postio monitors the ratio, so use it for genuine address entry, not bulk searching.

2. Resolve the picked address by UDPRN

Each suggestion carries a udprn. Resolve it to the full Royal Mail PAF record:

js async function expand(udprn) { const res = await fetch( https://api.postio.co.uk/v1/address/udprn/${udprn}, { headers: { 'x-api-key': process.env.POSTIO_KEY } } ); const { results } = await res.json(); const a = results[0]; // a.address_line_1, a.post_town, a.postcode, a.organisation_name ... }

The address object carries the full PAF record — UDPRN, formatted postcode (plus outward/inward split), up to three address lines, post town, organisation and building fields, thoroughfare, localities, DPS, constituent country — plus OS coordinates and ONS district and ward. The address API reference lists every field the response returns.

Every response follows the same envelope — { success, results, meta } — so you write your parsing once. A valid postcode with no delivery points is a 200 with an empty results array and is not charged.

3. Production notes

• Debounce at 200–300ms and require 3+ characters before calling.
• Never ship your API key to the browser — proxy through your server. Keys are scoped per service and can be locked to specific origins or IP ranges.
• Log the meta.requestId from each response; it is how Postio traces any request you raise.
• Only the resolve is billable, and only on a hit with results.

Full API reference and product page: https://postio.co.uk/products/address

---

*Postio is a UK address validation API and a direct Royal Mail PAF licensee. 100 free lookups on sign-up; pay as you go at https://postio.co.uk/pricing.*