Builds the place-name data package that the DBCode map downloads once, so it can place rows by city, postcode or state.
- GeoNames:
cities500.zip,allCountries.zip(postal codes),admin1CodesASCII.txt,alternateNamesV2.zipandcountryInfo.txt. Licensed under CC BY 4.0. The build always takes the current files, which GeoNames updates daily. - Natural Earth admin-1 states and provinces, 10m, from
nvkelso/natural-earth-vectorv5.1.2, pinned to its commit. Public domain.
Anything that shows this data must credit GeoNames. ATTRIBUTION.txt ships in every archive and says how the data was changed.
Needs Node 24, unzip, tar and gzip. There are no npm dependencies.
node scripts/build.ts 2026.11This writes dist/geodata-2026.11.tar.gz and prints its SRI hash last. Downloads stay in downloads/: delete that folder for fresh data. The build stops on a malformed row or when a source has far fewer rows than expected, so a bad download never reaches a release.
To publish, run the Release workflow with a version. It builds, creates a release of that name with the archive attached, and prints the SRI in the job log and the release notes. Take the hash from there: GeoNames changes daily, so a local build has a different one.
geodata-<version>.tar.gz, with these files at its root. All text is UTF-8. The .tsv files are tab-separated with no header row and no quoting.
| File | Contents |
|---|---|
manifest.json |
{ version, countries, postcodePrefix } |
cities/<CC>.tsv |
name, ascii, admin1, population, lat, lng, local |
postcodes/<CC>.tsv |
code, place, admin1, lat, lng |
admin1/<CC>.json |
GeoJSON FeatureCollection of simplified shapes, with the property code |
admin1/names.tsv |
code, name, ascii, local, for every country |
ATTRIBUTION.txt |
Sources and licences |
<CC> is the ISO 3166-1 alpha-2 country code. countries lists every country with at least one file, and a country does not always have all three: many have cities but no postcodes. Population is as GeoNames gives it, including 0.
name is often the English form: Munich, Bavaria. local holds the place's other names in its country's own languages, separated by |, and is empty when there are none: München for Munich, Bayern for Bavaria.
The languages are those GeoNames lists for the country. Names it flags as historic or colloquial are left out, and so is any name that equals name, ascii or an earlier local name once case and accents are ignored. A name holding a | is left out too, so the columns can never shift.
admin1 in the cities and postcodes, code in names.tsv and code in the shapes are all the same CC-XX value, so a city, its state's name and its state's shape join on it. It is blank where the source gives no state.
To resolve a state as typed, compare it with name, ascii and each local name in names.tsv and with the part of code after CC-, within the country. Illinois and IL both give US-IL, and Bayern gives DE-BY.
XXis the ISO 3166-2 code where Natural Earth has that exact region:US-CA,AU-NSW.- Otherwise it is the GeoNames code:
FR-11,GB-ENG. That covers countries whose Natural Earth shapes are finer than GeoNames regions, and countries where the ISO codes would repeat.
Not every code has a shape, and a few have no name. Where Natural Earth's shapes are finer than a region they are merged into one MultiPolygon, so the old inner borders remain. Where they are coarser, as in Kenya, the regions have no shapes.
A code can have several rows, one per place: AU 2000 has nine. The code is as GeoNames gives it, spaces and hyphens included, except that a country with a number in postcodePrefix has its codes cut to that length.
postcodePrefix names the countries where a code is reduced before it is looked up, and says how. That is every country whose free data holds the leading characters of the full code, plus the US, so that ZIP+4 places on the ZIP. Other countries with partial data, such as CL, CN, BR and AR, hold codes that a leading-characters rule cannot reach. A country it does not name is matched exactly.
- A number is how many leading characters to keep, once spaces are removed:
CA: 3looks upK1A 0B1asK1A. 'outward'is for GB, GG, IM and JE, whose outward codes run from 2 to 4 characters: drop the last three characters of a full code, soSE1 7PBis looked up asSE1.
The code in this repo is under the MIT licence: see LICENSE. That covers the code only. The data keeps its own licences: CC BY 4.0 for GeoNames, public domain for Natural Earth.