Address Generator API

A free public REST API that returns realistic, geographically self-consistent synthetic addresses: the ZIP/postal code, city, and region agree, and the phone area code matches the city. Ideal for seeding test databases, CI pipelines, and automated QA.

Endpoint

GET https://genaddr.com/api/v1/address

Query parameters

Param	Default	Description
country	US	ISO-3166 alpha-2 country code. Currently US is fully backed by real geographic data.
admin1	—	Optional state/province code (e.g. CA, NY) to constrain the location.
city	—	Optional exact city name to fix the city.
count	1	Number of records (1–100). With count>1 the response uses an `addresses` array.

Example request

curl "https://genaddr.com/api/v1/address?country=US&admin1=CA&count=2"

Example response

{
  "status": "ok",
  "address": {
    "country": "US",
    "city": "Newport Coast",
    "admin1Code": "CA",
    "admin1Name": "California",
    "postal": "92657",
    "street": "9942 Willow Creek Road",
    "phone": "+1 562 907 2402",
    "fullName": "Quinn Hayes",
    "cardType": "Visa",
    "cardNumber": "4xxx xxxx xxxx xxxx",
    "...": "all four field groups included"
  }
}

Rate limit

Unauthenticated clients get 60 requests per hour per IP. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Exceeding the limit returns HTTP 429.

Errors

400 — unsupported country
404 — no matching city/region found
429 — rate limit exceeded

Terms

All data is fictitious and for development and testing only. Do not use it for impersonation, payment, or identity verification.