randomaddress.app
API reference · v1

Synthetic Address API Reference

Returns fictional US test records. No request creates or validates a real address, and the service does not promise delivery.

Send a valid synthetic address request.

  • seed required, 1–160 characters.
  • count optional integer, default 1, minimum 1, maximum 20.
  • state, city, zipCode optional exact values from the supported tuple list. Unknown parameters are rejected.

Success response

{
  "dataVersion": "us-major-cities-2026-09-17",
  "records": [{
    "fullName": "Alex Cedar",
    "zipCode": "10001",
    "quality": { "deliverabilityStatus": "not_checked", "fictional": true }
  }]
}

Errors and limits

  • 400 invalid_request: missing/too-long seed, non-integer or out-of-range count, unknown parameter, or invalid filter combination.
  • 405 method_not_allowed: methods other than GET. The response includes Allow: GET.
  • 429 rate_limited: deployed Worker rate limiter rejected the client. Includes Retry-After: 60.

Responses use Cache-Control: no-store. Version changes may intentionally change deterministic output, so persist both seed and dataVersion in a fixture.