← Back to generatorv1

Real Address Generator API

Each request returns one source-backed address with coordinates and country-specific formatting.

Endpoints

GET/api/v1/countriesCountries, groups, capabilities, counts and shortcuts
GET/api/v1/locations/search?country=US&field=city&regionId=1416&limit=20000Load cities by parent once; regions and postcodes are paged
GET/api/v1/generate?country=US&residential=true&requestId=UUIDGenerate one random address
GET/api/v1/generate?mode=ip-region&ip=198.51.100.7Live IP-coordinate lookup with hot-pool fallback
GET/api/v1/data-healthPer-country data health

Generate parameters

countryISO 3166-1 alpha-2 · default USresidentialtrue | false · defaults to true where supportedregionExact state, province, prefecture or arearegionIdParent region ID used to filter cities and postcodescityExact city valuecityIdCity ID used to filter postcodespostcodeExact postcode, space-insensitivefield / qCatalog field and search text: region, city or postcodecursor / limitRegions/postcodes: 20–200 per page; cities: up to 20,000 per parentseedOptional reproducible random seedrequestIdRequest identifier used to validate response context

Response example

{
  "data": {
    "requestId": "UUID",
    "mode": "residential",
    "country": "US",
    "residential": true,
    "sourcesTried": ["address-pool-v2"],
    "result": {
      "addressFormats": {
        "native": { "postalLines": ["Avery Chen", "20 W 34th Street", "New York, NY 10001", "UNITED STATES"], "singleLine": "20 W 34th Street, New York, NY 10001, UNITED STATES" },
        "en": { "postalLines": ["..."], "singleLine": "..." },
        "zh-CN": { "postalLines": ["..."], "singleLine": "..." }
      },
      "profile": { "fullName": "Olivia Carter", "email": "oliviacarter0000@outlook.com" },
      "card": { "provider": "Stripe", "number": "4242 4242 4242 4242", "sandboxOnly": true },
      "googleMaps": { "status": "map_query", "embedUrl": "https://www.google.com/maps?q=LAT,LNG&z=17&output=embed" }
    }
  }
}

Source policy

Standard and residential requests read only the synchronized SQLite pool, with no runtime provider, translation or geocoding call. Only explicit IP-region mode queries a live source, then falls back through nearby, city, region and country pools. Residential mode always requires independent residential-use evidence.