How to Generate Random Address Data with the API
Generating random address data with the Fake Addresses API starts at a single endpoint, GET /api/v1/addresses, which accepts a count up to 10,000, an optional state, city or zip filter, a format (JSON, CSV, NDJSON, SQL across seven dialects, or XLSX), and a seed for reproducibility. No request needs an account, an email address, or an API key at any point — every call is anonymous and CORS-enabled, so a browser-based tool can call it directly.
A caller who pins a seed value gets the exact same records back on every future request against the same dataset version. That is the property every response carries explicitly, so a fixture never silently drifts underneath a test suite. /api/v1/coverage reports which states, counties and ZIP codes the current dataset actually covers, and a filter outside that coverage returns an honest 422 rather than an invented address or a silent empty response.
The full request and response contract is published as a single OpenAPI 3.1 specification at /openapi.yaml, covering every parameter, every export format, and the 60-requests-per-minute anonymous rate limit. The same specification generates a Postman collection, so a request built in one client behaves identically in the other, and it is what lets a developer generate a typed client in a language Fake Addresses does not ship a package for directly.
Client Libraries and Bulk Export
Beyond the raw HTTP endpoint, Fake Addresses publishes an npm package and a PyPI package for Node.js and Python callers, a command-line interface for a terminal or a CI step, and an MCP server so a coding agent can request test data as a direct tool call instead of scraping a page. Every one of these surfaces returns the same dataset version, and a pinned seed returns byte-identical rows across all of them. None of them requires the account or API key the raw HTTP endpoint already does not require.
For a one-off large export, the bulk export page returns up to 10,000 rows in a single response with no queued job and no pagination — a real bar to clear against a category where the market leader runs export jobs as a multi-minute queue. Output across every surface is licensed free to use, so a fixture generated through the API, the CLI, or the bulk export page is safe to commit to a public repository without an attribution obligation.
US address format rules the API output follows are documented on the USPS Publication 28 reference page. The coherence guarantee behind every generated record is documented separately on the methodology page — both are the primary sources this API documentation defers to rather than restating, so a change to either stays in exactly one place.
Frequently asked questions
Does the Fake Addresses API require an account or API key?
No. Every endpoint is keyless and anonymous, rate-limited to 60 requests per minute per caller, with no signup step and no API key to generate or store — the same anonymous access applies to every export format the API supports.
How do I get the same API response twice?
Add a seed parameter to the request. The same seed against the same dataset version returns byte-identical output forever, which is what makes the Fake Addresses API usable as a committed CI fixture rather than a one-off call.
What happens if I request a location the API does not cover?
The Fake Addresses API returns an honest 422 response naming the coverage gap, never an invented address and never a silent empty 200 — check /api/v1/coverage for exactly which states, counties and ZIP codes are covered today.
Is Fake Addresses API output licensed for commercial use?
Yes. Every record the API returns is licensed free to use, with no attribution requirement, so it can be used in a commercial test suite or a published dataset without a licensing obligation.