Getting Started

The HomePortfolio API gives you 300+ data points on any property in England from a single API call. This guide will get you from zero to your first response in under 5 minutes.

1. Get your API key

Email [email protected] with your company name and use case. You'll receive your key within 24 hours.

2. Make your first request

curl "https://api.homeportfolio.com/v1/property/100050675856" \
  -H "X-API-Key: your_api_key"

3. That's it

You'll get a JSON response with 19 data sections covering everything from valuations and EPC ratings to crime stats and planning history.

Authentication

All API requests (except public endpoints) require an API key. Pass it via:

Header (recommended)

X-API-Key: hp_live_your_key_here

Query parameter

https://api.homeportfolio.com/v1/property/123?api_key=hp_live_your_key_here

Public endpoints that don't require authentication:

Rate Limits

Rate limits are applied per API key. Every response includes headers showing your current usage:

X-RateLimit-Limit-Daily: 10000
X-RateLimit-Remaining-Daily: 9847
X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 98

When you exceed a rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Property Lookup

GET /v1/property/{uprn}

Returns the full property intelligence response — all 19 sections, 300+ fields.

Parameters

Response time

Cached: ~130ms · Uncached: ~1.3s · The first request for a UPRN runs 14+ parallel queries, then caches for 6 hours.

Section Endpoints

GET /v1/property/{uprn}/{section}

Returns just one data section. Faster and smaller than the full response. Available sections:

Search

GET /v1/search

Find properties by postcode, text address, or coordinates.

By postcode

GET /v1/search?postcode=SW1A+1AA

By text

GET /v1/search?q=10+Downing+Street+London

By location

GET /v1/search?lat=51.5034&lon=-0.1276&radius=200

Autocomplete

GET /v1/autocomplete?q=10+down

Returns address suggestions as the user types. Optimised for speed (~150ms).

Area Intelligence

GET /v1/area/{postcode}

Area-level data: walkability, census demographics, crime stats, planning activity, market stats, flood risk — all for a postcode area. ~170ms.

Compare

GET /v1/compare?uprns=100050675856,100050675857

Side-by-side comparison of up to 5 properties. Returns full data for each.

Bulk Lookup

POST /v1/bulk
Content-Type: application/json

{"uprns": ["100050675856", "100050675857", ...]}

Batch lookup up to 100 UPRNs in one request. Requires Pro plan or above.

Data Sections Reference

address (9 fields)

full, postcode, outcode, country, town, area, county, region, street

property (14 fields)

type, bedrooms, bathrooms, living_rooms, tenure, built_form, construction_age, floor_area_sqm, floor_height_m, habitable_rooms, heated_rooms, extension_count, open_fireplaces, transaction_type

valuation (10 fields)

sale_estimate, sale_range (low/high), sale_confidence, rent_estimate_monthly, rent_range (low/high), last_sale_price, last_sale_date, median_price_12mo, transactions_12mo, gross_rental_yield_pct

epc (22 fields)

current_rating, potential_rating, current_efficiency, potential_efficiency, co2_current_tonnes, co2_potential_tonnes, energy_consumption_current, energy_consumption_potential, environment_impact_current, environment_impact_potential, annual_costs (heating/hot_water/lighting), potential_costs, walls, roof, floor, windows, heating, hot_water, lighting, renewables, ventilation, inspection_date

risk (12 fields)

flood_risk, subsidence_risk, radon_risk_class, mining_risk, landslide_risk, collapsible_ground, compressible_ground, running_sand, soluble_rocks, air_quality_no2, air_quality_pm25, air_quality_pm10

demographics (21 fields)

lsoa_code, lsoa_name, local_authority, population, total_households, median_annual_income, mean_annual_income, area_sqkm, population_density, age_distribution, sex, ethnicity, religion, marital_status, health, qualifications, employment, occupation, housing, tenure_distribution, deprivation

Error Codes

All errors return JSON:

{"detail": "API key required. Pass via X-API-Key header or ?api_key= param."}

Data Sources

Our data is aggregated from 15+ authoritative UK sources, refreshed on different cadences:

Code Examples

cURL

# Full property intelligence — 379 fields, 19 sections
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.homeportfolio.com/v1/property/100030048320"

# Single section for speed (~142ms)
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.homeportfolio.com/v1/property/100030048320/valuation"

# Search by address or postcode
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.homeportfolio.com/v1/search?q=10+Downing+Street"

# Real-time autocomplete
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.homeportfolio.com/v1/autocomplete?q=10+down"

# Area intelligence
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.homeportfolio.com/v1/area/SW1A+1AA"

# Compare properties side-by-side
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.homeportfolio.com/v1/compare?uprns=100030048320,200004166621"

# Bulk lookup — up to 100 UPRNs (Starter+)
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uprns": ["100030048320", "200004166621"]}' \
  "https://api.homeportfolio.com/v1/bulk"

Python

import requests

API_KEY = "hp_live_your_key_here"
BASE = "https://api.homeportfolio.com/v1"
headers = {"X-API-Key": API_KEY}

# Search for a property
results = requests.get(f"{BASE}/search",
    params={"q": "10 Downing Street"},
    headers=headers
).json()

# Get full property intelligence
uprn = results["results"][0]["uprn"]
data = requests.get(f"{BASE}/property/{uprn}", headers=headers).json()

print(f"Address: {data['full_address']}")
print(f"Value: £{float(data['valuation']['sale_estimate']):,.0f}")
print(f"EPC: {data['epc']['rating']}")
print(f"Flood risk: {data['risk']['flood_zone']}")

# Or fetch a single section for speed (~142ms)
epc = requests.get(f"{BASE}/property/{uprn}/epc", headers=headers).json()

JavaScript / Next.js

const API_KEY = "hp_live_your_key_here";
const BASE = "https://api.homeportfolio.com/v1";
const headers = { "X-API-Key": API_KEY };

// Search for a property
const { results } = await fetch(
  `${BASE}/search?q=10+Downing+Street`, { headers }
).then(r => r.json());

// Get full property intelligence
const uprn = results[0].uprn;
const data = await fetch(
  `${BASE}/property/${uprn}`, { headers }
).then(r => r.json());

console.log(`Value: £${data.valuation.sale_estimate}`);
console.log(`EPC: ${data.epc.rating}`);
console.log(`Flood: ${data.risk.flood_zone}`);

// Single section for speed
const epc = await fetch(
  `${BASE}/property/${uprn}/epc`, { headers }
).then(r => r.json());

Java (JDK 11+)

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

// Full property lookup
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.homeportfolio.com/v1/property/100030048320"))
    .header("X-API-Key", "hp_live_your_key_here")
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString()
);

// Parse with Jackson, Gson, or your preferred JSON library
System.out.println(response.body());