Self-hosted Real Address Generator backed by PostgreSQL
Address generates real addresses from official registers and map data. China uses residential-community addresses; other countries also support real street-level addresses, preserving source house numbers when available. Missing premises are never invented. Source coordinates link each address to Google Maps or AMap.
- 27 configured countries and regions with country, administrative-area, city, district, and postcode filters where supported.
- Strict filter semantics: an empty matching pool returns an error instead of silently switching to another location.
- Fast database-backed random selection across the complete eligible scope; it does not repeatedly read the first rows.
- Source/native, English, Simplified Chinese, Traditional Chinese, Japanese, Korean, German, French, Spanish, and Portuguese presentation paths.
- Address and profile language choices persist independently in the browser; first use defaults to English.
- Browser-persistent address favorites with continent/country grouping, filters, drag-and-drop or numeric ordering, copy, delete, and Google Maps/AMap links.
- Popular administrative areas, popular cities, and special areas are configurable per country. The United States includes states without statewide sales tax.
- Public coverage monitor plus administrator dashboard, address-data rules, synchronization queue and history, quick-location editor, provider credentials, access control, blacklist, and API tokens.
- JSON API for health, readiness, countries, availability, location options, search, address/profile generation, batch generation, and monitoring, with Python, cURL, and JavaScript examples.
- PostgreSQL-only runtime with pooled connections, transactional publication, indexed location search, and prebuilt random-address indexes.
| Region | Countries and regions |
|---|---|
| North America | US, CA, MX |
| Europe | GB, DE, FR, IT, ES, NL, RU |
| East Asia | CN, HK, TW, JP, KR |
| Southeast Asia | SG, MY, TH, PH, VN |
| South Asia | IN |
| Oceania | AU |
| Middle East | TR, SA |
| South America | BR |
| Africa | NG, ZA |
The table lists fields and residential evidence supplied by existing sources. Outside China, real street-level records do not require house numbers or residential evidence. Their missing premises stay empty; postcodes are retained only when verified and unambiguous. All records require valid source, geography and language. Residential evidence applies only to the residential subset.
| Country/region | Current address sources | Address components | Real/source fields | Synthesized or completed fields | Residential evidence |
|---|---|---|---|---|---|
| United States (US) | Overture Maps and state-level Geofabrik OSM shards | house number, street, city, state, ZIP, coordinates | all address fields and coordinates | none; reversible formatting only | explicit OSM/Overture residential building or use |
| Canada (CA) | Statistics Canada National Address Register, Overture Maps, and Geofabrik OSM | house number, street, city, province, postcode, coordinates | NAR/source address fields and coordinates | none; postcode formatting only | NAR residential building use or explicit map residential use |
| Mexico (MX) | INEGI national address framework; Geofabrik/Overture; same-origin archive for names | house number, street, colonia, municipality, state, postcode, coordinates | original INEGI address, administrative, postcode, and coordinate fields | deterministic state/city name mapping only; no address generation | INEGI TIPODOM=VIVIENDA |
| United Kingdom (GB) | Geofabrik OSM; Postcodes.io/ONS for validation only | flat/building, house number, street, town, postcode, coordinates | all fields present in OSM and source coordinates | none; formatting only | explicit OSM/building residential use |
| Germany (DE) | Overture Maps, 16 Geofabrik state shards; OpenPLZ assistance | house number, street, city, postcode, coordinates | all address fields and coordinates | none; no invented Wohnung/Etage | explicit residential building or use |
| France (FR) | CSTB BDNB joined to BAN, Overture Maps, and 27 Geofabrik regional shards | house number, street, suffix, commune, postcode, coordinates | BDNB/BAN or map-source address fields and coordinates | none; formatting only | BDNB residential use with a reliable BAN join, or explicit map residential use |
| Italy (IT) | Overture Maps and Geofabrik OSM | house number, street, city, province/region, CAP, coordinates | all address fields and coordinates | none; no invented internal number | explicit residential building or use |
| Spain (ES) | Catastro INSPIRE address/building data, Overture Maps, and Geofabrik OSM | house number, street, municipality, province, postcode, coordinates | Catastro or map-source address fields and coordinates | none; stair/door retained only when sourced | Catastro residential use and dwelling count, or explicit map residential use |
| Netherlands (NL) | Kadaster BAG via PDOK and Overture Maps | house number/letter/addition, street, city, province, postcode, coordinates | all BAG/source address fields and coordinates | none; reversible number formatting only | active BAG woonfunctie or explicit Overture residential use |
| Russia (RU) | Geofabrik OSM | house number, street, locality, federal subject, postcode, coordinates | all address fields and coordinates | none; no invented корпус/квартира | explicit OSM residential building |
| China (CN) | AreaCity/StatsGov plus AMap, Baidu, and Tencent residential-community POIs | province, city, district, street/house number, community, building/unit/floor/room, coordinates | administrative areas, community name, street/house number, and provider coordinates | only building, unit, floor, and room are synthesized and marked synthetic; no postcode generation |
strict residential class, matching district, numeric house number, and institutional blacklist gates |
| Hong Kong (HK) | Housing Authority public-housing units, Buildings Department records, ALS, Geofabrik/Overture | unit/floor, building, house number, street, locality, 18 districts, region, coordinates | official public-housing or private residential-building fields and coordinates; no general postcode | none | Housing Authority inventory or Buildings Department Residential/Composite Tower |
| Taiwan (TW) | Ministry of the Interior transactions, Chunghwa Post 3+3, local-government address points, Geofabrik/Overture | house number, road/section/lane/alley, township/district, county/city, postcode, coordinates | residential transaction address, administrative fields, uniquely matched postcode, and coordinates | none; no nearest-point completion | explicit residential primary use and building type in transaction data |
| Japan (JP) | Digital Agency ABR/Geolonia, Japan Post, PLATEAU/MLIT, Geofabrik OSM | prefecture, municipality, town/chome, block/residence number or parcel number, postcode, coordinates | ABR address fields, uniquely matched Japan Post postcode, and source coordinates | none; missing building and room stay empty | address point lies exactly inside a PLATEAU/OSM residential building |
| South Korea (KR) | K-apt, Geoapify, archived Juso/OpenAddresses, Geofabrik/Overture | province/city, city/county/district, town, road, building number, postcode, coordinates | K-apt parcel address, Juso fields, and matched Geoapify roads/premises | none; unknown postcodes stay empty; no invented building, unit, or room | official K-apt complex or Juso point intersecting a residential building; Geoapify alone is not residential evidence |
| Singapore (SG) | HDB Property Information, Existing Building, OneMap, Geofabrik OSM | block number, road, planning town, six-digit postcode, coordinates | HDB block, road, town; matched OneMap roads, premises and coordinates | source fields only; unknown postcodes stay empty; no house-number generation | HDB residential=Y with dwelling units, or an OSM residential building; OneMap alone is not residential evidence |
| Malaysia (MY) | Geofabrik OSM Malaysia shard | unit/lot, building, street, district, city, state, postcode, coordinates | all fields present in OSM and source coordinates | none; no invented unit | explicit OSM residential building with commercial POIs excluded |
| Thailand (TH) | DPT official building layer, Geofabrik OSM, Google Geocoding enrichment | house number, moo, village/road, subdistrict, district, province, postcode, coordinates | DPT or OSM address, administrative, postcode, and geometry fields | none; polygon-to-point conversion and formatting only | DPT residential building classes or explicit OSM residential building |
| Philippines (PH) | Geofabrik OSM, Google Geocoding, PHLPost; PSA PSGC for administrative validation | house number, street, barangay, city/municipality, province, postcode, coordinates | OSM address fields and coordinates | a missing postcode may be completed only by a unique PHLPost province+city/municipality match | explicit OSM residential building |
| Vietnam (VN) | Geofabrik OSM; Google Geocoding enrichment | house number, street, ward/commune, province-level city/province, postcode, coordinates | source fields and coordinates | none; only five-digit postcodes accepted | explicit OSM residential building |
| Türkiye (TR) | Geofabrik OSM, Google Geocoding, existing İzmir Building Identity data | house number, street, district, province, postcode, coordinates | all sourced address fields and coordinates | none; formatting only | OSM residential tag or official Konut use |
| Saudi Arabia (SA) | Geofabrik OSM, Google Geocoding; optional national points via OpenAddresses | building/house number, street, district, city, postcode, coordinates | national-address point fields and coordinates | none; formatting only | address point exactly associated with an explicit residential building |
| India (IN) | Geofabrik OSM; Mappls Reverse Geocoding; Google Geocoding enrichment | house number, street/locality, district, city, state, PIN, coordinates | OSM roads and source premises; matched geocoder address, administrative fields and known PIN | none; no invented apartment or floor | explicit OSM residential building |
| Australia (AU) | Overture Maps and Geofabrik OSM | unit, house number, street, suburb, state, postcode, coordinates | all sourced address fields and coordinates | none; no invented unit | explicit residential building/use; address existence alone is insufficient |
| Brazil (BR) | Geofabrik OSM | house number, street, neighborhood, city, state, CEP, coordinates | all fields present in OSM and source coordinates | none; no invented complemento | explicit OSM residential building |
| Nigeria (NG) | Geofabrik OSM; Google Geocoding enrichment | house number, street, district, city, state, postcode, coordinates | source fields and coordinates | none; missing fields are not inferred | explicit OSM residential building |
| South Africa (ZA) | eThekwini official addresses/zoning, Cape Town official parcels, Geofabrik OSM, SAPO | unit, house number, street, suburb, city, postcode, coordinates | official address/parcel fields, supplemental OSM fields, uniquely matched SAPO postcode, and coordinates | none; no invented unit | exact official residential-zoning association or explicit OSM residential building |
See data sources and the country/region strategies for source versions, coordinate systems, deduplication, and publication gates.
| United States generator | China generator |
|---|---|
 |
 |
| Dashboard | Address data |
|---|---|
 |
 |
| Synchronization queue | Quick locations |
 |
 |
Astro static pages + React UI
│
▼
Hono Node.js API
├─ PostgreSQL address and control data
├─ in-memory random/filter indexes rebuilt from PostgreSQL
└─ local formatting, profile generation, and optional translation
Synchronization supervisor
├─ resumable bulk/API adapters
├─ country-specific precision, language and evidence validation
├─ transactional PostgreSQL publication
└─ coverage statistics and bounded queue state
A country is complete only when every enabled rule passes:
- total eligible-record target;
- lowest administrative-level coverage and per-node minimums;
- level-1 and level-2 minimums where configured;
- every explicit node override.
Reaching only the total target does not mark a country complete. Conversely, a source proven to be exhausted is kept visible as incomplete but removed from active work until its source/version fingerprint changes.
The queue applies bounded retries, exponential backoff, cooldown/quota reset times, resumable checkpoints, no-progress latching, and suspension after repeated failures. It cannot run the same unchanged no-progress source indefinitely. Run history records each source, duration, result, and address growth, while stale synchronization artifacts are cleaned automatically. China receives the highest automatic priority while it remains eligible.
mkdir address && cd address
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/daimon3332/address/main/docker-compose.yml
docker compose up -dThe initial administrator password is admin; the frontend password is disabled. Change either initial value in docker-compose.yml before the first start. The administrator console requires the default administrator password to be replaced after sign-in.
See the deployment guide for complete instructions.
- Frontend and administrator passwords, API tokens, provider credentials, quotas, and quick locations are managed in the administrator console.
- Provider keys are optional unless the selected synchronization strategy needs them.
- Multiple credentials rotate independently. A failing key is cooled down while another available key is tried; when all keys are unavailable, work waits for the earliest reset.
- Follow the dedicated API key configuration guide for provider purposes, official application links, and administrator entry names.
| Document | Purpose |
|---|---|
| API reference | Bearer authentication, generation, filtering, errors, and monitoring |
| API keys | Provider purpose, registration links, required products, and administrator configuration |
| Deployment | PostgreSQL, VPS layout, process control, Nginx, backup, restore, and upgrades |
| Development | Architecture, local checks, extension points, and release gates |
| Address formats | Country formatting and field behavior |
| Country strategies | Source, evidence, coordinates, deduplication, validation, and update policy |
- linux.do: Learn AI at L-Site!!!
Project source code is licensed under MIT. Upstream datasets retain their own licenses and attribution requirements.