US Address Generator

Guide

Understand the complete workflow, from browser controls to API requests

Complete a generation in three steps

01

Set the data range

Choose a state and city when needed, or leave filters empty for a random location

02

Refresh the sample record

Select random generation to replace the full set of fields shown on the page

03

Copy or download the result

Take one field, the complete record, or JSON into the next stage of your workflow

Using the browser interface

Control the location range

Filters determine the data range used for the next record:

  • Choose a state first to limit random results to that state
  • Select a city when you need a narrower geographic scope
  • Add has_number=1 to an API request to return only street fields with a house number

Take the page result

Choose the output that best fits the next task:

  • Use the copy control beside a field to take only that value
  • Copy the full record to receive the main page fields as one text block
  • Export JSON for a structured file that scripts and test environments can read

Review the location context

The map helps illustrate the approximate relationship between the city and address. It is not proof of navigation or postal accuracy.

Make testing more efficient

Fix the filters first

When debugging location-specific behavior, set the state and city before generating several records

Use it on smaller screens

Filtering, refreshing, and copying remain available on mobile layouts with controls adapted for narrow screens

Match output to the task

Use copy for quick pasting, and prefer JSON or the API for automated tests and batch workflows

Switch the interface language

Use the language menu to move between Chinese and English while keeping the same field structure

Retrieve data through the API

Use the generation endpoint when scripts or services need sample records. Every request requires a valid API Key and can filter by state, city, house number, or states without a statewide general sales tax.

Terminal 
# Filter by state and city
curl --get "/api/generate.php" -H "Authorization: Bearer YOUR_API_KEY" --data-urlencode "state=CA" --data-urlencode "city=Los Angeles"
Terminal 
# Require a house number
curl --get "/api/generate.php" -H "Authorization: Bearer YOUR_API_KEY" --data-urlencode "has_number=1"
Terminal 
# Generate without location filters
curl "/api/generate.php" -H "Authorization: Bearer YOUR_API_KEY"
Terminal 
# Use JSON POST
curl "/api/generate.php" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" --data '{"state":"CA","city":"Los Angeles","has_number":1}'
Terminal 
# List cities in a state (no key required)
curl --get "/api/get-cities.php" --data-urlencode "state=CA"
Terminal 
# Find states for a city (no key required)
curl --get "/api/get-state-by-city.php" --data-urlencode "city=Los Angeles"

Generation supports GET, JSON POST, and form POST. Location lookups support GET without authentication. All endpoints support OPTIONS preflight. Generation requires a Bearer key; the website uses a session-bound token.

state: optional two-letter state code, case-insensitive. city: optional full city name, case-insensitive; spaces and hyphens are equivalent. has_number: optional 0 or 1, default 0; 1 requires a street beginning with a house number. tax_free: optional 0 or 1; 1 randomly selects AK, DE, MT, NH, or OR and cannot be combined with state or city. Other filters must all match; no matching address returns 404. get-state-by-city requires city; unknown cities return empty states and null primary_state.

Errors contain success: false, error, and code. 400: invalid parameters or JSON; 401: missing, invalid, or expired authentication; 404: no matching address; 405: unsupported method; 413: body exceeds 4096 bytes; 415: unsupported POST content type; 500: service error. Do not repeat a parameter in both the URL and POST body.

Before sending a request: Replace YOUR_API_KEY with an active key in the Authorization: Bearer header, never in the URL. Examples follow this page’s protocol, hostname, and port. Contact the administrator to renew expired keys.

Selected fields are shown below. The actual data also includes employment, account, and credit-card fields. cardNumber and cvv are strings; expiry uses MM/YY. These are fictional samples.

Response structure 

{
  "success": true,
  "data": {
    "fullName": "John Doe",
    "street": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zipCode": "90001"
  }
}