Property data API
for sourcers.

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 (free)
    r    = requests.get(f"{BASE}/api/address/find/", params={"q": address})
    prop = r.json()["suggestions"][0]
    uprn, postcode = prop["uprn"], prop["postcode"]

    # Step 2 — comparable sales (2 calls)
    comps = requests.get(
        f"{BASE}/api/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 call)
    outcode = postcode.split()[0]
    dist    = requests.get(f"{BASE}/api/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"] <= asking_price <= b["max"]),
        "above market"
    )

    discount_pct = round((1 - asking_price / avg_comp) * 100, 1) if avg_comp else None

    return {
        "uprn":         uprn,
        "asking_price": asking_price,
        "avg_comp":     avg_comp,
        "discount_pct": discount_pct,
        "market_bucket": bucket_label,
    }

result = bmv_screen("14 Oak Avenue Manchester", 180_000)
print(f"Asking: £{result['asking_price']:,} | Avg comp: £{result['avg_comp']:,.0f}")
print(f"Discount: {result['discount_pct']}% | Bucket: {result['market_bucket']}")

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 (free)
  const findResp = await fetch(`${BASE}/api/address/find/?q=${encodeURIComponent(address)}`);
  const { suggestions } = await findResp.json();
  const { uprn, postcode } = suggestions[0];
  const outcode = postcode.split(' ')[0];

  // Steps 2 + 3 — comps and distribution in parallel
  const [compsResp, distResp] = await Promise.all([
    fetch(`${BASE}/api/comparables/${uprn}/?count=20&event_type=sold`, { headers }),
    fetch(`${BASE}/api/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 <= b.max)?.label ?? 'above market';

  return { uprn, askingPrice, avgComp: Math.round(avgComp), discountPct, bucket };
}

bmvScreen('14 Oak Avenue Manchester', 180000).then(r =>
  console.log(`Discount: ${r.discountPct}% | Bucket: ${r.bucket}`)
);