This is the complete 2026 developer guide for the random US address generator from USA Data Tools. It covers every way you can use the tool — the in-browser generator, bulk export, the REST API, the JSON data schema, state filters, state-specific ZIP prefixes, integration into JavaScript and Python projects, and the QA workflow we recommend for exercising edge cases. By the end you should have everything you need to ship a US-aware feature with confidence.
What the tool actually generates
A single record from the address generator is a structured object containing the fields a developer most often needs:
- name — a realistic first-name + last-name combo
- street — a number + street name + suffix, e.g.
4218 Lakeview Dr - city — a major city in the selected state
- state — 2-letter USPS abbreviation (e.g.
CA) - stateFull — full state name (e.g.
California) - zip — a 5-digit ZIP drawn from the correct prefix range for that state
- phone — a US phone with an area code valid for that state
- formatted — a multi-line string ready to paste
The point worth internalizing: the ZIP, the area code of the phone, and the city are all geographically consistent with the state. A California record produces a 90xxx–96xxx ZIP and a 213/408/415/510/… area-code phone. That is the property you rely on for tests where your form validates ZIP-against-state and your cart applies state-specific sales tax.
The three ways to generate
1. Browser UI
Open the address generator page, pick a state from the dropdown (or leave it on "Any state" for a random nationwide pick), and click Generate. The result card shows a multi-line formatted address; Copy or Download produce the same content as JSON.
2. Bulk export (one click)
The generator supports generating up to 1,000 addresses at once. This pairs nicely with seeding a development database — produce the JSON, write it to a fixtures directory, import to your DB.
// load 1000 addresses into a Node seed script
import users from "./fixtures/seed.json" assert { type: "json" };
await Promise.all(users.map(async u => {
await db.user.insert({
name: u.name,
street: u.street,
city: u.city,
state: u.state,
zip: u.zip,
phone: u.phone,
});
}));3. REST API
For scripts, CI, and integration testing the REST API is the right interface. See the API docs for the full surface; the headline endpoint is:
curl "https://vic999.com/us-address/api/v1/address?state=CA&count=10" \
-H "Authorization: Bearer YOUR_API_KEY"Response shape:
{
"data": [
{
"name": "Jordan Diaz",
"street": "7511 Eucalyptus Ave",
"city": "Sacramento",
"state": "CA",
"stateFull": "California",
"zip": "95820",
"phone": "+1 916 555 0149",
"formatted": "Jordan Diaz\n7511 Eucalyptus Ave\nSacramento, CA 95820\n+1 916 555 0149"
},
...
],
"count": 10,
"state": "CA"
}Tiers, rate limits, and keys
The Free tier allows 1,000 API requests/month with no signup, which is enough for most personal and evaluation workflows. The Pro tier at $9.99/mo lifts limits to 100,000 requests/month and adds bulk CSV export. Business is for teams that need 1MM requests/mo with named API keys and rate-limit controls.
Authentication is via a bearer token in the Authorization header. You can issue, rotate, and revoke keys from the dashboard.
State filtering in the API
Pass the state query parameter (2-letter abbreviation) to scope results:
curl "https://vic999.com/us-address/api/v1/address?state=TX&count=5" \
-H "Authorization: Bearer YOUR_API_KEY"Omitting state returns nationwide random addresses. For territory-specific work the tool supports all 51 states and territories — see state-specific generator pages for examples per region.
ZIP prefix consistency
The single most useful property of the tool is that ZIP prefixes are state-aware. The full US ZIP chart lives in our ZIP format explainer; here are the broad strokes:
| State | Prefixes used |
|---|---|
| California | 900–961 |
| Texas | 75–79 |
| New York | 10–14 |
| Florida | 32–34 |
| Puerto Rico | 006–009 |
| Delaware | 197–199 (tax-free) |
If your form validates state against zip, the generated address passes — which is exactly the test you want before shipping ZIP-state validation to production.
The Tax-Free States generator
For e-commerce testing, the Tax-Free States generator is a narrowing of the address generator that only emits addresses in Delaware, Montana, New Hampshire, and Oregon. Use it to test the zero-sales-tax branch of your checkout:
curl "https://vic999.com/us-address/api/v1/address?taxFree=1&count=5" \
-H "Authorization: Bearer YOUR_API_KEY"Pair this with a test card from your payment sandbox and you can exercise the entire tax-free checkout path with two stable fixture inputs.
Generating EIN and SSN alongside
For KYB / KYC scenarios that need a tax identifier beside the address, combine the address API with the EIN generator and the SSN Test Format. Two extra fields in your schema accommodates both business and individual KYC without component sprawl. Read our EIN vs SSN comparison for the field-by-field breakdown.
const entity = {
...addressRecord,
ein: einRecord.value, // format-only fake EIN
// OR
ssn: ssnRecord.value, // reserved-area SSN, never valid
};Idempotency and seed
For tests that should produce the same dataset on every run, pass the seed query parameter. The same seed plus the same count yields the same records in the same order, every time. This turns "the test that fails on CI but passes locally" into "the deterministic test that fails identically everywhere."
curl "https://vic999.com/us-address/api/v1/address?count=20&seed=42" \
-H "Authorization: Bearer YOUR_API_KEY"Integration in JavaScript
A thin fetch wrapper that handles auth, paging, and errors:
const USA_API = "https://vic999.com/us-address/api/v1";
async function usAddresses({ count = 10, state, seed, taxFree } = {}) {
const url = new URL(`${USA_API}/address`);
url.searchParams.set("count", String(count));
if (state) url.searchParams.set("state", state);
if (seed != null) url.searchParams.set("seed", String(seed));
if (taxFree) url.searchParams.set("taxFree", "1");
const r = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.USA_KEY}` },
});
if (!r.ok) throw new Error(`USA API ${r.status}: ${await r.text()}`);
return (await r.json()).data;
}
// usage
const ca = await usAddresses({ state: "CA", count: 50 });
console.log(ca[0]);Integration in Python
import os, requests
USA_API = "https://vic999.com/us-address/api/v1"
TOKEN = os.environ["USA_KEY"]
def us_addresses(count=10, state=None, seed=None, tax_free=False):
params = {"count": count}
if state: params["state"] = state
if seed is not None: params["seed"] = seed
if tax_free: params["taxFree"] = "1"
r = requests.get(
f"{USA_API}/address",
params=params,
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=15,
)
r.raise_for_status()
return r.json()["data"]
records = us_addresses(state="NY", count=20, seed=99)Building reproducible fixtures
A real workflow we use on our backend: snapshots of generated addresses are saved into version control as JSON so any test that depends on a specific address can pin to a specific commit. The generator's determinism via seed means we never need to scrub the fixtures manually — when the underlying dataset updates we re-seed and re-snapshot.
{
"v": 1,
"generated_at": "2026-07-10T09:00:00Z",
"seed": 42,
"records": [
{ "name": "...", "city": "...", "state": "..." }
]
}Email and password enrichment
The address API does not return emails or passwords (those are usually random generators that you apply locally). Combine the API output with Faker to produce a complete user object:
import { faker } from "@faker-js/faker";
const decorate = (addr) => ({
...addr,
email: faker.internet.email({
firstName: addr.name.split(" ")[0].toLowerCase(),
lastName: addr.name.split(" ")[1].toLowerCase(),
}),
password: faker.internet.password({ length: 14, prefix: "Abcd1234!" }),
});See our signup-form testing tutorial for a full Playwright harness around these enriched fixtures.
Mobile and desktop testing
The generated addresses exercise every US-format edge case keyboard auto-fill can throw at you: ZIPs with hyphens, names with apostrophes, "Street" vs "St" suffixes. Run them through iOS and Android webviews (or a service like BrowserStack) — any crash you find here is a real one.
Caching strategy
Three caching tiers, from cheapest to priciest:
- In-process cache: a 5-minute TTL on the address records during a CI run.
- Redis layer: cache by query string (state + seed + count), TTL 24 hours.
- Materialized fixtures: snapshot the JSON into git for pinning across test runs.
The free tier rate limit (1k/month) is easily exhausted by a test suite that hits the API directly. Redis or pre-generated fixtures remove that cap.
QA matrix for shipping US features
Use these generator outputs to manually verify your feature handles every category:
- Lower-48 state records (e.g. Texas, New York)
- A territory record (PR, GU, AS, MP, VI, AA/AE/AP)
- A tax-free state record (DE, MT, NH, OR)
- A 9-digit ZIP (some users paste ZIP+4)
- Long street addresses (some auto-suggest yields 50+ char outputs)
- An international-format phone (
+1 415 ...)
Once your QA matrix passes with all of these, the long tail of US-format bugs is essentially closed.
Reading the API docs
The API docs include complete endpoint reference, request/response schemas, error codes, and pagination semantics. If you only read one page, read the address endpoint reference and the authentication section. Combine with the ZIP Lookup endpoint when you need to validate ZIP-to-state matching in your front-end before the form submits.
Pro vs Free: which one to choose
Free: 1k API requests/month, 100 generations/day, basic support, all 51 states. Ideal for evaluation, personal projects, and CI runs that cache aggressive enough to stay under the cap.
Pro ($9.99/mo): unlimited generations, 100k API requests/month, CSV/JSON export, no ads. Pairs with a small team running nightly integration tests against the API.
Business ($49/mo): 1MM requests/month, priority support, named API keys with rate-limit control. For QA teams that hit the API on every pull request.
Start free; upgrade when you actually need the headroom.
Common pitfalls and known issues
- Confusing ZIP and ZIP+4: the API returns 5-digit ZIPs. Concatenate
-0000..-9999if you specifically need a ZIP+4 stress test instead. - Email uniqueness: the address API returns names but no emails — generate these locally to be sure they are unique.
- Rate-limit hits: when running a test that calls the API per-iteration you will exceed the free tier quickly; cache.
- Real-world geography: the city list per state is broad and realistic but not exhaustive — some small ZIPs will not match a populated-place lookup against a different vendor's database.
Wrapping up
The random US address generator is purpose-built for testing and seeding US-centric features. Three interfaces — browser UI, bulk export, REST API — cover any workflow you have, and the state-aware ZIP/phone consistency turns out to be the single property that catches the largest class of real production bugs. Start with the free tier; if the API becomes load-bearing on your CI, the Pro plan is a flat $9.99/mo that covers 100k requests. Pair with the ZIP Lookup, EIN, SSN, and Tax-Free-State generators to round out a US-shaped test data toolkit.