Getting Started

From zero to your first API call in under 5 minutes. No credit card required.

Prerequisites

• An HTTP client (curl, Postman, or your language's HTTP library)
• A Homedata account (free signup)

Create your free account

• Your name and email
• Organisation name (company or project name)
• Industry (helps us tailor your experience)

Your API key is generated instantly after signup. The free tier gives you 100 requests/month — enough to build and test your integration.

Get your API key

After signing in, go to Developer → API Keys in your dashboard. Click "Reveal" to see your full API key.

Your API Key Format

prefix.your_secret_key_here

⚠️ Keep your API key secret. Don't commit it to version control or expose it in client-side code.

Make your first request

Let's start with something simple — search for an address. The address search endpoint is open (no API key required for the demo), so you can try it right now:

Live API — Try it now

No API key required

Search for any UK address:

cURL Copy & paste into your terminal

curl "https://homedata.co.uk/api/v1/address/find?q=10%20Downing%20Street" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Python pip install requests

import requests

API_KEY = "YOUR_API_KEY"
headers = {"Authorization": f"Api-Key {API_KEY}"}

response = requests.get(
    "https://homedata.co.uk/api/v1/address/find",
    params={"q": "10 Downing Street"},
    headers=headers
)
data = response.json()
for addr in data["data"]:
    print(f"{addr['address']}, {addr['postcode']} (UPRN: {addr['uprn']})")

JavaScript (Node.js / Browser)

const API_KEY = "YOUR_API_KEY";

const response = await fetch(
  "https://homedata.co.uk/api/v1/address/find?q=10%20Downing%20Street",
  { headers: { "Authorization": `Api-Key ${API_KEY}` } }
);
const data = await response.json();
data.data.forEach(a =>
  console.log(`${a.address}, ${a.postcode} (UPRN: ${a.uprn})`)
);

PHP

$apiKey = "YOUR_API_KEY";
$url = "https://homedata.co.uk/api/v1/address/find?" . http_build_query(['q' => '10 Downing Street']);

$context = stream_context_create(['http' => [
    'header' => "Authorization: Api-Key $apiKey"
]]);
$response = file_get_contents($url, false, $context);
$data = json_decode($response, true);
foreach ($data['data'] as $addr) {
    echo $addr['address'] . ", UPRN: " . $addr['uprn'] . "\n";
}

Expected response:

200 OK ~160ms

{
  "data": [
    {
      "uprn": 100023336956,
      "address": "10 Downing Street, London, SW1A 2AA",
      "address_line_1": "10 Downing Street",
      "address_line_2": null,
      "town": "London",
      "postcode": "SW1A 2AA"
    },
    // ...more matches across the UK
  ],
  "meta": { "query_type": "postcode_exact", "took_ms": 12, "total": 7 }
}

Each result includes a UPRN — the unique identifier you'll pass to authenticated endpoints. Copy one and use it in Step 4 below.

Use your API key for authenticated endpoints

Most endpoints require authentication. Pass your API key in the Authorization header:

cURL

# Full property data — 60+ fields including type, bedrooms, tenure
curl https://homedata.co.uk/api/v1/properties/100023336956 \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Nearby schools with Ofsted ratings
curl "https://homedata.co.uk/api/v1/schools/nearby?postcode=SW1A+2AA&radius=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Broadband speeds by postcode
curl "https://homedata.co.uk/api/v1/broadband?postcode=SW1A2AA" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Street-level crime nearby
curl "https://homedata.co.uk/api/v1/crime/nearby?postcode=SW1A+2AA" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Python

import requests

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

# Get full property data
prop = requests.get(f"{BASE}/api/v1/properties/100023336956", headers=headers).json()
print(f"Type: {prop['property_type']}, Beds: {prop['bedrooms']}")

# Nearby schools with Ofsted ratings
schools = requests.get(
    f"{BASE}/api/v1/schools/nearby",
    params={"postcode": "SW1A 2AA", "radius": 1},
    headers=headers
).json()
for school in schools["schools"][:5]:
    print(f"{school['name']} — {school['ofsted']['rating']} ({school['distance_miles']}mi)")

# Broadband speeds by postcode
bb = requests.get(
    f"{BASE}/api/v1/broadband",
    params={"postcode": "SW1A2AA"},
    headers=headers
).json()

JavaScript

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

// Get full property data
const prop = await fetch(`${BASE}/api/v1/properties/100023336956`, { headers })
  .then(r => r.json());

// Nearby schools with Ofsted ratings
const schools = await fetch(
  `${BASE}/api/v1/schools/nearby?postcode=SW1A+2AA&radius=1`, { headers }
).then(r => r.json());
schools.schools.slice(0, 5).forEach(s =>
  console.log(`${s.name} — ${s.ofsted.rating} (${s.distance_miles}mi)`)
);

// Broadband speeds by postcode
const bb = await fetch(
  `${BASE}/api/v1/broadband?postcode=SW1A2AA`, { headers }
).then(r => r.json());

Monitor your usage

Every response includes rate limit headers so you always know where you stand:

Response Headers

X-RateLimit-Limit: 100      ← Monthly allowance
X-RateLimit-Remaining: 97  ← Requests left this month

You can also check your usage in the Developer Dashboard — it shows a 30-day usage chart with daily breakdown.

What's next?

→

Explore all endpoints

22 endpoints — address, properties, schools, broadband, valuations, and more

→

Error handling

Standard error format and HTTP status codes

→

Upgrade your plan

Need more than 100 requests? Plans start at £49/mo

→

Interactive API Reference

Try endpoints live with the OpenAPI 3.1 explorer