Skip to main content
29M UK properties, one API call. Get an API key →
Back to Blog
Developer & API Dec 8, 2025 · 4 min read

Address match tutorial: match an address and postcode, then enrich by UPRN

Match an address and postcode using the Homedata API, handle free 422 failures, and enrich by UPRN with Python or JavaScript.

Homedata Team · Updated

Match an address, then enrich the property

Collect a street address and postcode, submit them from your backend, and use the matched UPRN for property data. Address match is a matching endpoint: it resolves a submitted address to one property. It does not return search suggestions as someone types.

You need a Homedata API key and Python with requests, or Node.js 18+ with fetch. Keep the API key on your server. For a browser address picker, use the address widget.

1. Submit the address and postcode

Call GET /address/match/ with both address and postcode. On HTTP 200, the response is the address-level retrieve body plus address_resolution. The successful match costs 5 tokens and already includes the address fields, so you do not need a second address retrieve call.

curl --get "https://api.homedata.co.uk/address/match/" \
  --data-urlencode "address=10 Downing Street" \
  --data-urlencode "postcode=SW1A 2AA" \
  -H "Authorization: Api-Key YOUR_API_KEY"

2. Handle an unmatched or ambiguous submission

HTTP 422 has reason: no_match if no property matches, or reason: multiple_matches if the address is ambiguous. These failures are never charged. Ask for a corrected address or missing flat or building details; do not silently choose a candidate.

Python

import os
import requests

BASE = "https://api.homedata.co.uk"
headers = {"Authorization": f"Api-Key {os.environ['HOMEDATA_API_KEY']}"}

response = requests.get(
    f"{BASE}/address/match/",
    params={"address": "10 Downing Street", "postcode": "SW1A 2AA"},
    headers=headers,
    timeout=30,
)
if response.status_code == 422:
    reason = response.json()["reason"]
    raise ValueError(f"Check the address and postcode: {reason}. No tokens charged.")
response.raise_for_status()
matched = response.json()
print(matched["uprn"], matched["address_resolution"])

# Enrich only after a successful match.
epc = requests.get(
    f"{BASE}/epc-checker/{matched['uprn']}/",
    headers=headers,
    timeout=30,
)
epc.raise_for_status()
print(epc.json())

JavaScript (server)

const BASE = 'https://api.homedata.co.uk';
const headers = { Authorization: `Api-Key ${process.env.HOMEDATA_API_KEY}` };
const params = new URLSearchParams({
  address: '10 Downing Street', postcode: 'SW1A 2AA',
});
const response = await fetch(`${BASE}/address/match/?${params}`, { headers });
const matched = await response.json();
if (response.status === 422) {
  throw new Error(`Check the address and postcode: ${matched.reason}. No tokens charged.`);
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(matched.uprn, matched.address_resolution);

const epc = await fetch(`${BASE}/epc-checker/${matched.uprn}/`, { headers });
if (!epc.ok) throw new Error(`HTTP ${epc.status}`);
console.log(await epc.json());

3. Choose the data you need

The matched UPRN is the common key for EPC, risk and property endpoints. Each further call has its own published token cost. A postcode lookup is available when you need every address at a postcode; it is a separate workflow.

See the endpoint reference, SDK examples and token costs.