API developpeur

API de generation d'adresses

Generez des adresses fictives, codes postaux, numeros de telephone et profils synthetiques depuis un endpoint JSON.

FormatJSON

AuthNo key

Limit600/hour

CORSEnabled

Endpoint

Responses are JSON and include CORS headers, so you can call the API from scripts, backend services, CI jobs, and browser-based developer tools.

GEThttps://genaddr.com/api/v1/address

Demarrage rapide

Send a GET request. No API key is required for the public endpoint.

curl "https://genaddr.com/api/v1/address"

Parametres

countryUS

ISO-3166 alpha-2 country code. Supported: US, CA, GB, AU, DE, FR, ES, IT, NL, JP, KR, CN, TW, HK, SG, TH, PH, MY, TR, VN, IN.

admin1random

State, province, prefecture, or region code. Aliases: state, region, province.

cityrandom

Exact city name. Hyphenated URL values such as Los-Angeles are accepted.

count1

Number of records to generate, from 1 to 100. Multiple records return an addresses array.

has_number0

Compatibility filter for integrations that require numbered street addresses. Alias: hasNumber.

Exemples de requete

Two California addresses

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

Los Angeles address with a street number

curl "https://genaddr.com/api/v1/address?country=US&state=CA&city=Los-Angeles&has_number=1"

International test data

curl "https://genaddr.com/api/v1/address?country=JP&admin1=40&city=Tokyo&count=3"

Code examples

Use the address generator API from frontend tools, backend jobs, automated tests, and seed scripts. These examples request synthetic test data only.

JavaScript fetch

const res = await fetch("https://genaddr.com/api/v1/address?country=US&state=CA&count=5");
const data = await res.json();
console.log(data.addresses ?? [data.address]);

Python requests

import requests

res = requests.get("https://genaddr.com/api/v1/address", params={"country": "DE", "count": 3})
res.raise_for_status()
print(res.json())

OpenAPI schema

Download the machine-readable OpenAPI schema for client generation, API catalogs, documentation tools, and contract tests.

View openapi.json

Exemple de reponse

{
  "status": "ok",
  "meta": {
    "apiVersion": "v1",
    "count": 1,
    "country": "US",
    "admin1": "CA",
    "city": "Los Angeles",
    "hasNumber": true,
    "datasetVersion": "2026-06-02"
  },
  "address": {
    "country": "US",
    "countryName": "United States",
    "fullName": "Quinn Hayes",
    "street": "9942 Willow Creek Road",
    "city": "Los Angeles",
    "admin1Code": "CA",
    "postal": "90001",
    "phone": "+1 562 907 2402",
    "email": "quinn.hayes@example.com",
    "unverifiable": {
      "street": { "unverifiable": false, "source": "openaddresses" }
    }
  }
}

Champs de reponse

Each record includes address fields, profile fields, phone and fax, employment data, payment test fields, login fields, user agent, map URL, and provenance flags.

Developer use cases

QA automationGenerate repeatable address records for Playwright, Cypress, Selenium, and API integration tests.
Database seed dataFill staging databases with synthetic address, phone, email, company, and profile fields.
Checkout validationExercise shipping, billing, postal-code, and phone-number validation flows without using customer data.
Demos and prototypesPopulate dashboards, CRM tables, onboarding screens, and admin tools with realistic-looking sample data.

Limites et erreurs

Public calls are limited to 600 requests per hour per IP address. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

400 unsupported_country - the country code is not in the dataset.
404 not_found - no matching state, region, or city was found.
429 rate_limit_exceeded - the client exceeded the hourly limit.

Utilisation responsable

All personal data returned by this API is fictitious and for development/testing only. Do not use generated data for impersonation, identity verification, payment attempts, or illegal activity.

Questions frequentes

Is the address generator API free?

Yes. The public API is free to call without signup, with an hourly IP-based limit.