Random US Address Generator

Seeding a United States sandbox CRM

Ops wants 50 contacts in a sandbox CRM without loading a production extract. They run the generator at count 50 for United States, download CSV, and map street, city, state, ZIP code, and phone. Each ZIP code like 10001 keeps United States recognizable. No names, no cards, no national IDs. The import is location-only, which is what legal asked for.

US address format rules

A US address has a fixed order. Most forms split it into these fields:

1. Street line. House number, then street name and suffix: 4821 Oak Ridge Rd. Directionals like N, S, NE show up before or after the street name.
2. Secondary line (optional). Apt 4B, Suite 210, Unit 12, or # 7. Many forms call this Address Line 2. On an envelope, USPS prefers it at the end of the street line: 4821 Oak Ridge Rd Apt 4B.
3. City, state, ZIP. City name, the 2-letter state code, then the ZIP: Los Angeles, CA 90058.

A few rules worth knowing:

• ZIP code is 5 digits. ZIP+4 adds a hyphen and 4 more digits: 90058-2021. The extra 4 narrow delivery down to a block or building, and they're optional on most forms.
• State codes are always 2 capital letters with no periods: CA, NY, TX. DC is used for Washington, DC. Territories have codes too, such as PR for Puerto Rico and GU for Guam. Military mail uses AA, AE and AP.
• ZIPs can start with 0. New England and parts of the Northeast use codes like 02108 (Boston) and 06103 (Hartford). That zero is part of the code.

US phone number format

US numbers are +1, a 3-digit area code, then a 7-digit number: +1 (213) 555-0132, or +12135550132 in E.164 storage format. Area codes and the 3-digit exchange never start with 0 or 1. If you want a number that is guaranteed not to ring anyone, 555-0100 through 555-0199 is reserved for fictional use, which is why you see it in films. Phones on our cards use an area code from the right state but are otherwise made up.

US address bugs QA testers keep hitting

• The missing zero. A ZIP stored as an integer turns 02108 into 2108. Opening a CSV in a spreadsheet does the same thing. Store ZIPs as text.
• ZIP+4 rejected or mangled. A 5-character limit cuts off the +4. Some code strips the hyphen and saves 900582021, which then fails the 5-digit check on the next edit.
• State dropdown gaps. No DC, no territories, no AA/AE/AP. Real users in Puerto Rico and on military bases hit this.
• Line 2 treated as required, or dropped on save. Apartment numbers then vanish from shipping labels.
• Double country code. A phone field that adds +1 to a number that already has it and saves +1 +1 213 555 0132.
• City and ZIP mismatch checks that reject a valid city name because the lookup expects a different one. Brooklyn versus New York is the famous case.

Use cases

• Checkout and billing forms in sandbox mode, where you need a random US billing address that's well-formed.
• Figma screens for US users: long city names and a filled Address Line 2 show you where a shipping card wraps.
• Staging CRMs and admin tables filled with a spread of states, so filters and sorting have something to chew on.
• Test suites that loop over states to check tax or shipping zone logic.

FAQ