UK Address Generator REST API

Generate fictional UK addresses, postcodes, telephone numbers and test data over HTTP. No API key, no sign-up, CORS enabled.

Limits

• Authentication: None. No API key or registration is required.
• Rate limit: 100 requests per minute per IP address (HTTP 429 when exceeded).
• Maximum records: 1000 per request.
• Base path: /api/v1
• Specification: /api/v1/openapi.json

Endpoints

• GET /api/v1/health — Service health. Returns service status, version and the size of the reference registry.
• 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

Errors use the shape { "status": "error", "message": "…" } with status 400 for invalid parameters, 404 for an unknown endpoint, 413 for an oversized body, 429 for rate limiting and 500 for an unexpected failure.