# Homedata API — Full Reference for AI Ingestion ## Updated 2026-09-08 > Complete content for AI assistants. Base URL: https://api.homedata.co.uk/api/ > Auth: `Authorization: Api-Key YOUR_KEY` header on every request. > All responses are JSON. See https://homedata.co.uk/docs for the human-readable version. --- ## About Homedata Homedata is a UK property data API built by the HM Haus Group, a property technology company based in England. The API provides structured, UPRN-level access to 29 million properties across England and Wales, aggregating data from HM Land Registry, the Environment Agency, Ordnance Survey, DLUHC, Ofsted/DfE GIAS, and the Office for National Statistics into a single REST interface. Homedata exposes the full property listing-event chain — Added, Reduced, Withdrawn, Sold STC, Re-listed — matched to a UPRN and queryable over time, delivered via a licensed data feed. --- ## Quick Facts - **Properties indexed**: 29 million (England and Wales) - **Listing data**: licensed market data feed - **Price history depth**: 30 years (HM Land Registry) - **Schools**: 27,000+ from DfE GIAS (Get Information About Schools) - **Risk layers per property**: 7 (flood, radon, coal mining, landfill, noise, air quality, invasive plants) - **Event chain**: Added → Reduced → Withdrawn → Sold STC → Re-listed → Completed - **Unique identifier**: UPRN (Unique Property Reference Number) — Ordnance Survey AddressBase - **API style**: REST/JSON, key-auth, HTTPS - **Base URL**: https://api.homedata.co.uk/api/ - **Playground**: https://homedata.co.uk/try (no sign-up required) - **Free plan**: 100 calls/month, no credit card - **Data sources**: HM Land Registry, Environment Agency, Ordnance Survey, DLUHC, Ofsted/DfE GIAS, ONS, Police UK - **Not covered**: Scotland, Northern Ireland (separate land registries, not yet integrated) - **Not scraping**: Data is licensed, not scraped from portals --- ## API Surface — All Endpoints Every plan, including Free, reaches every self-serve endpoint below. Plans differ only on the monthly call allowance. The exception is the Premium section at the end: on-request products scoped per customer, not callable with a standard key. Paths are relative to `https://api.homedata.co.uk/api/`; trailing slashes matter. Send `Authorization: Api-Key YOUR_KEY`. ### Property tiers — one UPRN in, fixed depth out, fixed cost **GET /property/{uprn}/address/** - Weight: 5 calls - Purpose: Address fields only — full address, postcode, coordinates, USRN/TOID/UDPRN. Replaces /api/address/retrieve/. 5 calls. - Params: `uprn` (required) **GET /property/{uprn}/base/** - Weight: 10 calls - Purpose: House-shopper decision card — address + rooms + EPC + lr_title + last sold + construction + dimensions + garden/parking. Flat 10 calls. - Params: `uprn` (required) **GET /property/{uprn}/core/** - Weight: 25 calls - Purpose: Complete listing card — everything in Base + council tax band + flood + schools + broadband + crime + demographics + valuations + solar + lr_sales + title boundary + planning constraints (listed building / conservation area / designations). Flat 25 calls. - Params: `uprn` (required) **GET /property/{uprn}/complete/** - Weight: 50 calls - Purpose: Full property report — everything in Core + council tax FULL (GBP charges) + full title (ownership + boundary) + comparables + live listings + full environmental risks + deprivation + planning application history + price trends/distributions/growth. Flat 50 calls. - Params: `uprn` (required) **GET /property/{uprn}/** - Weight: 1 call - Purpose: Discovery menu — what data is available for this UPRN, per-slug cost, and tier shortcut paths. 1 call. Doubles as a "is this UPRN known to us" check. - Params: `uprn` (required) **GET /property/{uprn}/** - Weight: 1 call for the base record plus the sum of the selected `?with=` add-ons (the Discovery menu lists each add-on's price) - Purpose: Pick-and-choose — sum of individual slug weights. Same URL as Discovery, but supplying ?with=slug1,slug2 turns it into a custom chain. Pay only for what you ask for. - Params: `uprn` (required) ### Property attributes Pick one fact about one UPRN — cheaper than a tier when you only need one field. Need several? Build your own ?with= chain. **GET /properties/{uprn}/rooms/** - Weight: 1 call - Purpose: Bedrooms, bathrooms, habitable rooms, heated rooms. 1 call. - Params: `uprn` (required) **GET /properties/{uprn}/roof/** - Weight: 1 call - Purpose: Roof material, shape, and whether solar panels are present. 1 call. - Params: `uprn` (required) **GET /properties/{uprn}/garden/** - Weight: 1 call - Purpose: Presence and type(s) of garden — rear, front, patio, etc. 1 call. - Params: `uprn` (required) **GET /properties/{uprn}/parking/** - Weight: 1 call - Purpose: Presence and type(s) of parking — driveway, off-street, garage, etc. 1 call. - Params: `uprn` (required) **GET /properties/{uprn}/dimensions/** - Weight: 1 call - Purpose: Geometry area (m²), building height, estimated volume, predicted floor area. 1 call. - Params: `uprn` (required) **GET /properties/{uprn}/land/** - Weight: 1 call - Purpose: Land area (m²) for the property plot. Not available for flats/apartments/maisonettes — returns 400 with no call charged. - Params: `uprn` (required) **GET /properties/{uprn}/construction/** - Weight: 1 call - Purpose: Construction age band, primary construction material, basement presence. 1 call. - Params: `uprn` (required) **GET /properties/{uprn}/epc/** - Weight: 1 call - Purpose: Energy Performance Certificate — current and potential energy efficiency rating, EPC floor area, and last inspection date. 1 call. Distinct from EPC Renovations (which returns the recommended works + costs). - Params: `uprn` (required) **GET /properties/{uprn}/epc_renovations/** - Weight: 1 call - Purpose: Recommended renovations from the EPC assessment with min / max cost estimates. 1 call. - Params: `uprn` (required) **GET /council_tax_band/{uprn}/** - Weight: 3 calls - Purpose: Council tax band, billing authority name and GSS code. Light response — for yearly + monthly charge in GBP and the full bundle, use Council Tax. 3 calls. England, Scotland and Wales. - Params: `uprn` (required) **GET /council_tax/{uprn}/** - Weight: 5 calls - Purpose: Full council tax bundle for a UPRN: band, billing authority + GSS code, current-year yearly and monthly charge in GBP, 1991 valuation band bounds, fiscal year and source URL. 5 calls. England, Scotland and Wales. - Params: `uprn` (required) **GET /property_lr_titles/{uprn}/** - Weight: 10 calls - Purpose: Land Registry title records for a property — tenure (freehold/leasehold), registered owner, and title number. - Params: `uprn` (required) **GET /risks/{risk_type}/** - Weight: 1 call per hazard or flood layer; `all` is 5 calls - Purpose: Environmental risk scores — flood, radon, noise, landfill, coal mining, invasive plants, air quality. - Params: `uprn` (optional); `lat` (optional, alternative to the previous param); `lng` (optional, alternative to the previous param) - `risk_type` values: `all`, `flood`, `radon`, `landfill`, `coal_mining`, `non_coal_mining`, `noise`, `air_quality_today`, `invasive_plants`. `all` returns every hazard row in one response. **GET /risks/flood/{layer}/** — the flood evidence family (canonical) - Layers: `zones`, `history`, `defences`, `storage-areas`, `warning-areas`, `reservoir`, `climate` - Weight: 1 call per layer - Params: `uprn` (one of), or `lat` + `lng` (one of, WGS84). UPRN wins if both are sent - Purpose: `/risks/flood/` is the headline risk band; the layers are the evidence behind it — planning flood zones 2 and 3 (undefended), recorded floods since 1703, defences with standard of protection, flood storage areas, EA warning and alert areas, reservoir failure extents, and 2080s climate projections (UKCP18 RCP8.5) - Every layer echoes a `query` block with `basis` (`title` = assessed against the whole Land Registry title polygon, `point` = the coordinate) and `in_coverage` - Coverage: England only (Environment Agency data). Outside England the response is still 200 with `in_coverage: false` and empty results — treat that as "not assessed", never "not at risk" - Aliases: the older `/flood-risk/…` and `/flood/…` spellings answer forever with a `Link: rel="canonical"` header pointing here, but are not documented **GET /solar-assessment/{uprn}/** - Weight: 5 calls - Purpose: Solar PV potential for a property — roof area, estimated generation (kWh/yr), financial savings, payback period, and CO₂ offset. - Params: `uprn` (required) **GET /broadband/** - Weight: 1 call - Purpose: Ofcom Connected Nations broadband speed data for a UK postcode — avg/max download+upload speeds, superfast/ultrafast/gigabit/full-fibre coverage %, and premises count. 1 API call. - Params: `postcode` (required) **GET /valuations/estimate/** - Weight: 25 calls - Purpose: Sale price or monthly rent estimate from sold/let comparables, active listings, and a local price index. Sold comps are time-adjusted to today's market; the estimate is an outlier-robust weighted median with a 0-100 confidence score. Rent returns monthly + weekly figures. - Params: `uprn` (required); `type` (optional); `bedrooms` (optional); `property_type` (optional); `include_comps` (optional) ### Single property amenities What's near a property — three families, one UPRN, a radius you choose. Open a card for the whole bundle, or a category for one type. **GET /amenities/** - Weight: 5 calls - Purpose: All 11 OSM amenity groups in one response — food, education, healthcare, financial, civic, worship, culture, convenience, green_spaces, transport, shops. 5 calls. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/food/** - Weight: 1 call - Purpose: Cafes, restaurants, pubs, bars, fast food, ice cream, food courts, nightclubs, marketplaces. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/education/** - Weight: 1 call - Purpose: Schools, kindergartens, colleges, universities, childcare, libraries, music/language/driving/dance schools. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/healthcare/** - Weight: 1 call - Purpose: OSM-tagged healthcare — doctors, dentists, clinics, hospitals, pharmacies, veterinary, nursing homes. For CQC-authoritative records (registration ID, region, last-checked date, CQC URL), use the dedicated /healthcare/* endpoints. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/financial/** - Weight: 1 call - Purpose: Banks, ATMs, bureaux de change, money-transfer agents, payment centres. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/civic/** - Weight: 1 call - Purpose: Post offices, town halls, courthouses, fire stations, police, community centres, social facilities. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/worship/** - Weight: 1 call - Purpose: Places of worship — churches, mosques, synagogues, temples, gurdwaras. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/culture/** - Weight: 1 call - Purpose: Theatres, cinemas, arts centres, music venues, museums, galleries, attractions, viewpoints, theme parks, zoos. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/convenience/** - Weight: 1 call - Purpose: Public toilets, charging stations, parcel lockers, internet cafes, animal boarding, give-boxes. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/green_spaces/** - Weight: 1 call - Purpose: Parks, playgrounds, gardens, nature reserves, commons, sports pitches. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/transport/** - Weight: 1 call - Purpose: OSM-side transit — bus stops, ferry terminals, railway stations + halts, tram stops, public-transport platforms. Companion to the NaPTAN-authoritative /transport/ endpoint. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /amenities/shops/** - Weight: 1 call - Purpose: Every OSM-tagged shop — supermarket, clothing, bakery, hardware, convenience, books, the lot. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /fuel-stations/** - Weight: 1 call - Purpose: Petrol stations and EV charging points in one response, each result tagged with its `type`. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /fuel-stations/petrol/** - Weight: 1 call - Purpose: Petrol stations only — OSM amenity=fuel. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /fuel-stations/ev/** - Weight: 1 call - Purpose: EV charging points only — OSM amenity=charging_station. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /healthcare/** - Weight: 3 calls - Purpose: CQC-registered GPs, dentists and hospitals plus OSM-tagged pharmacies in one response. CQC entries carry name, address, postcode, region, distance and CQC location URL, with phone, website and last-checked date wherever the register holds them. CQC covers England only; the pharmacy layer is OpenStreetMap and UK-wide. Refreshed monthly. 3 calls. - Params: `uprn` (required); `radius_km` (optional) **GET /healthcare/gps/** - Weight: 1 call - Purpose: CQC-registered GP practices, straight from the Care Quality Commission register and refreshed monthly. Every entry carries name, address, postcode, region, straight-line distance and its CQC location URL; phone, website and the register's last-checked date arrive wherever CQC holds them, phone numbers without the leading 0. England only — CQC's remit, so Scotland, Wales and Northern Ireland have their own regulators and are not in this feed. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /healthcare/dentists/** - Weight: 1 call - Purpose: CQC-registered dental practices, straight from the Care Quality Commission register and refreshed monthly. Every entry carries name, address, postcode, region, straight-line distance and its CQC location URL; phone, website and the register's last-checked date arrive wherever CQC holds them, phone numbers without the leading 0. England only — CQC's remit, so Scotland, Wales and Northern Ireland have their own regulators and are not in this feed. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /healthcare/pharmacies/** - Weight: 1 call - Purpose: Pharmacies near a property — OpenStreetMap shop=pharmacy (CQC doesn't regulate pharmacies — General Pharmaceutical Council remit). Includes name, address, phone, website from OSM tags where present. 1 call. - Params: `uprn` (required); `radius_km` (optional) **GET /healthcare/hospitals/** - Weight: 1 call - Purpose: CQC-registered hospitals, straight from the Care Quality Commission register and refreshed monthly. Every entry carries name, address, postcode, region, straight-line distance and its CQC location URL; phone, website and the register's last-checked date arrive wherever CQC holds them, phone numbers without the leading 0. England only — CQC's remit, so Scotland, Wales and Northern Ireland have their own regulators and are not in this feed. 1 call. - Params: `uprn` (required); `radius_km` (optional) ### Area Postcode, outcode or boundary-level stats — prices, demographics, amenities, heritage. **GET /boundaries/autocomplete/** - Weight: 1 call - Purpose: Search UK administrative boundaries by name — returns boundary IDs for use with the Live Listings endpoint. 1 call per request. - Params: `q` (required) **GET /price_trends/{outcode}/** - Weight: 1 call - Purpose: Average property prices over time for an outcode area (e.g. SW1A, E1, M1). - Params: `outcode` (required) **GET /price_distributions/{outcode}/** - Weight: 1 call - Purpose: Property price distribution for an outcode — percentiles, median, and count by property type. - Params: `outcode` (required) **GET /price-growth/{outcode}/** - Weight: 1 call - Purpose: Capital appreciation data for an outcode area — annual growth rate, 1Y/3Y/5Y/10Y returns, and historical price index. Computed from Land Registry sold price transactions. - Params: `outcode` (required) **GET /postcode-profile/** - Weight: 1 call - Purpose: All-in-one postcode summary in a single call — deprivation index, crime rate, average property price, school count, transport links, and broadband speed. Replaces 5+ separate endpoint calls. - Params: `postcode` (required) **GET /deprivation/** - Weight: 1 call - Purpose: Index of Multiple Deprivation scores — income, employment, education, health, crime, housing, environment. - Params: `postcode` (required) **GET /demographics/** - Weight: 1 call - Purpose: ONS Census 2021 demographics resolved to the postcode's MSOA (middle-layer super output area, ~7,500 residents). Returns population, tenure breakdown (owned / mortgage / social / private rented / rent-free), age bands, ethnicity, occupation, household size, car ownership, plus MHCLG IMD 2019 deprivation if available. Area codes (LSOA + MSOA + local authority) are in the response so you can link to other ONS datasets. - Params: `postcode` (required) **GET /schools/nearby** - Weight: 1 call - Purpose: Find schools near a postcode — Ofsted ratings, phase, pupil numbers, and distance. ~27,000 open schools in England from the DfE GIAS register. - Params: `postcode` (required); `radius` (optional); `phase` (optional, advanced); `ofsted` (optional, advanced); `limit` (optional, advanced) **GET /planning/search/** - Weight: 5 calls - Purpose: National planning applications near a location — type, status, description, and decision date. 300+ LPAs via PlanIt. Use postcode or lat/lng. - Params: `postcode` (optional); `lat` (optional, alternative to the previous param); `lng` (optional, alternative to the previous param); `radius_km` (optional, advanced); `days` (optional, advanced); `type` (optional, advanced); `status` (optional, advanced) **GET /crime/** - Weight: 1 call - Purpose: Crime statistics near a location — 14 categories sourced from Police UK. Monthly counts and category breakdown. Use postcode or lat/lng. - Params: `postcode` (optional); `lat` (optional, alternative to the previous param); `lng` (optional, alternative to the previous param); `date` (optional, advanced); `category` (optional, advanced) **GET /comparables/{uprn}/** - Weight: 10 calls - Purpose: Comparable properties for valuation — same area, similar size, type, and recent sale window. PostGIS spatial query; slower on the first call (~3–12s) before caches warm. - Params: `uprn` (required) **GET /listed-buildings/** - Weight: 3 calls - Purpose: Historic England listed buildings within a radius of a UK postcode. Returns Grade I / II* / II entries with name, location, list date, and a hyperlink back to the official Historic England record. - Params: `postcode` (required); `radius_km` (optional, advanced); `grade` (optional, advanced) ### Tools Free calculators — no quota cost. Use anywhere, even on a free plan. **GET /calculators/stamp-duty/** - Weight: free — no quota cost - Purpose: Calculate UK Stamp Duty Land Tax (SDLT) for England and Northern Ireland. Returns total tax, effective rate, and a band-by-band breakdown for standard, first-time, or additional-dwelling buyers. Free endpoint — counts zero against your quota. - Params: `price` (required); `buyer_type` (required); `country` (optional, advanced) **GET /calculators/mortgage/** - Weight: free — no quota cost - Purpose: Mortgage repayment calculator — given price + deposit + rate + term, returns monthly payment, total repayment, total interest, LTV and LTI ratios. Free endpoint — counts zero against your quota. - Params: `price` (required); `deposit` (required); `rate` (required); `term_years` (required) ### Address lookup Find an address — by query, postcode, or building. **GET /address/find/** - Weight: 2 calls - Purpose: Search for UK addresses by query string. Returns the raw numeric uprn (a public OS AddressBase id) plus an encrypted uprn_token — either works in any {uprn} endpoint. Costs 2 API calls (weighted billing). - Params: `q` (required) **GET /address/postcode/{postcode}/** - Weight: 2 calls - Purpose: All registered addresses at a postcode. Returns address list with UPRNs. Costs 2 API calls (weighted billing). - Params: `postcode` (required) ### Enterprise — arranged directly (not self-serve) Enterprise products, scoped and priced per customer. They are not part of the self-serve surface and do not count against the call allowance. Do not infer paths or parameters for them — the team agrees coverage, cadence, SLA and price directly. Register interest at https://homedata.co.uk/try. **All Property Listings** — on request - Purpose: Thirty years of listing history for one property — what it asked, how often that was cut, and whether it sold or quietly came off. - Example (illustrative values): Last asking price £325,000; First listed: 30 September 2019; Left the market: Withdrawn; Days on market: 2,537; Price reductions: None; Property: 3 bed detached - Example response shape: `{"count":1,"results":[{"id":"7f9200c5-93be-487a-befa-26aa8667b3e4","street":"Mayfield Park North Fishponds BS16","postcode":"BS16 3NJ","transaction_type":"Sale","latest_price":325000,"bedrooms":3,"bathrooms":1,"reception_rooms":1,"property_type":"Detached","is_reduced":false,"times_reduced":0,"is_withdrawn":true,"days_on_market":2537,"added_date":"2019-09-30"}]}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=property-listings **Sale Events** — on request - Purpose: The negotiation behind the headline price — every price move, offer and withdrawal, dated. - Example (illustrative values): Events on record 3; 30 September 2019: Added; 7 October 2019: Sold STC; 30 March 2020: Withdrawn - Example response shape: `{"count":3,"results":[{"id":53472,"listing":"7f9200c5-93be-487a-befa-26aa8667b3e4","event_type":"Withdrawn","date":"2020-03-30","price":325000},{"id":53471,"listing":"7f9200c5-93be-487a-befa-26aa8667b3e4","event_type":"Sold STC","date":"2019-10-07","price":325000},{"id":53470,"listing":"7f9200c5-93be-487a-befa-26aa8667b3e4","event_type":"Added","date":"2019-09-30","price":325000}]}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=property-sale-events **Land Registry Sales** — on request - Purpose: What actually changed hands, not what was asked — every HM Land Registry confirmed completion, with the date and the real price. - Example (illustrative values): Price paid £310,000; Completion date: 9 April 2020; Against the asking price: £15,000 below; Land Registry txid: A96E4ACB-DBFE-9205-E053-6C04A8C0DA09 - Example response shape: `{"uprn":61263,"count":1,"sales":[{"txid":"A96E4ACB-DBFE-9205-E053-6C04A8C0DA09","sold_let_date":"2020-04-09","sold_let_price":310000,"transaction_type":"Sale"}]}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=lr-sales **Search live listings** — on request - Purpose: Live UK listings on sale or to let, filtered down to the properties worth calling. - Example (illustrative values): Listings matched 10,000+; Terraced · 3 bed · added today: Mayfield Park North, BS16 3NJ; Detached · 2 bed · added today: Cavendish Road, BA1 2UD; Detached · 3 bed · added today: Elmdon Lane, B37 7EQ; Filter on: Reductions, days on market, EPC band, floor area, garden, parking - Example response shape: `{"count":10000,"page":1,"page_size":3,"total_pages":3334,"results":[{"id":"c61d5383-1214-4e6f-b63c-1153863bc50f","street":"Mayfield Park North","postcode":"BS16 3NJ","transaction_type":"Sale","latest_status":"For sale","latest_price":385000,"bedrooms":3,"bathrooms":1,"property_type":"Terraced","ownership":"Freehold","is_new_build":false,"is_reduced":false,"times_reduced":0,"days_on_market":0,"added_date":"2026-09-10"}]}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=live-listings **Unlock UPRN + Address** — on request - Purpose: Turn a listing into a real address — the full postal address and the whole sale history, ready to act on. - Example (illustrative values): Returns UPRN + address + timeline; You send: listing_id; You get: The full postal address; You get: The UPRN; You get: The full event timeline; Already revealed: Free - Example response shape: `{"listing_id":"","uprn":100023336956,"full_address":"10 Downing Street, London SW1A 2AA","charged":true}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=listing-address **Flood risk expert** — on request - Purpose: Everything the Environment Agency knows about flooding at one address — seven layers behind the headline band, 1703 to the 2080s. England only. - Example (illustrative values): Flood outlines within 250 m 10+; Screening band: Surface water — Low; Planning zone 3: Outside; Planning zone 2: Outside; Recorded floods: Five episodes in the ten nearest outlines; Defences: None within 250 m; Storage areas: Not inside one; Warning and alert areas: Inside neither; Reservoir failure: Inside the extent; Climate 2080s: In the extreme river extent - Example response shape: `{"query":{"uprn":100120547768,"country":"England","coverage":["England"],"in_coverage":true,"basis":"title"},"band":{"risk_type":"flood_surface_water","label":"Low","score":2,"score_unit":"band","description":"Between 1 in 1,000 and 1 in 100 chance of flooding each year","confidence":3},"zones":{"source":"EA Flood Map for Planning (undefended fluvial/tidal)","flood_zone_3":{"inside":false,"nearest_m":104.7},"flood_zone_2":{"inside":false,"nearest_m":42.3}},"history":{"source":"EA Recorded Flood Outlines (1703-present)","has_flooded":true,"events_within_250m":[{"name":"March-1947 River Severn","flood_source":"main river","flood_cause":"channel capacity exceeded (no raised defences)","start_date":"1947-03-07","end_date":"1947-04-04","distance_m":0},{"name":"River Swilgate 006 (July 07)","flood_source":"main river","flood_cause":"channel capacity exceeded (no raised defences)","start_date":"2007-07-20","end_date":"2007-07-24","distance_m":43.4}]},"defences":{"source":"EA Spatial Flood Defences","count_within_250m":0,"defences":[]},"storage-areas":{"source":"EA Flood Storage Areas","inside":false,"nearest_m":null},"warning-areas":{"source":"EA Flood Warning and Alert Areas","warning_area":{"inside":false},"alert_area":{"inside":false}},"reservoir":{"source":"EA Reservoir Flood Extents (wet-day worst case)","inside":true,"reservoir":"Cheltenham Racecourse","operator":"The Steeplechase Company (Cheltenham) Ltd","risk_designation":"High-risk"},"climate":{"source":"EA climate-change flood projections (CCP1)","epoch":"2080s (2070-2125)","scenario":"UKCP18 RCP8.5 (high emissions)","river":{"high":{"defended":false,"undefended":false},"extreme":{"defended":true,"undefended":true}},"sea":{"high":{"defended":false,"undefended":false},"extreme":{"defended":false,"undefended":false}}}}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=premium-flood-expert **Plot intelligence** — on request - Purpose: What the plot actually contains — garden size and aspect, whether a car fits on the drive, and whether it has already been extended. Measured, not guessed. - Example (illustrative values): Private garden 138 m²; Extension: Rear, 14 m²; Evidence: Extra building part, lower eaves, off-archetype, approved application; Garden: 138 m² · widest circle 7.4 m; Sun on the garden: 6.2 hrs midsummer; Driveway: 41 m² a car can reach; Way in: 3.1 m gap in the frontage - Example response shape: `{"uprn":100023336956,"extension":{"detected":true,"area_m2":14,"position":"rear","signals":["extra_building_part","eaves_step_down","off_cohort_archetype","approved_application"],"confidence":"high"},"extents":{"title_m2":604,"boundary_basis":"HMLR general boundaries — indicative, screening tolerance","built_m2":96,"private_amenity_m2":138,"shared_m2":0},"garden":{"area_m2":138,"inscribed_circle_m":7.4,"aspect":"south_west","direct_sun_hours_midsummer":6.2},"parking":{"drivable_area_m2":41,"independent_bays":2,"tandem_bays":1,"opening_width_m":3.1,"crossing_consent":"not_verified"},"confidence":{"band":"high","abstained":[]}}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=premium-plot-intelligence **Development suitability** — on request - Purpose: Whether a plot carries a garden room, an annexe or several houses — tested by placing them, not by dividing the area. When it does not fit, you get the reason. A screening indicator, never a promise of consent. - Example (illustrative values): Screening clears 2 extra homes; Garden room or outbuilding: Yes; Annexe: Yes; Extension: Rear, side or loft; One extra house: Yes; Two extra houses: Yes; Three extra houses: No; Consent base rate, same council: 61% granted - Example response shape: `{"title_number":"BK123456","plot_area_m2":604,"development_potential":"high","supports":{"garden_room":true,"annexe":true,"extension":["rear","side","loft"],"extra_dwellings":2},"why_not_three":{"binding_constraint":"access","would_need":"3.3 m easement across the northern boundary"},"each_dwelling_cleared":{"envelope_m2":186,"min_width_m":9,"separation_m":6,"access_route_m":3.4,"parking_spaces":2},"site":{"slope_deg":2.1,"land_type":"brownfield","designations":[],"street_approvals_last_15_years":4},"grant_rate":{"cohort":"same council, infill dwelling, post-2010","decided":148,"granted":91,"rate":0.61,"confidence_interval_95":[0.53,0.69]},"note":"Desk-based screening indicator. Subject to planning."}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=premium-development-suitability **Lender-grade AVM** — on request - Purpose: A valuation you can put in front of a credit committee — a point estimate, a stated confidence band, and what each attribute is actually worth. - Example (illustrative values): Estimated value £412,500; Floor area: 118 m² · 3 bed; Garden: 92 m² · south-facing; EPC rating: C (72); Parking: Driveway · 2 cars; Flood risk: Very low; Construction: 1930s · solid brick - Example response shape: `{"uprn":100023336956,"estimate":412500,"range":{"low":389000,"high":436000},"confidence":84,"forecast_sd_pct":5.7,"attributes":{"floor_area_m2":{"value":118,"vs_area_pct":8.2},"garden_m2":{"value":92,"vs_area_pct":3.4},"epc":{"value":"C","vs_area_pct":2.1},"parking":{"value":"driveway","vs_area_pct":1.6},"flood_risk":{"value":"very_low","vs_area_pct":0},"construction":{"value":"1930s_solid_brick","vs_area_pct":-2.3}},"estimated_at":"2026-09-09"}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=premium-lender-avm **Subsidence risk** — on request - Purpose: Why the ground moves here — the clay, the tree next to the wall, and the mine workings underneath, each with the check that settles it. - Example (illustrative values): Susceptibility Moderate — band 2 of 3; Shrink–swell: Class 2 of 3; Nearest tree: Lone canopy 8 m from the wall; Mine workings: Moderate; Coal reporting area: Outside; Building era: 1930s; Claims history: Not held - Example response shape: `{"uprn":100023336956,"band":"moderate","band_index":2,"band_count":3,"factors":{"shrink_swell":{"source":"BGS GeoSure","hazard_class":2,"class_count":3},"nearest_tree":{"source":"LiDAR trees outside woodland","distance_m":8,"canopy_class":"lone","mean_height_m":14.2,"survey_year":2022},"mine_workings":{"source":"Mining hazard zones","class":"Moderate"},"coal_reporting_area":false,"building_era":"1930s","claims_history":null},"assessed_at":"2026-09-09"}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=premium-subsidence-risk **Land quality** — on request - Purpose: Every abnormal on a title before you instruct anyone — the things that kill a deal at week six, surfaced in week one. - Example (illustrative values): Constraints found 3; Soil: Naturally wet, loamy and clayey; Peat: Across 1.9 ha of the parcel; Flood: Zone 3; Superficial geology: Tidal flat deposits — clay and silt; Bedrock: Ampthill Clay Formation; Aquifer: Principal; Agricultural class: Provisional Grade 2; Permitted waste sites: None within 250 m; Planning: No live applications - Example response shape: `{"title_number":"CB123456","area_ha":2.4,"constraints":["flood_zone_3","peat_extent","principal_aquifer"],"soil":{"source":"Cranfield Soilscapes","texture_class":"loamy and clayey","drainage":"Naturally wet"},"peat":{"source":"Natural England peat soil extent","within_parcel":true,"area_ha":1.9},"geology":{"source":"BGS 1:50,000 DiGMapGB","superficial":"Tidal flat deposits — clay and silt","bedrock":"Ampthill Clay Formation"},"aquifer":{"source":"EA aquifer designation","designation":"Principal"},"alc":{"provisional_grade":"2","basis":"Natural England ALC 1:250,000"},"ea_permitted_waste_within_250m":false,"flood_zone":3,"road_frontage_m":40,"planning":{"live_applications":0,"green_belt":false},"assessed_at":"2026-09-09"}` - Access: enterprise only — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try?endpoint=premium-land-quality --- ## Response Format All successful responses return HTTP 200 with a JSON body. Example — `GET /property/100023336956/core/` (captured from production, lists trimmed to two items): ```json { "uprn": 100023336956, "address": { "full_address": "PRIME MINISTER & FIRST LORD OF THE TREASURY, 10 DOWNING S\u2026", "address": "10 Downing Street", "address_line_1": "10 Downing Street", "address_line_2": null, "address_line_3": null, "sub_building": null, "building_name": null, "building_number": "10", "street_name": "Downing Street", "locality": null, "town_name": "London", "post_town": null, "postcode": "SW1A 2AA", "outward_postcode": "SW1A" }, "property_type": { "property_type": "Terraced", "classification_code": "RD" }, "rooms": { "bedrooms": null, "predicted_bedrooms": 3, "bathrooms": null, "habitable_rooms": null, "heated_rooms": null }, "epc": { "available": false, "reason": "no EPC certificate on file" }, "lr_title": { "title_no": "NGL864428", "estate_interest": "Estate in land", "estate_interest_code": "EL", "title_class": "Absolute freehold title", "title_class_code": "AF", "has_restrictive_covenant": null, "record_status": "A" }, "last_sold": { "available": false, "reason": "no recorded sale" }, "construction": { "construction_age_band": "Pre-1837", "construction_material": "Brick Or Block Or Stone", "has_basement": true }, "dimensions": { "geometry_area_m2": 1427.918, "building_height": 25.6, "estimated_volume": 36554.7008, "predicted_floor_area": 7140 }, "garden": { "has_garden": null, "garden_details": null }, "parking": { "has_parking": null, "parking_details": null }, "council_tax": { "council_tax_band": "H", "authority_name": "Westminster" }, "flood": [ { "risk_type": "flood_rivers_sea", "label": "Very low", "score": 1, "score_unit": "band", "intersects": true, "distance_m": 0, "search_radius_m": 0, "count": 1, "radius_description": "At property", "properties": { "description": "Less than 1 in 1,000 chance of flooding each year", "confidence": null } }, { "risk_type": "flood_surface_water", "label": "Low", "score": 2, "score_unit": "band", "intersects": true, "distance_m": 0, "search_radius_m": 0, "count": 1, "radius_description": "At property", "properties": { "description": "Between 1 in 1,000 and 1 in 100 chance of flooding each year", "confidence": null } } ], "schools": { "query": { "lat": 51.503541, "lng": -0.12767, "radius_km": 3.0, "postcode": null, "uprn": "100023336956", "phase": null, "ofsted": null }, "count": 20, "total_in_radius": 130, "ofsted_summary": { "Good": 19, "Outstanding": 11, "Requires Improvement": 3, "Not yet inspected": 97 }, "schools": [ { "urn": 140939, "name": "Harris Westminster Sixth Form", "type": "Free schools 16 to 19", "type_group": "Free Schools", "phase": "16 plus", "gender": "Mixed", "religious_character": "None", "admissions_policy": null, "age_range": "16-19", "number_of_pupils": 610, "school_capacity": 600, "percentage_fsm": null, "ofsted": { "rating": null, "last_inspection": null }, "address": { "street": "Steel House, 11 Tothill Street", "locality": "Westminster", "town": "London", "county": null, "postcode": "SW1H 9LH" } }, { "urn": 101159, "name": "Westminster Abbey Choir School", "type": "Other independent school", "type_group": "Independent schools", "phase": "Not applicable", "gender": "Boys", "religious_character": "Anglican", "admissions_policy": "Not applicable", "age_range": "8-13", "number_of_pupils": 27, "school_capacity": 32, "percentage_fsm": null, "ofsted": { "rating": null, "last_inspection": null }, "address": { "street": "Dean's Yard", "locality": null, "town": "London", "county": null, "postcode": "SW1P 3NY" } } ], "metadata": { "source": "GIAS \u2014 DfE Get Information About Schools", "coverage": "England (~27,000 open schools)", "note": "Distance is straight-line (as the crow flies)" } } } ``` Every response includes `X-Call-Weight` header showing calls debited. --- ## Error Codes Errors arrive under an `error` key in THREE shapes, and a client must handle all three: 1. Platform envelope (raised: authentication, allowance) — UPPER_SNAKE_CASE code, and the only shape that carries `status`: `{"error": {"code": "INVALID_API_KEY", "message": "...", "status": 403}}` 2. Endpoint coded object (most endpoints) — lowercase code, usually no `status`: `{"error": {"code": "invalid_uprn", "message": "..."}}` 3. Plain string — no code at all: `{"error": "Provide one of: postcode, lat+lng, or uprn"}` The trap is the case difference between 1 and 2: a client comparing `err.code == "BAD_REQUEST"` silently misses `invalid_uprn` and never fires. Branch on the HTTP status first, compare codes case-insensitively, never rely on `error.status` being present, and check whether `error` is a string before reading `error.code`. - **400** Bad request — missing or invalid parameter (e.g. `missing_listing_id`, `missing_idempotency_key`, `invalid_property_type`) - **401** `auth_error` — the key was recognised but its configuration is missing (Explore and listing-address only). A request with NO key does not return 401; it returns 403 `INVALID_API_KEY` - **402** `ALLOWANCE_EXHAUSTED` when the monthly allowance is gone; on reveal endpoints, insufficient reveal credits — body includes `required` (pence) and `available` (pence) - **403** Every key rejection lands here — missing, wrong, revoked, unknown — carrying `INVALID_API_KEY`. Read `message` to tell them apart ("Authentication credentials were not provided." means no key reached us). BUT NOT EVERY 403 IS A KEY PROBLEM: treat a 403 as an authentication failure ONLY when `error` is an object whose `code` equals `INVALID_API_KEY` (compare case-insensitively). A 403 whose `error` is a plain string, or carries any other code, is a permission or plan restriction — the key is fine, and the fix is to remove the filter or change plan, not to replace credentials. Asking the listings endpoint for a filter your plan does not include is exactly that case. `no_organization` means the key is not linked to a credit account. Running out of allowance is not a 403 at all — that is 402 `ALLOWANCE_EXHAUSTED`. Plans never gate endpoints - **404** Property/UPRN/listing not found — **never charged** - **422** Idempotency-Key reused with a different `listing_id` — **never charged** - **500 / 503 / 504** Something failed or timed out on our side — retry with exponential backoff --- ## Credits vs Calls — Two Independent Pots API calls and reveal credits are completely separate billing mechanisms: **Call quota** — debits the monthly subscription allowance: - Resets on each plan renewal date - Most endpoints debit 1 call; the full per-endpoint table is under "Call Weights" - Every response header includes `X-Call-Weight` (calls debited) and `X-Calls-Remaining` **Reveal credits** — debits the £ wallet (pence): - Granted monthly with every paid plan (£49/£149/£349/£699 matching plan price) - **Never expire, never reset** — unused credits carry forward indefinitely - One-off top-up packs: £10 / £40 (20% off) / £140 (30% off) / £300 (40% off) - A customer with 200 calls remaining and £10 of credits can do 200 property lookups AND 50 listing reveals simultaneously --- ## Call Weights Each response carries an `X-Call-Weight` header with the calls debited. Error responses (404, 422) are never charged. | Endpoint | Calls debited | |-----------------------------------|-----------------------------| | GET /address/find/ | 2 | | GET /property/{uprn}/address/ | 5 | | GET /property/{uprn}/base/ | 10 | | GET /property/{uprn}/core/ | 25 | | GET /property/{uprn}/complete/ | 50 | | GET /property/{uprn}/ | 1 + selected ?with= add-ons | | GET /address/postcode/{postcode}/ | 2 | | GET /council_tax_band/{uprn}/ | 3 | | GET /council_tax/{uprn}/ | 5 | | GET /comparables/{uprn}/ | 10 | | GET /property_lr_titles/{uprn}/ | 10 | | GET /planning/search/ | 5 | | GET /solar-assessment/{uprn}/ | 5 | | GET /amenities/ | 5 | | GET /healthcare/ | 3 | | GET /valuations/estimate/ | 25 | | GET /listed-buildings/ | 3 | | GET /calculators/stamp-duty/ | free | | GET /calculators/mortgage/ | free | | GET /risks/all/ | 5 | | Every other endpoint | 1 | --- ## Pricing Plans | Plan | Price/month | Calls/month | Reveal credits/month | Cost per call | |---------|-------------|-------------|----------------------|---------------| | Free | £0 | 100 | £0 | — | | Starter | £49 | 4,500 | £49 | 1.09p | | Growth | £149 | 18,000 | £149 | 0.83p | | Pro | £349 | 70,000 | £349 | 0.50p | | Scale | £699 | 250,000 | £699 | 0.28p | Every plan, including Free, reaches every endpoint. Plans differ on the monthly call allowance only. Reveal credits never expire. Unused monthly calls do not carry over. --- ## Coverage Scope **Included:** - England and Wales — all 29 million residential and commercial properties with a UPRN - Residential listings via licensed market data feed - HM Land Registry sold price data going back 30 years (since 1995) - 27,000+ schools across England (Wales schools in progress) - Environment Agency flood data — risk bands (rivers, sea, surface water), planning Flood Zones 2 and 3, recorded floods since 1703, defences, flood storage areas, warning and alert areas, reservoir failure extents, 2080s climate projections. **England only**: the `/risks/flood/` family returns `in_coverage: false` for Wales, Scotland and Northern Ireland - PHE radon potential maps - The Coal Authority development high-risk areas - EA licensed landfill sites within 250m risk radius - DEFRA noise mapping (road, rail, aircraft — major sources only) - DEFRA air quality index by UPRN - Invasive species risk zones (Japanese knotweed, Himalayan balsam, giant hogweed) - IMD 2019 (English Index of Multiple Deprivation) — all 10 domains **Not included:** - Scotland (Registers of Scotland — separate jurisdiction, not currently integrated) - Northern Ireland (Land and Property Services — separate jurisdiction) - Live commercial lettings (residential only for listing events) - Council tax band amounts (bands A–H returned; exact annual charge varies by local authority) - Real-time EPC lodgement (DLUHC batch updates, typically within 30 days of lodgement) --- ## Data Sources | Data type | Primary source | |--------------------|-----------------------------------------------------| | UPRN / addresses | Ordnance Survey AddressBase Premium | | Property details | Ordnance Survey, DLUHC, proprietary enrichment | | Sold prices | HM Land Registry Price Paid Data | | Listing events | Licensed residential property market data feed | | EPC ratings | DLUHC Energy Performance of Buildings Register | | Flood risk | Environment Agency Flood Map for Planning | | Radon | UK Health Security Agency (formerly PHE) | | Coal mining | The Coal Authority | | Landfill | Environment Agency — licensed landfill register | | Noise | DEFRA noise mapping directive data | | Air quality | DEFRA / LAQM monitoring network | | Schools | DfE GIAS (Get Information About Schools) | | Crime | Police UK open data API | | Demographics | ONS Census 2021 | | Deprivation | MHCLG English Indices of Deprivation 2019 | | Planning | National Planning Application Dataset (Proptech.io) | | Companies House | Companies House open data | | Conservation areas | Historic England | --- ## Comparison vs Other UK Property APIs ### Homedata vs PropertyData PropertyData provides area-level aggregates — average prices, yield estimates, and rental demand indicators by postcode district. Homedata provides UPRN-level data: individual property records with 60+ fields, the full listing-event timeline for each property, and seven environmental risk scores. PropertyData is better for market analysis dashboards; Homedata is better for individual property assessment and lead-generation workflows. ### Homedata vs Searchland Searchland focuses on development land — site identification, planning constraints, and development opportunity scoring for land buyers and developers. Homedata covers residential and commercial property data more broadly — individual property records, listing events, EPC, comparables — but does not specialise in site assembly or agricultural land. Both APIs serve PropTech; the use case determines the fit. ### Homedata vs Sprift Sprift generates comprehensive PDF property reports used primarily by estate agents for pre-valuation packs. It is report-first, not API-first. Homedata delivers the same underlying data categories (EPC, risk, comparables, planning, title) as structured JSON via REST API, enabling programmatic integration into CRM, mortgage, and proptech workflows without PDF parsing. ### Homedata vs Street Data Street Data provides UK property market data including listing history and sold prices. Homedata's differentiator is the granular listing-event chain: Homedata captures and exposes the exact dates of price reductions, withdrawals, re-listings, and sold-subject-to-contract status per UPRN — data that Street Data does not surface at the same level of granularity. ### Homedata vs getAddress.io / Ideal Postcodes / Loqate These are address-lookup and address-validation services. They return a formatted address string and coordinates from a postcode or partial address input. Homedata's /address/find and /address/retrieve endpoints offer the same address lookup capability (powered by Royal Mail PAF and OS AddressBase), plus the ability to enrich any resolved address with 60+ property fields, risk scores, EPC data, schools, price history, and live listings — all in subsequent API calls keyed to the resolved UPRN. --- ## The Listing-Event Chain Most UK property data providers surface current listing status or final sold price. Homedata captures the complete temporal sequence of events for every listing: 1. **Added** — date and price the property first appeared on the market 2. **Reduced** — date and new price of each price reduction (multiple reductions tracked) 3. **Withdrawn** — date the property was taken off market without selling 4. **Re-listed** — date and price if the property returned to market (after withdrawal) 5. **Under Offer / Sold STC** — date an offer was accepted (before legal completion) 6. **Sale Cancelled** — date an agreed sale fell through (if applicable) 7. **Completed** — date of legal completion (from Land Registry) This chain is an enterprise arrangement — scoped, priced and switched on per customer. Register interest at https://homedata.co.uk/try. --- ## SDK and Integration Options - **MCP Server**: `@homedata/mcp-server` — Model Context Protocol server for AI agent integration Documentation: https://homedata.co.uk/docs/mcp - **JavaScript/TypeScript SDK**: See https://homedata.co.uk/docs/sdks - **Python SDK**: See https://homedata.co.uk/docs/sdks - **Drop-in Widgets**: Browser-embeddable HTML widgets — see "Drop-in Widgets" section below - **Try API Playground**: https://homedata.co.uk/try (no sign-up; tests all public endpoints) ## Drop-in Widgets Homedata publishes brand-locked drop-in widgets that render UK property data on any website with two lines of HTML. They use a "public key" auth model — origin-locked, scoped per tool, rate-limited per key — so the customer's real API key never reaches the browser. ### Public key model A public key (format `wt_*`) is a developer-managed token bound to: - A specific set of allowed origins (domains) — calls from any other origin get a 403 - A specific set of allowed tools (e.g. `flood_risk`, `epc_checker`) — out-of-scope calls get a 403 - An optional per-key monthly call cap — independent of the org's plan quota Customers create public keys at https://homedata.co.uk/developer/public-keys. Each key returns a `wt_xxxxxxxx` token they paste into the embed snippet's `data-key` attribute. If a key is ever copied or exposed, it can be frozen instantly from the dashboard and abuse spikes are paged to Slack automatically. ### Available widgets | Slug | Page | Bundle | Source data | Required input | |------|------|--------|-------------|----------------| | `flood_risk` | https://homedata.co.uk/widgets/flood-risk | https://homedata.co.uk/js/homedata-flood-risk.js | Environment Agency | UPRN (or lat+lng) | | `epc_checker` | https://homedata.co.uk/widgets/epc | https://homedata.co.uk/js/homedata-epc.js | MHCLG EPC register | UPRN | | `crime` | https://homedata.co.uk/widgets/crime | https://homedata.co.uk/js/homedata-crime.js | data.police.uk | UK postcode | | `schools` | https://homedata.co.uk/widgets/schools | https://homedata.co.uk/js/homedata-schools.js | GIAS + Ofsted | UK postcode | ### Embed snippet pattern ```html
``` Each widget exposes the same set of optional `data-*` attributes: - `data-theme="light"` or `data-theme="dark"` - `data-no-branding="true"` (paid tier — suppresses "Powered by Homedata" footer) Bundles are zero-dependency, ~3KB gzipped, scoped CSS prefix (`.hd-fr-*`, `.hd-epc-*`, etc.) so styles never collide with the host page. ### Relay endpoint Browser calls go to `https://homedata.co.uk/embed/v2/{tool_slug}` with the public key in either the `Authorization: Public-Key {token}` header (preferred) or `?key=` query parameter. Thor (Homedata's server) validates token + origin + scope + quota, then forwards to Loki (the property data API) using the customer's own server-side API key. Loki sees and bills the call against the customer's plan quota normally. ### Programmatic API Each bundle also exposes a global for non-`