Authentication
All authenticated endpoints use API key authentication via the Authorization header.
Passing your API key
Include your API key in the Authorization header with the Api-Key prefix:
Authorization: Api-Key your_api_key_here
curl https://api.homedata.co.uk/properties/100023336956/ \
-H "Authorization: Api-Key your_api_key_here"
⚠️ Important
- • Use
Api-Keyprefix, notBearer - • /ping and /health work without authentication
- • API keys are tied to your organisation, not individual users
Alternative: query parameter
For testing or environments where custom headers are difficult, you can pass your key as a query parameter:
https://api.homedata.co.uk/properties/100023336956/?api_key=your_api_key_here
⚠️ Query parameter auth is not recommended for production: keys may appear in server logs and browser history. Use the header method in production code.
Open endpoints (no auth required)
Some endpoints are publicly accessible without an API key, including:
| Endpoint | Description |
|---|---|
| GET /ping | Liveness probe — returns status "ok" |
| GET /health | Detailed health with DB + ES status |
Response headers
Which headers an authenticated response carries depends on how your key is billed. Wallet keys receive the X-Tokens-* pair and no rate-limit headers at all; quota keys receive the X-RateLimit-* family instead. You will not see both. Not every member of the family is sent to every quota key — the table says which.
| Header | Example | Description |
|---|---|---|
| X-Tokens-Charged | 1 | Wallet keys only — tokens spent by this request |
| X-Tokens-Balance | 1847 | Wallet keys only — tokens left on your balance |
| X-RateLimit-Limit | 10000 | Quota keys only — requests allowed this billing period. Unlimited keys send the literal unlimited. |
| X-RateLimit-Remaining | 9427 | Quota keys only — requests left in the period. Unlimited keys send the literal unlimited. |
| X-RateLimit-Reset | 1760140800 | Limited keys only — Unix timestamp when the period resets. Unlimited and test keys do not receive it. |
| Retry-After | 30 | Seconds to wait after a 429 (rate limits are about pace, not tokens) |
Security best practices
Store keys in environment variables
Never hardcode API keys. Use .env files or your platform's secret management.
Use server-side calls only
Don't expose your API key in browser JavaScript, mobile apps, or public repositories.
Revoke compromised keys immediately
Use the Developer Dashboard to revoke a key if it's exposed. You can generate a new one instantly.
Add .env to your .gitignore
Prevent accidental commits of your API key to version control.
Integrate into your own product
Pay as you goEvery authenticated Homedata API call is validated in under 5ms. Your usage is reported in response headers, so your application can track it without polling the dashboard.
Structured as JSON · queryable by UPRN or postcode · ready to embed in any application
Exact measurements
Real values — distances, concentrations, counts — not rounded ratings
29 million UK properties covered
Every address queryable by UPRN or postcode
REST API
JSON responses, OpenAPI docs, sandbox — first call in under 5 minutes
Pay as you go: 100 tokens = £1 across every endpoint, no subscription needed. Bonus tokens with an optional monthly subscription, and your first top-up matched 100%. See pricing →
Sources
Further reading