A self-hosted address and synthetic test-profile generator for 27 countries and regions.
Address combines real open-data streets, administrative areas, coordinates, and postcodes with clearly marked synthetic indoor details. It produces source-language, English, and Simplified-Chinese address presentations plus coherent profile fields for form and software testing.
Generated records are test data. They do not prove deliverability, residency, identity, payment-account validity, or ownership.
Choose a country and location → select ordinary or evidence-backed residential mode → generate an address and test profile → copy individual fields or export the result.
- Covers 27 countries and regions with region, city, and postcode filters.
- Uses exact → nearby → same-region → nationwide fallback for synchronized countries.
- Supports IP-nearby generation with a local SQLite RTree fallback.
- Presents addresses in the source language, English, and Simplified Chinese.
- Separates source-backed address components from labeled synthetic indoor fields.
- Generates coherent basic profile, sandbox card, employment, finance, and network fields.
- Provides Google coordinate preview, address search, and an AMap link for China.
- Hot-reloads a custom blacklist and preserves evidence/source attribution.
- Supports resumable initial imports, daily country rotation, quality gates, and storage limits.
The default synchronized pool uses the following source family for each country. Live providers may be used only when the corresponding mode and credential are enabled; they do not replace the default offline pool.
| Country / region | Default source | Real/source-backed address fields | Generated/synthetic address fields |
|---|---|---|---|
| United States (US) | Overture Maps | House number, street, city, state, ZIP, source geometry | None for ordinary records; missing apartment details may generate Apt/room |
| Canada (CA) | Overture Maps | House number, street, city, province, postal code, source geometry | None for ordinary records; missing apartment details may generate Unit/room |
| Mexico (MX) | Overture Maps | House number, street, municipality, state, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| United Kingdom (GB) | Geofabrik OSM | House number, street, town, postcode, source geometry | None for ordinary records; missing apartment details may generate Flat |
| Germany (DE) | Overture Maps | House number, street, city, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| France (FR) | Overture Maps | House number, street, city, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Italy (IT) | Overture Maps | House number, street, city, region, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Spain (ES) | Overture Maps | House number, street, city, province, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Netherlands (NL) | Overture Maps | House number, street, city, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Russia (RU) | Geofabrik OSM | House number, street, city, federal subject, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| China (CN) | Geofabrik OSM | Province/municipality, city, district, road, source geometry; nearby named OSM community when available | House number; lexicon community fallback; missing building/unit/room details |
| Hong Kong (HK) | Geofabrik OSM | Building/street, district, area, source geometry | Missing floor/flat/room details may be generated |
| Taiwan (TW) | Overture Maps | House number, street, city/county, district, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Japan (JP) | Overture Maps | Block/house number, street, municipality, prefecture, postcode, source geometry | None for ordinary records; missing apartment room details may be generated |
| South Korea (KR) | Geofabrik OSM | Road, building number, district, city/province, postcode, source geometry | Missing building/unit/room details may be generated |
| Singapore (SG) | Geofabrik OSM | House number, street, locality, postcode, source geometry | Missing apartment unit may be generated |
| Vietnam (VN) | Geofabrik OSM | House number, street, district, city, province, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Thailand (TH) | Geofabrik OSM | House number, street, city, province, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Philippines (PH) | Geofabrik OSM | House number, street, barangay/district, city, region, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Malaysia (MY) | Geofabrik OSM | House number, street, district, city, state, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| India (IN) | Geofabrik OSM | House number, street, district, city, state, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Australia (AU) | Overture Maps | House number, street, suburb, state, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Türkiye (TR) | Geofabrik OSM | House number, street, city, province, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Saudi Arabia (SA) | Geofabrik OSM | House number, street, city, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Brazil (BR) | Geofabrik OSM | House number, street, city, state, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| Nigeria (NG) | Geofabrik OSM | House number, street, city, state, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
| South Africa (ZA) | Geofabrik OSM | House number, street, suburb, postcode, source geometry | None for ordinary records; missing apartment details may be generated |
None for ordinary records means the street-level address fields are not invented; an apartment record can still receive a synthetic indoor field when the source has no official unit.
| Field | Provenance |
|---|---|
| Country, region, city, district, and street | Source-backed and normalized from the address record; missing administrative labels may be filled from the local catalog. |
| House number | Source-backed for non-China countries. China intentionally replaces it with a deterministic test number. |
| Postcode | Uses a valid source postcode when available; invalid or missing values may be filled from the nearest catalog entry. |
| Coordinates | Copied from the source geometry. Depending on the source, this may be an address point, building point, or the centroid of an OSM way. |
| Building or community | Uses a source value when present. For China, a nearby named OSM residential community is preferred; the bundled lexicon is only the no-coverage fallback. |
| Apartment, building, unit, and room | Keeps official/source-tagged values when present. Missing indoor details may be generated for China and apartment records in other countries. |
| Name, phone, email, employment, finance, network, and sandbox card | Synthetic test data. |
China therefore means real administrative and road context plus a source coordinate, with a synthetic house number and possible synthetic indoor details. The other countries keep source house numbers, while missing apartment/unit details may still be generated. verified means that source evidence and project quality checks passed; it does not mean that the address is current, occupied, or deliverable.
- Google coordinate preview opens
latitude,longitudefrom the source geometry. It is a location preview, not a Google delivery or occupancy certificate. - Google address search uses only the address skeleton. Synthetic China house numbers, community names, and indoor units are excluded from that query; non-China searches use source-backed house number, street, locality, region, and postcode.
- AMap is generated only for China. The source WGS-84 coordinate is converted to GCJ-02 before opening the AMap marker URL.
- A map pin may represent an address point, building centroid, or way centroid rather than an entrance or room. The default generation path does not claim that a Google Geocoding result has independently verified every record.
For detailed field examples and source notes, see address formats, data sources, and the API documentation.
View the complete United States and China WebUI preview
| United States | China |
|---|---|
 |
 |
| Generator | Generator |
 |
 |
| Address | Address |
 |
 |
| Basic profile | Basic profile |
 |
 |
| Sandbox card | Sandbox card |
 |
 |
| Employment | Employment |
 |
 |
| Finance | Finance |
 |
 |
| Network and extended fields | Network and extended fields |
 |
 |
| Google Maps | Google Maps |
 |
 |
| Document | Contents |
|---|---|
| API documentation | Public endpoints, parameters, errors, sync management, CORS, and examples |
| Deployment documentation | API keys, private configuration, VPS, Nginx, synchronization, backup, and capacity |
| Development documentation | Architecture, local setup, data pipeline, extension points, tests, and release gates |
Node.js 24 or newer is required.
git clone https://github.com/daimon3332/address.git
cd address
cp .env.example .env
npm ci
npm run db:migrate
npm run devA new database contains schema only. Run npm run data:address-pool:bootstrap for the resumable 27-country import. See the deployment guide before running a production VPS.
Offline generation and data synchronization need no third-party API key. AMap, Geoapify, Youdao, and OneMap credentials enable optional live-provider features; SYNC_ADMIN_TOKEN protects VPS synchronization control. Put real values only in ignored .env, .deploy.env, or /root/address/runtime/address.env files. Never add credentials to source, browser code, screenshots, issues, or CI logs.
Measured after all 27 countries were synchronized on 2026-07-23 at commit 084805e:
| Item | Measured size |
|---|---|
address.sqlite |
6.90 GiB |
Complete data/ directory |
7.89 GiB |
| Initial-import peak | About 11.2 GiB |
Actual size varies with upstream releases and WAL activity. A production application volume of at least 60 GiB is recommended for synchronization, backups, and recovery space.
United States, Canada, Mexico, United Kingdom, Germany, France, Italy, Spain, Netherlands, Russia, China, Hong Kong, Taiwan, Japan, South Korea, Singapore, Vietnam, Thailand, Philippines, Malaysia, India, Australia, Turkey, Saudi Arabia, Brazil, Nigeria, and South Africa.
- Overture Maps provides selected address records with source-specific metadata and terms.
- OpenStreetMap and Geofabrik provide other source data under ODbL 1.0.
- Client IP is used only for a requested location lookup and is not written to the address database.
- Indoor details, profiles, and card fields are synthetic test data.
Project code is released under the MIT License. Redistributed data remains subject to its source licenses, attribution, and share-alike terms. The repository and releases contain no production database or private credentials.