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:/.homedata.co.uk/api/properties/100023336956/ \
-H "Authorization: Api-Key your_api_key_here"
⚠️ Important
- • Use
Api-Keyprefix — notBearer - • Some endpoints (like EPC Checker) 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:/.homedata.co.uk/api/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. These are ideal for testing your integration:
| Endpoint | Description |
|---|---|
| GET /api/epc-checker/{uprn}/ | EPC energy performance data |
| GET /api/address/find/?q={query} | Address search (typeahead autocomplete) |
| GET /api/address/postcode/{postcode}/ | All addresses at a postcode |
| GET /ping | Simple health check (returns "pong") |
| GET /health | Detailed health with DB + ES status |
Rate limits by plan
Each plan includes a monthly request allowance and per-second rate limit:
| Plan | Price | Monthly requests | Rate limit |
|---|---|---|---|
| Free | £0 | 100 | 2/sec |
| Starter | £19/mo | 2,000 | 5/sec |
| Growth | £49/mo | 10,000 | 10/sec |
| Pro | £149/mo | 50,000 | 20/sec |
| Scale | £349/mo | 200,000 | 40/sec |
| Enterprise | Custom | Unlimited | Custom |
Limits reset at the start of each billing period. View full pricing →
Rate limit response headers
Every authenticated response includes these headers:
| Header | Example | Description |
|---|---|---|
| X-RateLimit-Limit | 2000 | Monthly allowance |
| X-RateLimit-Remaining | 1847 | Requests remaining this period |
| X-RateLimit-Reset | 1711929600 | Unix timestamp when limit resets |
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.