Cloudflare Worker · v1.0
Address Generator
Country-aware streets, postal codes and names — generated on demand at the edge, with a JSON API you can call today.
Synthetic data only. E-mails use the reserved example.com domain; postal codes follow each country's real format.
Overview
One Worker, no database, no API key. Every request builds fresh synthetic people and postal addresses for 16 countries. Responses are CORS-enabled, so you can call the API straight from a browser.
/
Same seed + same parameters = identical records. Handy for fixtures and reproducible tests.
/api/randomGenerate one or more records for a single country.
| Param | Type | Required | Description |
|---|---|---|---|
country | string | yes | ISO 3166-1 alpha-2 code (US, GB, JP…) or RANDOM. |
count | integer | no | 1–100. Default 1. |
gender | string | no | any (default), female, male. |
seed | string | no | 1–64 characters. Reuse it for reproducible output. |
{{ORIGIN}}/api/random?country=JP&count=2&gender=female&seed=demo/api/randomSame generator, JSON body. Query parameters are merged, body values win.
curl -X POST {{ORIGIN}}/api/random \
-H "content-type: application/json" \
-d '{"country":"DE","count":3,"gender":"male","seed":"fixtures"}'/api/countriesSupported countries with postal masks, region counts and a sample address. Cached for one hour.
Response
Every successful call returns ok, the resolved country, the echoed request and a data array.
{
"ok": true,
"count": 1,
"country": { "code": "US", "name": "United States", "flag": "🇺🇸" },
"data": [
{
"id": "us_7c1e0a",
"gender": "female",
"name": { "first": "Emily", "last": "Carter", "full": "Emily Carter" },
"address": {
"line1": "1428 Maple Avenue",
"line2": "Apt 12B",
"city": "San Francisco",
"region": "California",
"regionCode": "CA",
"postalCode": "94110",
"country": "United States",
"countryCode": "US",
"formatted": "1428 Maple Avenue\nApt 12B\nSan Francisco, CA 94110\nUnited States"
},
"email": "emily.carter@example.com",
"coordinates": { "lat": 37.7699, "lng": -122.4465 }
}
],
"meta": { "generatedAt": "2026-11-19T08:00:00.000Z", "synthetic": true, "version": "1.0.0", "seed": "a3f19c2e" }
}Errors
Failures always return JSON with a stable machine-readable code.
| Status | Code | When |
|---|---|---|
| 400 | missing_country | No country given. |
| 400 | invalid_country | Code is not supported (response lists the valid ones). |
| 400 | invalid_count | Count is not an integer in 1–100. |
| 400 | invalid_gender | Gender is not any/female/male. |
| 400 | invalid_seed | Seed is empty or longer than 64 characters. |
| 400 | invalid_json | POST body is missing or not a JSON object. |
| 404 | not_found | Unknown API path. |
| 405 | method_not_allowed | Wrong HTTP verb (Allow header included). |
| 415 | invalid_content_type | POST without application/json. |
| 500 | internal_error | Unexpected failure; retry the request. |
Notes
Names are random combinations, not real individuals. Street numbers and postal codes are structurally valid but not guaranteed to be assigned. E-mail addresses always end in @example.com, a domain reserved by RFC 2606, so nothing can be delivered.
The API is stateless and needs no key. Add Cloudflare rate limiting rules if you expose it publicly.
Supported countries
16 locales, each with its own street naming, address order and postal format.