Address API Reference | randomaddress.app

Request parameters

Start with the address API introduction, or try this request for one New York record:

GET /api/v1/addresses?seed=address-example&count=1&state=NY

seed: required, 1–160 characters.
count: integer from 1 to 20, default 1.
state, city, zipCode: optional exact values from the available address list. Unknown parameters and unavailable filter combinations are rejected.

Explore available cities and ZIP codes in the US address generator before choosing filters.

Success response

{
  "dataVersion": "synthetic-address-v4|public-place-addresses-2026-09-26-13-32-25-3a7a704269b2",
  "records": [
    {
      "id": "sample-1kiab4v",
      "placeName": "",
      "fullName": "Kai Rowe",
      "address1": "242 Meadow Street",
      "city": "New York",
      "state": "NY",
      "stateName": "New York",
      "zipCode": "10010",
      "areaCode": "212",
      "phone": "(212) 555-0126",
      "country": "US",
      "countryName": "United States",
      "source": null,
      "quality": {
        "formatValid": true,
        "geoConsistent": false,
        "deliverabilityStatus": "not_checked",
        "fictional": true,
        "addressStatus": "synthetic",
        "identityStatus": "generated",
        "postalCodeStatus": "provided",
        "sourceVersion": "synthetic-address-v4|public-place-addresses-2026-09-26-13-32-25-3a7a704269b2",
        "seed": "api-reference-v2",
        "localityConsistent": true
      }
    }
  ]
}

Address and identity fields

address1, fullName and phone are generated sample fields. city, state and zipCode stay paired. Preserve ZIP codes as text.

addressStatus: synthetic identifies the generated address. source is null and placeName is empty. The response keeps these fields for existing integrations without attaching a business source to an invented street.

localityConsistent: true describes the city/state/ZIP pairing; geoConsistent: false means the invented street has not been geocoded. deliverabilityStatus: not_checked is unchanged. Use the samples for testing rather than mail delivery.

Errors and limits

400 invalid_request: invalid parameter, count, seed or location combination.
405 method_not_allowed: only GET is supported; the response includes Allow: GET.
429 rate_limited: the deployed client limit was exceeded; Retry-After is 60 seconds.

Responses use Cache-Control: no-store. Preserve seed, filters, count and dataVersion to reproduce output. Data updates may change seed selections; a large batch can reuse the same address.

Need a larger file? The bulk address generator exports up to 1,000 records in CSV, JSON, SQL or plain text.