Data sources, coverage and method
Every generated address combines real geography with synthetic details. This page lists what is real, where it comes from, how each country is graded, and what we know is incomplete. Data version 2026.10.1, built 2026-10-26.
Coverage levels
| Level | Countries | Meaning |
|---|---|---|
| A Dataset-matched | 121 | City, region and postcode come from one dataset record. |
| B Places verified | 70 | City and region are dataset-backed; postcodes are not linked to places. |
| C Format example | 52 | Generic layout with real place names; national format not documented. |
| N No civilian addresses | 7 | No conventional addresses exist, so nothing is generated. |
A country never moves up a level because we filled a gap with invented data. When information is missing, we leave the field out or label it.
What is real and what is synthetic
| Field | Source |
|---|---|
| Locality, region, postcode | One record from the GeoNames postal dataset, Japan Post’s KEN_ALL file, or Google’s address hierarchy (China, Taiwan, Hong Kong). For countries without postal data: GeoNames populated places (≥ 500 inhabitants) and first-level divisions. |
| Address layout | Google’s address metadata (libaddressinput), the format data used by Chrome and Android. |
| Local-script names | From the dataset itself where available (Japan, Korea, Russia, Bulgaria…), otherwise GeoNames alternate names in the country’s language. |
| Street names | Synthetic. Built from common street-type words and generic name roots for each address language (for example “Lindenstraße”, “rue des Lilas”, “King Fahd Street”). Not taken from maps. |
| House numbers, units | Synthetic. Japanese block numbers, Korean road numbers and Colombian grid numbers follow local conventions. |
| Names | @faker-js/faker locale lists (MIT) plus curated lists for under-served regions. 76 countries have a country-specific list, 74 a language-level list and 93 a regional approximation, labelled on each country page. |
Always example.com, example.net or example.org (reserved by RFC 2606). | |
| Phone | Regulator-reserved fictional ranges (NANPA 555-01XX, Ofcom drama numbers, ACMA, ARCEP). Elsewhere, the national number shape from libphonenumber metadata, with digits masked. |
| Coordinates | Approximate centre of the locality from the same dataset record, rounded to 3 decimals. |
Validation
- For every generating country, the automated tests generate 40 addresses and profiles and check that each locality, region and postcode match one source record. They also check postcodes against the national pattern, the use of local script, formatting artefacts, reserved e-mail domains and phone labelling, and that the output is deterministic.
- Postal datasets are kept only when at least 60% of their codes match the national pattern in Google’s metadata; codes that do not match are dropped. In German-speaking countries, rows for companies and offices with their own postcodes are removed by matching localities against GeoNames populated places.
- Each source file’s SHA-256 checksum is recorded below, so the build can be reproduced and audited.
Places by source: GeoNames populated places (cities500): 146 countries; GeoNames postal codes: 93 countries; Google address metadata hierarchy (libaddressinput): 3 countries; Japan Post postal code data (KEN_ALL, UTF-8 and romaji editions): 1 countries. 172,465 localities in total.
Source files and licences
| Source | Licence | Retrieved | Size | SHA-256 |
|---|---|---|---|---|
| GeoNames country info | CC BY 4.0 | 2026-10-25 | 32 KB | c55f638cfaafb4fe… |
| GeoNames first-level administrative divisions | CC BY 4.0 | 2026-10-25 | 152 KB | 2e4867f5397acb05… |
| GeoNames populated places with population ≥ 500 | CC BY 4.0 | 2026-10-25 | 13.9 MB | 2709e682708bc5a8… |
| GeoNames alternate names (local-script names) | CC BY 4.0 | 2026-10-25 | 205.2 MB | 635560bb5c90b9b7… |
| GeoNames postal codes, all countries | CC BY 4.0 | 2026-10-25 | 19.8 MB | fe0ee75c60cc1f83… |
| GeoNames full UK postcodes | CC BY 4.0 (contains Royal Mail and OS data via ONS) | 2026-10-25 | 15.0 MB | b64cd52fe5112777… |
| GeoNames full Canadian postal codes | CC BY 4.0 | 2026-10-25 | 6.4 MB | f58a84568a0890f6… |
| GeoNames full Dutch postcodes | CC BY 4.0 | 2026-10-25 | 3.6 MB | 0ca6a6df7bdd8dbb… |
| Japan Post postal code data (UTF-8) | Japan Post claims no copyright and allows free redistribution | 2026-10-25 | 2.1 MB | 444881769a631d2c… |
| Japan Post postal code data (romaji) | Japan Post claims no copyright and allows free redistribution | 2026-10-25 | 1.8 MB | 9764834dfd1d0148… |
| Google address metadata (libaddressinput) via google-i18n-address 3.1.1 | Google data: Apache 2.0 (libaddressinput); package: BSD-3-Clause | 2026-10-26 | 773 KB | f66f4fd2b75d1cd3… |
| @faker-js/faker 10.6.0 (name lists, job titles) | MIT | |||
| libphonenumber-js 1.13.15 (calling codes and national number shapes) | MIT (metadata from Google libphonenumber, Apache 2.0) |
GeoNames data is used under Creative Commons Attribution 4.0. Japan Post states it claims no copyright over its postcode data and that it may be redistributed freely. Google’s libaddressinput is licensed under Apache 2.0.
Coverage by country
All 250 entries: the 249 ISO 3166-1 codes plus Kosovo (XK).
| Country | Level | Localities | Regions | Postcodes | Names |
|---|---|---|---|---|---|
 Afghanistan AF | B | 319 | 34 | format-only | country |
 Åland Islands AX | A | 37 | 3 | dataset | language |
 Albania AL | A | 494 | 12 | dataset | country |
 Algeria DZ | A | 2,403 | 48 | dataset | regional |
 American Samoa AS | A | 1 | 1 | dataset | regional |
 Andorra AD | A | 7 | 7 | dataset | regional |
 Angola AO | C | 563 | 20 | none | language |
 Anguilla AI | A | 14 | 14 | single | language |
 Antarctica AQ | N | 0 | 0 | — | — |
 Antigua and Barbuda AG | C | 41 | 7 | none | language |
 Argentina AR | A | 2,398 | 23 | dataset | language |
 Armenia AM | A | 87 | 2 | dataset | country |
 Aruba AW | C | 10 | 0 | none | language |
 Australia AU | A | 2,526 | 8 | dataset | country |
 Austria AT | A | 2,393 | 9 | dataset | country |
 Azerbaijan AZ | A | 1,186 | 64 | dataset | country |
 Bahamas BS | A | 35 | 30 | none | language |
 Bahrain BH | B | 12 | 4 | format-only | regional |
 Bangladesh BD | A | 1,347 | 7 | dataset | country |
 Barbados BB | B | 16 | 10 | format-only | language |
 Belarus BY | A | 2,400 | 6 | dataset | language |
 Belgium BE | A | 2,400 | 3 | dataset | country |
 Belize BZ | C | 138 | 6 | none | language |
 Benin BJ | C | 87 | 12 | none | regional |
 Bermuda BM | A | 112 | 11 | dataset | language |
 Bhutan BT | B | 35 | 20 | format-only | country |
 Bolivia BO | C | 183 | 9 | none | language |
 Bosnia and Herzegovina BA | B | 311 | 3 | format-only | country |
 Botswana BW | C | 139 | 16 | none | regional |
 Bouvet Island BV | N | 0 | 0 | — | — |
 Brazil BR | A | 3,501 | 27 | dataset | country |
 British Indian Ocean Territory IO | N | 0 | 0 | — | — |
 British Virgin Islands VG | B | 2 | 0 | format-only | language |
 Brunei BN | B | 63 | 4 | format-only | regional |
 Bulgaria BG | A | 2,395 | 28 | dataset | country |
 Burkina Faso BF | A | 118 | 13 | none | regional |
 Burundi BI | C | 33 | 15 | none | regional |
 Cabo Verde CV | B | 153 | 22 | format-only | language |
 Cambodia KH | B | 338 | 25 | format-only | country |
 Cameroon CM | C | 145 | 10 | none | regional |
 Canada CA | A | 3,913 | 13 | dataset | language |
 Caribbean Netherlands BQ | C | 10 | 3 | none | language |
 Cayman Islands KY | B | 70 | 6 | format-only | language |
 Central African Republic CF | C | 51 | 20 | none | regional |
 Chad TD | C | 74 | 23 | none | regional |
 Chile CL | A | 346 | 15 | dataset | language |
 China CN | A | 2,852 | 31 | dataset | country |
 Christmas Island CX | A | 1 | 0 | single | regional |
 Cocos (Keeling) Islands CC | A | 1 | 0 | single | regional |
 Colombia CO | A | 2,405 | 33 | dataset | language |
 Comoros KM | C | 118 | 3 | none | regional |
 Cook Islands CK | C | 2 | 1 | none | regional |
 Costa Rica CR | A | 473 | 7 | dataset | regional |
 Côte d'Ivoire CI | A | 1,204 | 14 | none | regional |
 Croatia HR | A | 2,399 | 21 | dataset | country |
 Cuba CU | B | 191 | 16 | format-only | regional |
 Curaçao CW | C | 12 | 0 | none | language |
 Cyprus CY | A | 1,126 | 6 | dataset | language |
 Czechia CZ | A | 2,401 | 14 | dataset | country |
 Democratic Republic of the Congo CD | C | 118 | 26 | none | regional |
 Denmark DK | A | 1,159 | 5 | dataset | country |
 Djibouti DJ | C | 32 | 6 | none | regional |
 Dominica DM | C | 20 | 10 | none | language |
 Dominican Republic DO | A | 542 | 0 | dataset | regional |
 Ecuador EC | A | 1,176 | 24 | dataset | language |
 Egypt EG | B | 254 | 27 | region-prefix | country |
 El Salvador SV | B | 102 | 14 | region-prefix | regional |
 Equatorial Guinea GQ | C | 28 | 8 | none | language |
 Eritrea ER | C | 18 | 6 | none | regional |
 Estonia EE | A | 2,399 | 15 | dataset | country |
 Eswatini SZ | B | 25 | 4 | format-only | regional |
 Ethiopia ET | B | 256 | 14 | format-only | regional |
 Falkland Islands FK | A | 1 | 0 | single | language |
 Faroe Islands FO | A | 130 | 0 | dataset | regional |
 Fiji FJ | C | 16 | 5 | none | regional |
 Finland FI | A | 2,399 | 18 | dataset | country |
 France FR | A | 3,514 | 13 | dataset | country |
 French Guiana GF | B | 20 | 1 | format-only | language |
 French Polynesia PF | A | 207 | 5 | dataset | language |
 French Southern Territories TF | N | 0 | 0 | — | — |
 Gabon GA | C | 50 | 9 | none | regional |
 Gambia GM | C | 176 | 6 | none | regional |
 Georgia GE | B | 218 | 12 | format-only | country |
 Germany DE | A | 3,833 | 16 | dataset | country |
 Ghana GH | C | 116 | 16 | none | country |
 Gibraltar GI | A | 2 | 0 | single | language |
 Greece GR | B | 1,198 | 14 | format-only | country |
 Greenland GL | A | 32 | 0 | dataset | regional |
 Grenada GD | C | 10 | 7 | none | language |
 Guadeloupe GP | B | 25 | 1 | format-only | language |
 Guam GU | A | 20 | 1 | dataset | language |
 Guatemala GT | A | 543 | 21 | dataset | regional |
 Guernsey GG | B | 12 | 10 | format-only | language |
 Guinea GN | B | 83 | 8 | format-only | regional |
 Guinea-Bissau GW | B | 44 | 9 | format-only | language |
 Guyana GY | C | 22 | 10 | none | language |
 Haiti HT | A | 236 | 10 | dataset | country |
 Heard Island and McDonald Islands HM | N | 0 | 0 | — | — |
 Honduras HN | A | 38 | 18 | dataset | regional |
 Hong Kong HK | A | 124 | 3 | none | country |
 Hungary HU | A | 2,400 | 20 | dataset | country |
 Iceland IS | A | 195 | 0 | dataset | country |
 India IN | A | 4,521 | 35 | dataset | country |
 Indonesia ID | A | 2,398 | 32 | dataset | country |
 Iran IR | B | 1,203 | 31 | format-only | country |
 Iraq IQ | B | 170 | 19 | format-only | regional |
 Ireland IE | A | 139 | 26 | dataset-prefix | language |
 Isle of Man IM | B | 21 | 21 | format-only | language |
 Israel IL | B | 707 | 7 | format-only | country |
 Italy IT | A | 2,513 | 107 | dataset | country |
 Jamaica JM | A | 99 | 14 | none | language |
 Japan JP | A | 4,003 | 47 | dataset | country |
 Jersey JE | B | 6 | 5 | format-only | language |
 Jordan JO | B | 143 | 12 | format-only | regional |
 Kazakhstan KZ | B | 350 | 21 | format-only | regional |
 Kenya KE | A | 888 | 47 | dataset | regional |
 Kiribati KI | A | 37 | 2 | none | regional |
 Kosovo XK | B | 77 | 7 | format-only | regional |
 Kuwait KW | B | 21 | 6 | format-only | regional |
 Kyrgyzstan KG | B | 107 | 8 | format-only | regional |
 Laos LA | B | 117 | 18 | format-only | country |
 Latvia LV | A | 2,414 | 43 | dataset | country |
 Lebanon LB | B | 51 | 8 | format-only | regional |
 Lesotho LS | B | 48 | 10 | format-only | regional |
 Liberia LR | B | 27 | 15 | format-only | regional |
 Libya LY | C | 119 | 22 | none | regional |
 Liechtenstein LI | A | 10 | 9 | dataset | regional |
 Lithuania LT | A | 2,399 | 10 | dataset | country |
 Luxembourg LU | A | 2,401 | 12 | dataset | language |
 Macao MO | A | 8 | 2 | none | regional |
 Madagascar MG | B | 152 | 23 | format-only | country |
 Malawi MW | A | 39 | 3 | none | regional |
 Malaysia MY | A | 2,391 | 16 | dataset | country |
 Maldives MV | B | 34 | 19 | format-only | country |
 Mali ML | C | 92 | 11 | none | regional |
 Malta MT | A | 73 | 67 | dataset-prefix | country |
 Marshall Islands MH | A | 2 | 1 | dataset | regional |
 Martinique MQ | B | 23 | 1 | format-only | language |
 Mauritania MR | C | 88 | 15 | none | regional |
 Mauritius MU | B | 116 | 12 | format-only | language |
 Mayotte YT | A | 21 | 18 | dataset | language |
 Mexico MX | A | 3,999 | 32 | dataset | country |
 Micronesia FM | A | 4 | 4 | dataset | regional |
 Moldova MD | A | 1,753 | 48 | dataset | country |
 Monaco MC | A | 29 | 1 | dataset | language |
 Mongolia MN | B | 332 | 22 | format-only | country |
 Montenegro ME | B | 66 | 25 | format-only | regional |
 Montserrat MS | C | 4 | 2 | none | language |
 Morocco MA | A | 1,325 | 12 | dataset | regional |
 Mozambique MZ | B | 94 | 11 | format-only | language |
 Myanmar MM | B | 517 | 15 | format-only | country |
 Namibia NA | B | 91 | 14 | format-only | regional |
 Nauru NR | A | 15 | 14 | none | regional |
 Nepal NP | B | 84 | 7 | format-only | country |
 Netherlands NL | A | 2,698 | 12 | dataset | country |
 New Caledonia NC | A | 52 | 3 | dataset | language |
 New Zealand NZ | A | 1,738 | 16 | dataset | regional |
 Nicaragua NI | B | 169 | 17 | region-prefix | regional |
 Niger NE | B | 74 | 8 | format-only | regional |
 Nigeria NG | B | 927 | 37 | format-only | country |
 Niue NU | C | 1 | 0 | none | regional |
 Norfolk Island NF | A | 1 | 0 | single | regional |
 North Korea KP | B | 127 | 13 | format-only | language |
 North Macedonia MK | A | 220 | 0 | dataset | country |
 Northern Mariana Islands MP | A | 3 | 3 | dataset | language |
 Norway NO | A | 2,399 | 15 | dataset | country |
 Oman OM | B | 39 | 11 | format-only | regional |
 Pakistan PK | A | 2,401 | 7 | dataset | country |
 Palau PW | A | 1 | 0 | dataset | regional |
 Palestine PS | C | 406 | 2 | none | regional |
 Panama PA | A | 760 | 13 | none | regional |
 Papua New Guinea PG | B | 59 | 22 | format-only | regional |
 Paraguay PY | B | 173 | 18 | format-only | language |
 Peru PE | A | 1,106 | 25 | dataset | language |
 Philippines PH | A | 2,109 | 85 | dataset | country |
 Pitcairn PN | A | 1 | 0 | single | language |
 Poland PL | A | 2,402 | 16 | dataset | country |
 Portugal PT | A | 2,399 | 20 | dataset | country |
 Puerto Rico PR | A | 177 | 78 | dataset | regional |
 Qatar QA | C | 22 | 8 | none | regional |
 Republic of the Congo CG | C | 60 | 12 | none | regional |
 Réunion RE | B | 28 | 1 | format-only | language |
 Romania RO | A | 2,399 | 42 | dataset | country |
 Russia RU | A | 2,409 | 78 | dataset | country |
 Rwanda RW | C | 51 | 5 | none | regional |
 Saint Barthélemy BL | B | 1 | 0 | format-only | language |
 Saint Helena, Ascension and Tristan da Cunha SH | A | 6 | 3 | single | language |
 Saint Kitts and Nevis KN | A | 18 | 14 | none | language |
 Saint Lucia LC | C | 34 | 9 | none | language |
 Saint Martin MF | B | 9 | 0 | format-only | language |
 Saint Pierre and Miquelon PM | A | 2 | 2 | dataset | language |
 Saint Vincent and the Grenadines VC | B | 21 | 6 | format-only | language |
 Samoa WS | C | 74 | 11 | none | regional |
 San Marino SM | A | 26 | 0 | dataset | language |
 São Tomé and Príncipe ST | C | 49 | 2 | none | language |
 Saudi Arabia SA | B | 159 | 13 | format-only | regional |
 Senegal SN | B | 152 | 14 | format-only | country |
 Serbia RS | A | 1,155 | 0 | dataset | country |
 Seychelles SC | A | 20 | 17 | none | language |
 Sierra Leone SL | C | 87 | 5 | none | regional |
 Singapore SG | A | 2,400 | 0 | dataset | country |
 Sint Maarten SX | C | 7 | 0 | none | language |
 Slovakia SK | A | 2,400 | 8 | dataset | country |
 Slovenia SI | A | 556 | 0 | dataset | country |
 Solomon Islands SB | C | 13 | 9 | none | regional |
 Somalia SO | B | 76 | 18 | format-only | country |
 South Africa ZA | A | 2,400 | 0 | dataset | country |
 South Georgia and the South Sandwich Islands GS | N | 0 | 0 | — | — |
 South Korea KR | A | 2,402 | 17 | dataset | country |
 South Sudan SS | C | 23 | 10 | none | regional |
 Spain ES | A | 3,607 | 52 | dataset | country |
 Sri Lanka LK | A | 1,837 | 9 | dataset | country |
 Sudan SD | B | 112 | 18 | format-only | regional |
 Suriname SR | A | 24 | 10 | none | language |
 Svalbard and Jan Mayen SJ | A | 8 | 2 | dataset | language |
 Sweden SE | A | 2,415 | 21 | dataset | country |
 Switzerland CH | A | 1,573 | 26 | dataset | country |
 Syria SY | C | 308 | 14 | none | regional |
 Taiwan TW | A | 365 | 22 | dataset | country |
 Tajikistan TJ | B | 103 | 5 | format-only | regional |
 Tanzania TZ | B | 323 | 31 | format-only | regional |
 Thailand TH | A | 903 | 74 | dataset | country |
 Timor-Leste TL | C | 32 | 13 | none | language |
 Togo TG | C | 35 | 5 | none | regional |
 Tokelau TK | C | 3 | 3 | none | regional |
 Tonga TO | C | 47 | 5 | none | regional |
 Trinidad and Tobago TT | C | 27 | 15 | none | language |
 Tunisia TN | B | 282 | 24 | format-only | regional |
 Turkey TR | A | 2,399 | 74 | dataset | country |
 Turkmenistan TM | B | 179 | 6 | format-only | regional |
 Turks and Caicos Islands TC | A | 11 | 0 | single | language |
 Tuvalu TV | A | 7 | 6 | none | regional |
 U.S. Minor Outlying Islands UM | N | 0 | 0 | — | — |
 U.S. Virgin Islands VI | A | 16 | 1 | dataset | language |
 Uganda UG | C | 212 | 4 | none | regional |
 Ukraine UA | A | 2,399 | 20 | dataset | country |
 United Arab Emirates AE | A | 51 | 7 | none | regional |
 United Kingdom GB | A | 4,800 | 4 | dataset | language |
 United States US | A | 6,643 | 52 | dataset | country |
 Uruguay UY | A | 1,962 | 19 | dataset | language |
 Uzbekistan UZ | B | 218 | 14 | format-only | country |
 Vanuatu VU | C | 10 | 6 | none | regional |
 Vatican City VA | A | 1 | 0 | single | language |
 Venezuela VE | B | 412 | 25 | format-only | language |
 Vietnam VN | B | 910 | 34 | format-only | country |
 Wallis and Futuna WF | A | 3 | 3 | dataset | language |
 Western Sahara EH | B | 26 | 0 | format-only | regional |
 Yemen YE | C | 311 | 22 | none | regional |
 Zambia ZM | B | 98 | 10 | format-only | regional |
 Zimbabwe ZW | C | 67 | 10 | none | regional |
Postcode modes: dataset: Every postcode comes from the dataset record of its locality. dataset-prefix: The dataset gives each locality’s postcode prefix; the remaining characters are synthetic. single: A single postcode covers the whole territory. region-prefix: Only the region’s postcode prefix is known. Placeholders keep that prefix but the remaining digits are synthetic. format-only: No open dataset links postcodes to places. Postcodes are left out unless you turn on pattern-valid placeholders. none: Postcodes are not used.
Known limitations
- Street names are synthetic, so address-verification services will usually reject the street line even when the postcode and town are real.
- Each country file holds a sample of up to about 2,400 places, so not every village appears.
- GeoNames postal data is partial in some countries: Brazil (municipality-level CEPs), Chile (commune-level), China (district codes from Google’s examples), Argentina (four-digit codes without the CPA letters), Ireland and Malta (prefixes only).
- UK localities are those recorded with each postcode. Royal Mail’s post town can differ.
- Google’s Chinese metadata predates some district mergers (for example, Shanghai’s Zhabei district merged into Jing’an in 2015).
- Regional name lists are approximations. Each country page says how specific its list is.
- Local-script names are partial in a few countries (for example, some Thai localities appear only in Latin script); country pages report the share.