Property data API for valuers.

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

# Step 2: property record: floor area, type, bedrooms, age band (1 token)
curl "https://api.homedata.co.uk/properties/100023456789/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Step 3: comparable sales: up to 200 nearby sold prices (arranged per customer, not self-serve)
curl "https://api.homedata.co.uk/comparables/100023456789/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Step 4: price trends: outcode median and volatility score (1 token)
curl "https://api.homedata.co.uk/price_trends/BS6/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

import requests

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

def build_desktop_appraisal(address: str) -> dict:
    # Step 1: UPRN lookup (2 tokens)
    r = requests.get(f"{BASE}/address/find/", params={"q": address}, headers=HEADERS)
    suggestion = r.json()["suggestions"][0]
    uprn    = suggestion["uprn"]
    outcode = suggestion["postcode"].split()[0]  # e.g. "BS6"

    # Steps 2-4: property data (sequential or parallel)
    property_data = requests.get(f"{BASE}/properties/{uprn}/", headers=HEADERS).json()
    # comparables: arranged per customer, not self-serve
    comparables   = requests.get(f"{BASE}/comparables/{uprn}/", headers=HEADERS).json()
    price_trends  = requests.get(f"{BASE}/price_trends/{outcode}/", headers=HEADERS).json()

    return {
        "uprn": uprn,
        "subject_property": {
            "type":             property_data.get("property_type"),
            "bedrooms":         property_data.get("bedrooms"),
            "floor_area_sqm":   property_data.get("epc_floor_area"),
            "construction_age": property_data.get("construction_age_band"),
            "tenure":           property_data.get("tenure"),
            "council_tax_band": property_data.get("council_tax_band"),
        },
        "comparables_count": len(comparables.get("comparables", [])),
        "outcode_median":    price_trends.get("median_asking_price"),
        "market_volatility": price_trends.get("volatility_score"),
    }

appraisal = build_desktop_appraisal("42 Church Road Bristol")
print(f"Property: {appraisal['subject_property']['type']}, {appraisal['subject_property']['bedrooms']} bed")
print(f"Floor area: {appraisal['subject_property']['floor_area_sqm']} sqm")
print(f"Comps: {appraisal['comparables_count']} found")
print(f"Outcode median: £{appraisal['outcode_median']:,}")

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

async function buildDesktopAppraisal(address) {
    // Step 1: resolve address to UPRN (2 tokens)
    const findRes  = await fetch(`${BASE}/address/find/?q=${encodeURIComponent(address)}`, { headers: HEADERS });
    const findData = await findRes.json();
    const { uprn, postcode } = findData.suggestions[0];
    const outcode = postcode.split(' ')[0]; // e.g. "BS6"

    // Steps 2-4: fetch in parallel
    const [property, comparables, priceTrends] = await Promise.all([
        fetch(`${BASE}/properties/${uprn}/`,      { headers: HEADERS }).then(r => r.json()),
        // comparables: arranged per customer, not self-serve
        fetch(`${BASE}/comparables/${uprn}/`,     { headers: HEADERS }).then(r => r.json()),
        fetch(`${BASE}/price_trends/${outcode}/`, { headers: HEADERS }).then(r => r.json()),
    ]);

    return {
        uprn,
        subjectProperty: {
            type:            property.property_type,
            bedrooms:        property.bedrooms,
            floorAreaSqm:    property.epc_floor_area,
            constructionAge: property.construction_age_band,
            tenure:          property.tenure,
            councilTaxBand:  property.council_tax_band,
        },
        comparablesCount: comparables.comparables?.length ?? 0,
        outcodeMedian:    priceTrends.median_asking_price,
        marketVolatility: priceTrends.volatility_score,
    };
}

buildDesktopAppraisal('42 Church Road Bristol').then(appraisal => {
    const p = appraisal.subjectProperty;
    console.log(`Property: ${p.type}, ${p.bedrooms} bed, ${p.floorAreaSqm} sqm`);
    console.log(`Comps: ${appraisal.comparablesCount} found`);
    console.log(`Outcode median: £${appraisal.outcodeMedian?.toLocaleString()}`);
});