Generate fictional UK addresses, postcodes, telephone numbers and test data over HTTP. No API key, no sign-up, CORS enabled.
The API is open. Calling it without a key gives you the free tier. Passing a key raises the per-request and monthly limits to whatever your plan allows, and meters usage against it.
Authorization: Bearer uk_live_… — Preferred.X-API-Key: uk_live_… — Equivalent, for clients that reserve the Authorization header.A key is never accepted as a query parameter. A URL ends up in access logs, Referer headers, browser history and every proxy in between, so a request carrying api_key=, key= or token= is refused with 400 rather than honoured.
| Plan | Requests | Per minute | Max results | Bulk export |
|---|---|---|---|---|
| Free | 100 per day by IP | 100 | up to 25 per request | JSON only |
| Starter ($19/mo) | 10,000 per month | 100 | up to 500 per request | CSV, TSV, SQL, XML, TXT |
| Pro ($49/mo) | 100,000 per month | 300 | up to 1,000 per request | CSV, TSV, SQL, XML, TXT |
| Business ($149/mo) | 1,000,000 per month | 300 | up to 10,000 per request | CSV, TSV, SQL, XML, TXT |
Until then, calling without a key keeps exactly the limits it has always had: 100 requests per minute, up to 1,000 results per request, and every export format. From that date the free tier becomes 100 requests per day by IP address, 25 results per request and JSON only. A request that would be refused after the change is served today with a Sunset header and an X-Api-Deprecation header naming the date, so an existing integration can be found before it breaks.
X-Api-Tier — The plan the request was served under, or "anonymous" when no API key was accepted. Check this to confirm a key was actually read: an anonymous call is served on the free tier’s terms, so the status and body look the same either way.X-RateLimit-Limit — Requests per minute allowed for this caller.X-RateLimit-Remaining — Requests left in the current minute.X-RateLimit-Quota — Requests included in the plan for this billing period. Keyed requests only.X-RateLimit-Quota-Remaining — Requests left in the current billing period.X-RateLimit-Quota-Reset — When the monthly allowance resets, as an ISO 8601 timestamp./api/v1/api/v1/openapi.jsonGET /api/v1/health — Service health. Returns service status, version, the size of the reference registry, and four booleans about how this deployment is configured: whether sign-in is enabled, whether sign-in links can be delivered, whether API keys are enabled, and whether accounts are stored durably.GET /api/v1/addresses/random — Generate random UK addresses. Generates fictional UK addresses using real postcode districts, post towns and counties. Returns JSON by default; CSV, TSV, SQL, XML and envelope text are available through the format parameter.POST /api/v1/addresses/generate — Generate addresses from a JSON body. The same generator as GET /addresses/random, with options supplied as a JSON body.GET /api/v1/addresses/validate — Validate a UK address. Checks a free-text UK address against Royal Mail formatting conventions and validates the postcode structure. This is a structural check, not a Postcode Address File lookup.GET /api/v1/postcodes/random — Generate random UK postcodes. Generates structurally valid postcodes built on real Royal Mail districts. The outward code is real; the inward code is generated.GET /api/v1/postcodes/lookup — Look up a postcode, district, area or post town. Resolves a full postcode, an outward code, a postcode area or a post town to its district, post town, county, country and dialling code. Returns found: false rather than inventing a result.GET /api/v1/postcodes/validate — Validate a postcode. Validates a postcode against the Royal Mail structural rules and returns its area, district, sector and unit, plus the format it matches.GET /api/v1/countries — List the four UK countries. Returns England, Scotland, Wales and Northern Ireland with their postcode areas and county terminology.GET /api/v1/locations — List post towns. Returns every post town in the registry with its county, country, postcode areas, districts and dialling code.GET /api/v1/phone/random — Generate UK telephone numbers. Generates UK numbers exclusively from the blocks Ofcom reserves for drama, so no generated number can reach a real subscriber.GET /api/v1/names/random — Generate UK personas. Fictional British personas with names, job titles, usernames and example.com email addresses.GET /api/v1/companies/random — Generate UK company names. Fictional UK company names with Companies House-format company numbers and HMRC-format VAT numbers.GET /api/v1/uuid — Generate UUIDs. RFC 4122 version 4 UUIDs from a cryptographically secure source.GET /api/v1/passwords — Generate passwords. Cryptographically secure random passwords for test accounts.GET /api/v1/lorem — Generate placeholder text. Lorem ipsum paragraphs for UI mock-ups.GET /api/v1/numbers — Generate random numbers. Random integers across a range, optionally with no repeats.POST /api/v1/contact — Send a message. Submits the contact form. Rate limited and protected by a honeypot field.Errors use the shape { "status": "error", "message": "…" }.
200 — Success.400 — Invalid parameters — a count outside the range your plan allows, a missing required parameter, or an API key passed in the query string. The message names the problem.401 — The API key is missing from the record, malformed, or has been revoked. Calling without a key is not an error; it is the free tier.402 — The endpoint or format is not included in your plan — for example a CSV or SQL export on the free tier.404 — Unknown endpoint.413 — Request body too large.429 — Either the per-minute rate limit or the monthly quota. A quota response names the tier, the limit, the usage and when it resets.500 — Unexpected server error.503 — A dependency is unavailable — for example API keys cannot be verified right now. Calling without a key still works.