Developer REST API Documentation

Integrate synthetic US address generation, postal validation, and developer testing utilities directly into your automated test suites, CI/CD pipelines, and seed scripts using our free REST API.

API Overview & Core Limits

• Authentication: No API key or registration required (100% free and open for testing).
• Rate Limit: 100 requests per minute per IP address. Exceeding this limit returns HTTP 429 Too Many Requests.
• Record Cap: Up to 1,000 records per request across all generation endpoints.
• Base URL: https://usaddressgenerator.org/api/v1
• Response Formats: JSON (default), CSV, SQL INSERT statements, XML, and Envelope TXT.
• CORS: Enabled globally (Access-Control-Allow-Origin: *) for direct frontend testing.

API Endpoints Reference

1. Address Generation

GET /api/v1/addresses/random

Generate random synthetic US addresses with complete postal, geographic, and formatted data.

Query Parameters:

• count (integer, optional, default: 10, min: 1, max: 1000): Number of synthetic addresses to generate.
• state (string, optional): 2-letter US state postal abbreviation (e.g. CA, TX, NY). Defaults to all states.
• city (string, optional): Target city name within the selected state.
• type (string, optional, enum: all, residential, commercial, default: all): Address categorization.
• secondary (boolean, optional, default: true): Whether to include secondary unit numbers (Apt, Suite, Bldg).
• phone (boolean, optional, default: true): Whether to include regional NANPA area code phone numbers.
• format (string, optional, enum: json, csv, sql, xml, txt, default: json): Output representation.
• tableName (string, optional, default: addresses): Custom table name when format=sql.

POST /api/v1/addresses/generate

Batch generate synthetic addresses using a customizable JSON configuration payload.

JSON Body Parameters:

• count (integer, optional, default: 10, min: 1, max: 1000): Number of records to return.
• stateCode (string, optional): 2-letter state code.
• city (string, optional): Specific city filter.
• addressType (string, optional, enum: all, residential, commercial, default: all).
• includeSecondary (boolean, optional, default: true).
• includePhone (boolean, optional, default: true).
• zipFormat (string, optional, enum: 5digit, zip9, default: 5digit).

2. Postal & State Data

GET /api/v1/states

Retrieve all 51 US states and jurisdictions (including Washington, D.C.) with capital cities, coordinate bounds, timezones, and county lists.

Parameters: None.

GET /api/v1/zip/lookup

Query postal database by 5-digit ZIP code or city name to resolve state, county, coordinates, and timezone.

Query Parameters:

• zip or q (string, required): 5-digit ZIP code (e.g. 90210) or city search query.

GET /api/v1/validate (Alias: GET /api/v1/validate/address)

Validate and standardize a synthetic address string against USPS DPV heuristics and postal standards.

Query Parameters:

• address (string, required): Full address string to validate and standardize.

3. Developer Test Utilities

GET /api/v1/phone/generate

Generate realistic US phone numbers adhering to the North American Numbering Plan (NANPA) with valid area codes.

Query Parameters:

• count (integer, optional, default: 10, min: 1, max: 1000): Number of phone numbers.
• state (string, optional): 2-letter state code to use localized area codes.
• areaCode (string, optional): Specific 3-digit area code (e.g. 415, 212, 512).

GET /api/v1/uuid/generate

Generate standard UUID v4 (random) or UUID v1 (timestamp-based) identifiers for database keys.

Query Parameters:

• count (integer, optional, default: 5, min: 1, max: 1000): Number of UUIDs.
• version (string, optional, enum: v4, v1, default: v4): UUID version.

GET /api/v1/password/generate

Generate cryptographically secure random passwords for testing authentication and credential validation.

Query Parameters:

• count (integer, optional, default: 5, min: 1, max: 1000): Number of passwords.
• length (integer, optional, default: 16, min: 4, max: 128): Character length per password.

GET /api/v1/lorem/generate

Generate synthetic Lorem Ipsum placeholder text paragraphs for UI testing and typography layouts.

Query Parameters:

• paragraphs (integer, optional, default: 3, min: 1, max: 100): Number of paragraphs to generate.

GET /api/v1/business-name/generate

Generate realistic synthetic US business, company, and corporate entity names.

Query Parameters:

• count (integer, optional, default: 10, min: 1, max: 1000): Number of company names to generate.

GET /api/v1/number/generate

Generate randomized integer sequences, test code numbers, and numerical arrays across custom ranges.

Query Parameters:

• count (integer, optional, default: 10, min: 1, max: 1000): Quantity of numbers to generate.
• min (integer, optional, default: 1): Lower boundary integer (inclusive).
• max (integer, optional, default: 100): Upper boundary integer (inclusive).
• unique (boolean, optional, default: false): When true, ensures non-repeating numbers in the returned batch.

GET /api/v1/health

System health check endpoint providing uptime status, service name, version, and server timestamp.

Parameters: None.

Working cURL Example & Actual Response Shape

Every street value the API returns is standardised to USPS Publication 28 — see the USPS street suffix abbreviations reference for the suffix and secondary-unit rules the API applies.

cURL Request

curl -s "https://usaddressgenerator.org/api/v1/addresses/random?count=1&state=CA&type=residential"

Actual Response Body (HTTP 200 OK)

{
  "status": "success",
  "count": 1,
  "query": {
    "count": 1,
    "state": "CA",
    "type": "residential"
  },
  "data": [
    {
      "id": "addr_92jyojq_1787034998000",
      "recipientName": "Robert Rodriguez",
      "streetNumber": "3893",
      "directional": "N",
      "streetName": "N Pioneer Rd",
      "streetType": "Rd",
      "secondary": "Apt 4B",
      "city": "Pasadena",
      "state": "CA",
      "stateName": "California",
      "zipCode": "91101",
      "zipPlus4": "3653",
      "fullZip": "91101-3653",
      "county": "Los Angeles County",
      "timezone": "America/Los_Angeles",
      "latitude": 34.148734,
      "longitude": -118.127334,
      "phone": "(626) 698-2016",
      "type": "residential",
      "rdi": "Residential",
      "isDeliverable": true,
      "deliveryPoint": "73",
      "carrierRoute": "C029",
      "formattedSingleLine": "3893 N Pioneer Rd, Apt 4B, Pasadena, CA 91101-3653",
      "formattedMultiLine": "3893 N Pioneer Rd\nApt 4B\nPasadena, CA 91101-3653",
      "formattedEnvelope": "Robert Rodriguez\n3893 N Pioneer Rd\nApt 4B\nPasadena, CA 91101-3653\nUNITED STATES"
    }
  ]
}

POST Batch Generation cURL Example

curl -s -X POST "https://usaddressgenerator.org/api/v1/addresses/generate" \
  -H "Content-Type: application/json" \
  -d '{"count": 2, "stateCode": "TX", "addressType": "commercial", "zipFormat": "5digit"}'