Address Lookup Tutorial: Typeahead → Resolve → Enriched Property in Under 50 Lines

# No API key required
curl "https://api.homedata.co.uk/api/address/find/?q=10+downing+street"

import requests

# No API key required
resp = requests.get(
    "https://api.homedata.co.uk/api/address/find/",
    params={"q": "10 downing street"}
)
suggestions = resp.json()["suggestions"]
for s in suggestions:
    print(s["uprn"], s["address"])

// No API key required
const res = await fetch(
  "https://api.homedata.co.uk/api/address/find/?q=10+downing+street"
);
const { suggestions } = await res.json();
suggestions.forEach(s => console.log(s.uprn, s.address));

{
  "suggestions": [
    {
      "uprn": 100023336956,
      "address": "10 DOWNING STREET, LONDON, SW1A 2AA",
      "postcode": "SW1A 2AA",
      "town": "London"
    },
    {
      "uprn": 10008315461,
      "address": "10A DOWNING STREET, LONDON, SW1A 2AB",
      "postcode": "SW1A 2AB",
      "town": "London"
    }
  ],
  "count": 2
}

The key field is uprn. That's the Unique Property Reference Number — your handle to everything that follows. Store it. Pass it to Retrieve.

You can also filter results to a specific postcode with ?postcode=SW1A, or increase the result count up to 15 with ?limit=10.

Alternative: list all addresses at a postcode

If you already know the postcode — batch processing a dataset, or building a postcode-first lookup flow — use the Postcode endpoint instead. It returns every address at that postcode with full building identifiers. No auth required.

curl "https://api.homedata.co.uk/api/address/postcode/SW1A2AA/"

# Response
{
  "postcode": "SW1A 2AA",
  "count": 3,
  "addresses": [
    {
      "uprn": 100023336956,
      "address": "10 DOWNING STREET, LONDON, SW1A 2AA",
      "building_name": "",
      "building_number": "10",
      "sub_building": "",
      "street": "Downing Street",
      "town": "London"
    }
  ]
}

Each address includes building_number and building_name — useful if you need to chain to an endpoint that requires a building identifier rather than a UPRN.

---

Step 2 — Retrieve: resolve a UPRN to a full property record

Retrieve is where the value is. Pass a UPRN and an enrichment level, and you get back the property record. There are three levels:

• address (default) — formatted address + coordinates
• property — adds bedrooms, property type, EPC score, floor area, last sold price
• full — adds predicted value, construction details, structural data, area stats, 55+ fields total

For most form-filling and qualification use cases, level=property is the right call. It's the balance point between data richness and response speed.

curl "https://api.homedata.co.uk/api/address/retrieve/100023336956/?level=property" \
  -H "Authorization: Api-Key YOUR_API_KEY"

import requests

API_KEY = "YOUR_API_KEY"
UPRN = 100023336956

resp = requests.get(
    f"https://api.homedata.co.uk/api/address/retrieve/{UPRN}/",
    params={"level": "property"},
    headers={"Authorization": f"Api-Key {API_KEY}"}
)
prop = resp.json()
print(f"{prop['bedrooms']}bed {prop['property_type']} — EPC {prop['current_energy_efficiency']}")

const API_KEY = "YOUR_API_KEY";
const uprn = 100023336956;

const res = await fetch(
  `https://api.homedata.co.uk/api/address/retrieve/${uprn}/?level=property`,
  { headers: { Authorization: `Api-Key ${API_KEY}` } }
);
const prop = await res.json();
console.log(`${prop.bedrooms}bed ${prop.property_type} — EPC ${prop.current_energy_efficiency}`);

{
  "uprn": 100023336956,
  "full_address": "10 DOWNING STREET, LONDON, SW1A 2AA",
  "address_line_1": "10 Downing Street",
  "address_line_2": "",
  "postcode": "SW1A 2AA",
  "latitude": 51.5034,
  "longitude": -0.1276,
  "level": "property",

  "property_type": "Terraced",
  "bedrooms": 4,
  "bathrooms": 3,
  "epc_floor_area": 248,
  "current_energy_efficiency": 71,
  "potential_energy_efficiency": 83,
  "last_epc_date": "2019-06-14",
  "last_sold_date": "2010-01-12",
  "last_sold_price": 825000
}

With one API call you know: the property is a 4-bed terraced house, EPC Band C (score 71), 248m² floor area, last sold for £825k in 2010. That's a mortgage application pre-filled. Or a lettings listing scaffolded. Or a valuation context built.

The current_energy_efficiency score maps to letter bands: 1–20 = G, 21–38 = F, 39–54 = E, 55–68 = D, 69–80 = C, 81–91 = B, 92–100 = A. You don't need to call the EPC endpoint separately if you just want the band — Retrieve gives you the score and you derive the band yourself.

---

Step 3 — Chain: EPC details and comparable sales

The UPRN from Find is the key to every other endpoint. Here's where the real power shows up: once you have it, a single lookup triggers a cascade of property intelligence.

For an EPC deep-dive — construction age, floor area from the official certificate, EPC id — call the EPC endpoint separately. The code below chains all three: Find → Retrieve → Comparables → EPC, with the same UPRN threading through each step.

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.homedata.co.uk"
HEADERS = {"Authorization": f"Api-Key {API_KEY}"}

# Step 1: Find the address (no key needed)
suggestions = requests.get(
    f"{BASE}/api/address/find/",
    params={"q": "42 acacia avenue, leeds", "limit": 5}
).json()["suggestions"]

if not suggestions:
    raise SystemExit("No results found")

# Pick the first match
uprn = suggestions[0]["uprn"]
address = suggestions[0]["address"]
print(f"Resolved: {address} (UPRN {uprn})")

# Step 2: Enrich the property (key required)
prop = requests.get(
    f"{BASE}/api/address/retrieve/{uprn}/",
    params={"level": "property"},
    headers=HEADERS
).json()

print(f"  Type: {prop.get('property_type')} | Beds: {prop.get('bedrooms')}")
print(f"  Floor area: {prop.get('epc_floor_area')}m²")
print(f"  EPC score: {prop.get('current_energy_efficiency')} (potential: {prop.get('potential_energy_efficiency')})")
print(f"  Last sold: £{prop.get('last_sold_price'):,} on {prop.get('last_sold_date')}")

# Step 3: Pull comparable sales
comps = requests.get(
    f"{BASE}/api/comparables/{uprn}/",
    params={"count": 5},
    headers=HEADERS
).json()

print(f"\nNearby comparables ({comps['total_results']} found):")
for c in comps["comparables"][:3]:
    print(f"  {c['address']} — £{c['sold_let_price']:,} ({c['sold_let_date']})")

# Step 4: EPC deep-dive (construction age, floor area, certificate id)
epc = requests.get(
    f"{BASE}/api/epc-checker/{uprn}/",
    headers=HEADERS
).json()

print(f"\nEPC detail:")
print(f"  Score: {epc['current_energy_efficiency']} → potential {epc['potential_energy_efficiency']}")
print(f"  Floor area: {epc['epc_floor_area']}m²")
print(f"  Construction age: {epc.get('construction_age_band', 'N/A')}")
print(f"  Last assessed: {epc['last_epc_date']}")

const API_KEY = "YOUR_API_KEY";
const BASE = "https://api.homedata.co.uk";
const headers = { Authorization: `Api-Key ${API_KEY}` };

async function resolveAddress(query) {
  // Step 1: Find — no key needed
  const findRes = await fetch(`${BASE}/api/address/find/?q=${encodeURIComponent(query)}`);
  const { suggestions } = await findRes.json();
  if (!suggestions.length) throw new Error("No results");

  const { uprn, address } = suggestions[0];
  console.log(`Resolved: ${address} (UPRN ${uprn})`);

  // Step 2: Retrieve enriched property
  const propRes = await fetch(
    `${BASE}/api/address/retrieve/${uprn}/?level=property`,
    { headers }
  );
  const prop = await propRes.json();
  console.log(`Type: ${prop.property_type} | Beds: ${prop.bedrooms}`);
  console.log(`EPC score: ${prop.current_energy_efficiency}`);
  console.log(`Last sold: £${prop.last_sold_price?.toLocaleString()}`);

  // Step 3: Comparables
  const compRes = await fetch(
    `${BASE}/api/comparables/${uprn}/?count=5`,
    { headers }
  );
  const { comparables, total_results } = await compRes.json();
  console.log(`\nNearby comparables (${total_results} found):`);
  comparables.slice(0, 3).forEach(c =>
    console.log(`  ${c.address} — £${c.sold_let_price?.toLocaleString()} (${c.sold_let_date})`)
  );

  // Step 4: EPC deep-dive
  const epcRes = await fetch(`${BASE}/api/epc-checker/${uprn}/`, { headers });
  const epc = await epcRes.json();
  console.log(`\nEPC detail:`);
  console.log(`  Score: ${epc.current_energy_efficiency} → potential ${epc.potential_energy_efficiency}`);
  console.log(`  Floor area: ${epc.epc_floor_area}m²`);
  console.log(`  Construction age: ${epc.construction_age_band ?? "N/A"}`);
  console.log(`  Last assessed: ${epc.last_epc_date}`);

  return { uprn, prop, comparables, epc };
}

resolveAddress("42 acacia avenue, leeds");

The Python version is 41 lines including whitespace and comments. The JavaScript is 36 lines. Both go from a natural-language search query to a full property record with recent comparables — one resolved UPRN, three API calls.

---

Building the JavaScript widget

Server-side is one pattern. The more common use case is a live typeahead in a browser form. Here's a minimal implementation using vanilla JS and the Find endpoint — no framework, no dependencies:

<input id="address-input" type="text" placeholder="Start typing an address...">
<ul id="suggestions"></ul>

<script>
const API_KEY = "YOUR_API_KEY";
const input = document.getElementById("address-input");
const list = document.getElementById("suggestions");
let debounceTimer;

input.addEventListener("input", () => {
  clearTimeout(debounceTimer);
  const q = input.value.trim();
  if (q.length < 2) { list.innerHTML = ""; return; }

  debounceTimer = setTimeout(async () => {
    // Find: no API key needed
    const res = await fetch(`https://api.homedata.co.uk/api/address/find/?q=${encodeURIComponent(q)}`);
    const { suggestions } = await res.json();
    list.innerHTML = suggestions.map(s =>
      `<li data-uprn="${s.uprn}">${s.address}</li>`
    ).join("");
  }, 200);
});

list.addEventListener("click", async (e) => {
  const li = e.target.closest("li[data-uprn]");
  if (!li) return;

  const uprn = li.dataset.uprn;
  input.value = li.textContent;
  list.innerHTML = "";

  // Retrieve: API key required
  const res = await fetch(
    `https://api.homedata.co.uk/api/address/retrieve/${uprn}/?level=property`,
    { headers: { Authorization: `Api-Key ${API_KEY}` } }
  );
  const prop = await res.json();

  // Auto-fill your form fields
  document.getElementById("bedrooms").value = prop.bedrooms ?? "";
  document.getElementById("property-type").value = prop.property_type ?? "";
  document.getElementById("floor-area").value = prop.epc_floor_area ?? "";
  document.getElementById("epc-score").value = prop.current_energy_efficiency ?? "";
});
</script>

The 200ms debounce prevents hammering the Find endpoint on every keystroke. The Find call has no authentication — the browser can call it directly without exposing your key. The Retrieve call needs an API key, so in production you'd proxy it through your own backend rather than embedding the key in client-side JS.

---

Practical patterns

Pattern 1 — Mortgage or conveyancing intake form

The user types their address into a search field. You resolve it to a UPRN via Find, then call Retrieve at level=full to get predicted value, last sold price, construction age, and structural data. Then call the Flood Risk endpoint separately with the same UPRN for the NAFRA2 flood band. The form auto-fills. Your underwriters get pre-qualified data instead of applicant self-reporting.

Pattern 2 — Lettings platform listing creation

Agent types the property address. Find returns the UPRN. Retrieve at level=property populates: bedrooms, property type, floor area, EPC band. They can override manually if anything's wrong. Listing creation goes from a 5-minute form to a 30-second confirmation.

Pattern 3 — AVM input enrichment

Your automated valuation model needs clean structured inputs. Instead of asking users for property type and bedrooms (which they often get wrong), resolve the address to a UPRN and pull the data directly. Chain to Comparables for recent sales within 0.5 miles with matching bedrooms. You've built a lightweight AVM input pipeline in 50 lines.

Pattern 4 — Insurance quoting

Address search → Retrieve level=full → read current_energy_efficiency, construction_age_band, epc_floor_area. Separately call the Flood Risk endpoint with the same UPRN for NAFRA2 flood band. You have the key risk factors for a buildings insurance quote without the user filling in a single property characteristic.

---

API reference quick look

Next steps

The free tier gives you 100 calls per month — enough to build and test a real integration. When you're ready to go live, the Starter plan at £49/month lifts that to 2,000 calls, and Growth (£149/month) gives you 10,000. Address find and postcode endpoints cost 2 calls each, and address retrieve costs 5 calls — reflecting real licensing costs but still far cheaper than per-lookup competitors.

• Get your API key — free, no card required
• API reference — all endpoints, parameters, and response schemas
• Address Lookup API overview — use cases, pricing, and field reference
• What is a UPRN? — if you want the full backstory on why UPRNs exist