API للمطورين

واجهة API لتوليد العناوين

أنشئ عناوين وهمية ورموزا بريدية وأرقام هاتف وملفات مستخدم تركيبية من endpoint واحد.

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

بدء سريع

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

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

معاملات الاستعلام

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.

أمثلة الطلبات

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

مثال الاستجابة

{
  "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" }
    }
  }
}

حقول الاستجابة

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.

الحدود والأخطاء

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.

استخدام مسؤول

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.

الأسئلة الشائعة

Is the address generator API free?

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