About

Software testing, form validation, and database seeding require plausible address data. Using real addresses creates privacy liability. Using obviously fake data ("123 Fake Street") fails format validation and misses edge cases like long city names or multi-word street types. This generator assembles addresses from real US geographic components - actual city/state/ZIP combinations, common street name patterns, and standard USPS formatting - producing output that passes regex validation and visual inspection without corresponding to occupied dwellings. Each address follows the USPS Publication 28 structure: primary number, street name, optional secondary unit, city, two-letter state abbreviation, and 5-digit ZIP code.

The generator draws from a curated dataset of 50 US states plus DC, real city-to-ZIP mappings, and over 200 common American street names. Street numbers are bounded to the range 1 - 9999. Secondary designators (Apt, Suite, Unit) appear with configurable probability. Note: generated addresses are combinatorially plausible but not verified against USPS delivery databases. Do not use these for shipping or legal documents.

Formulas

Each address is assembled from independent random selections across structured component pools. The generation follows USPS Publication 28 address formatting standards.

Address = N + Dir + Street + Type + Unit + City + State + ZIP

Where N is a street number drawn uniformly from [1, 9999]. Dir is an optional cardinal prefix (N, S, E, W) applied with probability p = 0.25. Street is selected uniformly from a pool of ≥ 200 real American street names. Type is the street suffix (St, Ave, Blvd, Dr, Ln, etc.) selected uniformly. Unit is an optional secondary designator (Apt, Suite, Unit) with probability p_unit controlled by user setting. City, State, and ZIP form a validated tuple selected from a curated geographic dataset ensuring the ZIP code falls within the correct state range.

The total combinatorial space is approximately:

C = 9999 × 5 × 200 × 20 × L ≈ 2 × 10⁸ unique addresses

Where L is the number of city/state/ZIP tuples in the dataset. Randomness is sourced from crypto.getRandomValues for uniform distribution quality superior to Math.random.

Reference Data

State	Abbreviation	Capital	Sample ZIP Range	Area Code(s)
Alabama	AL	Montgomery	35004 - 36925	205, 251, 256
Alaska	AK	Juneau	99501 - 99950	907
Arizona	AZ	Phoenix	85001 - 86556	480, 520, 602
California	CA	Sacramento	90001 - 96162	213, 310, 415
Colorado	CO	Denver	80001 - 81658	303, 719, 720
Florida	FL	Tallahassee	32003 - 34997	305, 407, 813
Georgia	GA	Atlanta	30002 - 39901	404, 478, 706
Illinois	IL	Springfield	60001 - 62999	217, 312, 630
Indiana	IN	Indianapolis	46001 - 47997	317, 574, 812
Massachusetts	MA	Boston	01001 - 02791	413, 508, 617
Michigan	MI	Lansing	48001 - 49971	231, 248, 313
Minnesota	MN	Saint Paul	55001 - 56763	218, 320, 612
New Jersey	NJ	Trenton	07001 - 08989	201, 609, 732
New York	NY	Albany	10001 - 14925	212, 315, 516
North Carolina	NC	Raleigh	27006 - 28909	336, 704, 919
Ohio	OH	Columbus	43001 - 45999	216, 330, 614
Oregon	OR	Salem	97001 - 97920	503, 541, 971
Pennsylvania	PA	Harrisburg	15001 - 19640	215, 412, 717
Texas	TX	Austin	73301 - 79999	210, 214, 512
Virginia	VA	Richmond	20101 - 24658	276, 540, 703
Washington	WA	Olympia	98001 - 99403	206, 253, 509
Wisconsin	WI	Madison	53001 - 54990	262, 414, 608

Frequently Asked Questions

No. The addresses are combinatorially assembled from real geographic components (actual city names, valid state abbreviations, ZIP codes within correct state ranges) but the specific street number + street name + city combination is statistically unlikely to match an occupied dwelling. The combinatorial space exceeds 2 × 10⁸ permutations. Do not use these for shipping, legal filings, or identity verification.

US ZIP codes in the Northeast (Connecticut, Massachusetts, Maine, New Hampshire, New Jersey, Puerto Rico, Rhode Island, Vermont) begin with 0. For example, Boston ZIP codes start with 021xx. The generator preserves leading zeros by treating ZIP codes as strings, not numbers. If you import these into a spreadsheet, format the ZIP column as text to prevent Excel from stripping the leading zero.

Yes. This is the primary intended use case. Generated addresses follow USPS Publication 28 formatting: numeric street number, optional directional prefix, street name, street type suffix, city, 2-letter state abbreviation, and 5-digit ZIP. They will pass standard regex validation patterns for US addresses. For API integration testing, the addresses are realistic enough to test geocoding error handling (the geocoder should return low-confidence or no-match results).

When you select a specific state, the generator only draws from city/ZIP tuples mapped to that state. The ZIP code ranges are real: Texas ZIPs fall within 73301-79999, California within 90001-96162, etc. The city-to-state mapping is verified. Selecting "Any State" draws uniformly from all available state datasets.

The "Include Unit" toggle controls secondary address line generation. When enabled, approximately 40% of generated addresses include a secondary designator chosen from: Apt (apartment), Suite (Ste), Unit, or # followed by a number between 1 and 999 or a letter A - H. This ratio reflects approximate US Census data showing roughly 1 in 3 occupied housing units are in multi-unit structures.

The generator uses crypto.getRandomValues() via the Web Crypto API, which provides cryptographically strong random values. This exceeds the quality of Math.random() (which uses a PRNG and is not suitable for security-sensitive applications). For address generation, this level of randomness is more than sufficient and ensures uniform distribution across the combinatorial space.