Current geographic source
The current release uses the United States, Australia, Canada, Germany and Kenya files from the GeoNames postal-code export. The build pipelines download US.zip, AU.zip, CA.zip, DE.zip and KE.zip. The US dataset keeps the 50 states, the Australia dataset keeps all 8 states and territories, and the Germany dataset keeps all 16 federal states. Canada and Kenya are published with explicit limited GeoNames coverage.
France uses the La Poste HexaSmal dataset for postcodes, routing labels and optional line 5 values. Those rows are joined to the INSEE Code officiel géographique 2026 for communes, departments and regions.
Additional country datasets
Mexico, United Kingdom, Netherlands, Italy, Spain, Poland, Ukraine, Portugal, Japan, China, South Korea, India, Singapore, Indonesia, Thailand, Brazil, Argentina, Colombia, Chile, Peru and South Africa use the standard GeoNames postal exports. Files are split into source regions or explicit postal-prefix groups, so a browser loads only the selected group. Country manifests record source URLs, download times, exclusions and actual retained counts.
The UK and Netherlands source provides postcode prefixes; Argentina provides a province letter and four-digit locality code. China and Chile provide partial postal values. Completed codes for those five countries have synthetic suffixes. Brazil retains the source's major-area CEP values ending in -000, not a street-level CEP directory.
Philippines, Saudi Arabia, Nigeria and Egypt use the GeoNames cities5000 populated-place extract with admin1CodesASCII region names. Postal codes are intentionally omitted: these are incomplete city-only test addresses. Bolivia and UAE use the same geographic source with test layouts that do not add a postcode. UAE box tokens explicitly include TEST, SAMPLE or DEMO and are not assigned mailboxes.
The populated-place source includes selected larger places and administrative seats, not every settlement. Its field definitions and reuse terms differ from the postal export. No city/postcode relationship is inferred from coordinates.
Country-specific exclusions
Singapore's six-digit postcodes can identify individual buildings. Its source place field is a road name, not a city. The build removes road names and coordinates, retains unique source postcodes, and groups them by the first two postal digits under Singapore country context. The synthetic street and number are not matched to those postcodes; no SingPost delivery verification is claimed.
Italy excludes Sardinia, Casciana Terme and Collarmele while source province/CAP changes remain unresolved. Spain requires a source municipality code whose province prefix agrees with the postcode. Poland excludes Szczawa and Grabowka records with known administrative review issues; other records are not claimed to be freshly matched to TERYT. Colombia excludes retired Mapiripana municipality-code rows and does not invent the missing new municipality relationships. China excludes conflicting province names under source code 20.
Indonesia and South Africa lack usable province names in these postal exports. Their selectors group by the first two postal digits, not guessed provinces. Mexico keeps the source colonia/locality separate from its municipality; Japan keeps the postal locality separate from its source municipality/district and prefecture. Source labels can be historical or describe postal places rather than municipal cities. No remaining dataset is certified as a current national administrative or street-delivery directory.
Fields and cleaning
The US browser dataset contains city, state, two-letter state code, five-digit ZIP code and county. The Australia dataset contains locality, state or territory, official abbreviation and four-digit postcode. Canada retains source municipality, province and three-character FSA relationships for 10 provinces; its final three postal-code characters are generated and unverified. The Germany dataset contains city, federal state, state code and five-digit postcode. The Kenya browser rows contain only a GeoNames place and five-digit postcode plus an internal country-scope value. Incomplete records and exact duplicates are removed, whitespace is normalized, and coordinates and unused source fields are omitted.
The France browser file uses a compact row format to avoid repeating region and department names 38,925 times. It expands locally into a postcode, delivery locality, optional line 5, commune, department and region record. Source hashes and exact row counts are checked before the file is replaced.
A result selects one complete source row, so related geographic fields are not mixed independently. ZIP codes and postcodes stay as strings so leading zeroes are preserved.
Canada-specific boundary
The Canada build keeps only GeoNames rows with an explicit source municipality. It covers all 10 provinces but excludes the three territories and other rows where the free source provides only a broad FSA-area description. Those rows are not converted into guessed municipality names.
GeoNames supplies the three-character Forward Sortation Area, not Canada Post's complete six-character Postal Code Address Data. The generator adds a synthetic ANA NAN-compatible Local Delivery Unit segment for form testing and labels the completed postal code as unverified.
Kenya-specific boundary
The Kenya build retains 890 GeoNames place/postcode rows and 877 unique postcodes. It is not copied from Posta Kenya and is not presented as an official or complete postal directory. GeoNames source county labels are omitted from the browser rows because current validation found known county conflicts and no independently verified national relationship table suitable for redistribution.
The generated first line uses P O BOX TEST-0000-style tokens. The letters make the box deliberately non-deliverable because no official reserved numeric test-box range was found. A user must not treat the result as an assigned P.O. Box.
Germany-specific filtering
The GeoNames Germany file also contains company, institution and bulk-recipient records that use numeric first-level administrative codes. The browser dataset keeps only the 16 reviewed two-letter German state codes and excludes records without a German state, including the Austrian locality Jungholz. Representative postcode and city pairs were checked against the public Deutsche Post postcode search before the country page was enabled.
France-specific boundary
France retains 38,925 HexaSmal rows covering 6,187 unique postcodes, 18 regions and 101 departments in the 2026 COG. This includes metropolitan France and Guadeloupe, Martinique, Guyane, La Réunion and Mayotte. The build excludes 267 rows for overseas collectivities and Monaco because they do not resolve into this region/department model.
This is not a street directory. The route type, test phrase and house number are synthetic. CEDEX, BP, organization-recipient data and postal validation are outside the current release.
Synthetic street data
House numbers and street lines are generated for testing and are not selected from a resident-address directory.
A generated combination may coincidentally resemble an existing location. The finished result is not represented as nonexistent, verified by a postal authority or deliverable.
Limitations
US ZIP geography can cross county boundaries. The displayed county belongs to the selected GeoNames place row and is not a legal, property, tax, emergency or USPS-grade boundary decision. Australian locality and postcode records are not the licensed Australia Post commercial address database. German rows are not the licensed Deutsche Post address directory. Canadian rows do not include Canada Post's full postal codes or the territories. Kenya rows are not the Posta Kenya branch directory and do not establish county or deliverability. French routing rows do not provide real street addresses and do not cover CEDEX or every overseas territory. Source data is provided as-is and may be incomplete or outdated.
License and attribution
Geographic data includes GeoNames data under the Creative Commons Attribution 4.0 International license. See the GeoNames postal-code readme for source field definitions.
La Poste HexaSmal and INSEE COG data are reused under France's Licence Ouverte / Open Licence 2.0. The France build records the source URLs, timestamps and SHA-256 hashes in the packaged metadata file.