Property data API for sourcers.

# Step 1: resolve address to UPRN (2 tokens)
curl "https://api.homedata.co.uk/address/find/?q=14+Oak+Avenue+Manchester" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Step 2: comparable sales within 0.5 miles (arranged per customer, not self-serve)
curl "https://api.homedata.co.uk/comparables/100023456789/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  # filter to same type, sold in last 18 months
  # returns sold_let_price, distance_meters, epc_floor_area

# Step 3: price distribution for the outcode (1 token)
curl "https://api.homedata.co.uk/price_distributions/M20/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
  # returns 5 buckets with min/max/count: plot where asking price sits

import requests

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

def bmv_screen(address: str, asking_price: int) -> dict:
    # Step 1: UPRN lookup
    r    = requests.get(f"{BASE}/address/find/", params={"q": address}, headers=HEADERS)
    prop = r.json()["suggestions"][0]
    uprn, postcode = prop["uprn"], prop["postcode"]

    # Step 2: comparable sales (arranged per customer, not self-serve)
    comps = requests.get(
        f"{BASE}/comparables/{uprn}/",
        headers=HEADERS,
        params={"count": 20, "event_type": "sold"}
    ).json().get("comparables", [])

    avg_comp = sum(c["sold_let_price"] for c in comps) / len(comps) if comps else None

    # Step 3: price distribution for outcode (1 token)
    outcode = postcode.split()[0]
    dist    = requests.get(f"{BASE}/price_distributions/{outcode}/", headers=HEADERS).json()
    buckets = dist.get("buckets", [])

    # Find which bucket the asking price falls into
    bucket_label = next(
        (b["label"] for b in buckets if b["min"] 

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

async function bmvScreen(address, askingPrice) {
  // Step 1: UPRN lookup
  const findResp = await fetch(`${BASE}/address/find/?q=${encodeURIComponent(address)}`, { headers });
  const { suggestions } = await findResp.json();
  const { uprn, postcode } = suggestions[0];
  const outcode = postcode.split(' ')[0];

  // Steps 2 + 3: comps (arranged per customer, not self-serve) and distribution in parallel
  const [compsResp, distResp] = await Promise.all([
    fetch(`${BASE}/comparables/${uprn}/?count=20&event_type=sold`, { headers }),
    fetch(`${BASE}/price_distributions/${outcode}/`, { headers }),
  ]);

  const { comparables } = await compsResp.json();
  const { buckets }     = await distResp.json();

  const avgComp = comparables.reduce((s, c) => s + c.sold_let_price, 0) / comparables.length;
  const discountPct = ((1 - askingPrice / avgComp) * 100).toFixed(1);
  const bucket = buckets.find(b => askingPrice >= b.min && askingPrice 
  console.log(`Discount: ${r.discountPct}% | Bucket: ${r.bucket}`)
);