Skip to content

Releases

v5.2.0-export.1

Choose a tag to compare

@github-actions github-actions released this 03 Nov 08:18
Immutable release. Only release title and notes can be modified.
9b255c4

v5.2.0-export.1 - November 03, 2026

Data export build for v5.2.0.

Data Statistics

  • Regions: 6
  • Subregions: 22
  • Countries: 250
  • States: 5327
  • Counties: 14058
  • Cities: 156169
  • Postcodes: 728556

Formats

JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet

Licence and credits

ODbL 1.0, attribution required. Some values come from sources that ask for credit (see the README). Their
notices are attached as NOTICE-*.txt and must be kept with every copy of this data.

Migration files

Each migrations-from-<release>.tar.gz says how ids changed since that release: removals and where they went,
added ids, identity decisions and changed fields. See migrations/README.md.


Auto-generated by GitHub Actions export workflow

v5.2.0

Choose a tag to compare

@dr5hn dr5hn released this 02 Nov 09:54
Immutable release. Only release title and notes can be modified.
e39d710

Countries States Cities Database v5.2.0

Counts describe source commit 29dd43bb, compared with
v5.1.0.

What this release changes

v5.2.0 is a regular release. It adds missing places and corrects existing ones; it removes nothing and changes no id.
Every id in v5.1.0 means the same entity in v5.2.0. See the
data versioning contract.

Table Rows changed Rows added Rows removed
Cities 8,183 3,791 0
Postcodes 0 2,563 0
States, counties, countries 0 0 0

Changed city fields:

Field Cities
parent_id 8,089
level 100
type and type_local 90
name and Latin-script translations 3
wikiDataId 1

New rows

Country Added What they are Source
Mexico 1,732 cities municipios and alcaldías, with their 2020 census total INEGI
Poland 1,372 cities rural and urban-rural gminy, with their 30 June 2026 total GUS
Nigeria 591 cities local government areas and FCT area councils OCHA COD-AB (CC BY-IGO 3.0), via Open Admin Data
Cuba 63 cities municipios; no populations, as ONEI's terms allow only non-commercial reuse ONEI list, Wikidata points
Pakistan 33 cities, 2,563 postcodes towns and villages, 27 of them in Gilgit-Baltistan; GeoNames postcodes Wikidata, GeoNames (CC BY 4.0)

Pakistan's and Nigeria's rows were contributed by shaxzad and Christiano112.
59.1% of cities now carry a population year, up from 58.6% in v5.1.0.

Municipality rows

A municipio, gmina or local government area is a city row of type municipality (level 2, or level 3 for a gmina, under
its powiat), and its
towns link to it through parent_id (8,089 links in this release: Mexico 6,581, Poland 1,498, Cuba 10). A municipality
can share its town's name (the gmina Krobia and the town of Krobia), and its population includes its towns'.

  • To list only settlements, leave out type municipality (in Poland also adm2 and adm3).
  • To avoid double counting, don't add a municipality's population to its towns'.

TYPE_FIELD.md gains sections for Mexico, Poland and Cuba.

Other corrections

  • Cuba: 90 existing municipio rows are typed municipality, including the 33 "Municipio de ..." rows and San Germán,
    which is the Urbano Noris municipio. San Luis in Pinar del Río loses the Wikidata item of San Luis in Santiago de Cuba.
  • Pakistan: Bhimber, Rawalakot and Vehari get their standard spelling.

Every change is traced, record by record, in the ledgers under
.github/fixes-docs/ledgers/, and each source is credited in
.github/licenses/SOURCES.txt.

v5.1.0-export.1

Choose a tag to compare

@github-actions github-actions released this 02 Nov 07:55
Immutable release. Only release title and notes can be modified.
925204e

v5.1.0-export.1 - November 02, 2026

Data export build for v5.1.0.

Data Statistics

  • Regions: 6
  • Subregions: 22
  • Countries: 250
  • States: 5327
  • Counties: 14058
  • Cities: 152378
  • Postcodes: 725993

Formats

JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet

Licence and credits

ODbL 1.0, attribution required. Some values come from sources that ask for credit (see the README). Their
notices are attached as NOTICE-*.txt and must be kept with every copy of this data.

Migration files

Each migrations-from-<release>.tar.gz says how ids changed since that release: removals and where they went,
added ids, identity decisions and changed fields. See migrations/README.md.


Auto-generated by GitHub Actions export workflow

v5.1.0

Choose a tag to compare

@dr5hn dr5hn released this 31 Oct 13:23
Immutable release. Only release title and notes can be modified.
41f30ae

Countries States Cities Database v5.1.0

Counts describe source commit 465beaae,
compared with v5.0.0.

What this release changes

v5.1.0 is a regular release. It corrects facts about existing records and adds nothing, removes nothing and changes no
id. Every id in v5.0.0 means the same entity in v5.1.0, so you can update stored rows by id. See the
data versioning contract.

Table Rows changed Rows added Rows removed
Cities 33,473 0 0
States 135 0 0
Countries 1 0 0
Counties, postcodes 0 0 0

Changed city fields:

Field Cities
population_year set 25,756
population corrected or added 17,659
level 4,679
type 3,315
type_local 2,714
timezone 2,374
wikiDataId added, replaced or cleared 1,498
county_id 723
parent_id 99
latitude and longitude 59
translations 5

States: 135 get their level and 40 their parent_id (the Dominican Republic's provinces under their regions,
Equatorial Guinea's under its two regions).

Populations

Since v5.0.0 every population we add or correct comes from the national statistics office, carries its reference
year in population_year, and is bound to the place the row denotes: a town no longer carries its district's or
municipality's total, and a district no longer carries its main town's. 58.6% of cities now carry a population year,
up from 42.4% in v5.0.0.

Country Source and reference date
United States Census Bureau, 2020 Census
United Kingdom ONS 2021 (built-up areas and civil parishes), NRS 2022, NISRA 2021 censuses
Canada Statistics Canada, 2021 Census
Australia ABS, 2021 Census
New Zealand Stats NZ, estimates at 30 June 2025
Mexico INEGI, 2020 Census
Guatemala INE, 2018 Census
Uruguay INE, 2023 Census
Philippines PSA, 2024 Census of Population
Taiwan Ministry of the Interior, household registration, September 2026
Japan e-Stat, 2020 Census
Israel CBS, preliminary estimates at the end of August 2026
India 2011 Census, year added only where the stored count matched
Russia Rosstat open data, 2015, for cities that had no population; for 680 others, the year of the Wikidata statement that gives exactly the stored count
Ukraine State Statistics Service, 1 January 2022
Kazakhstan Bureau of National Statistics, 1 July 2026
Georgia Geostat, 1 January 2026
Moldova National Bureau of Statistics, 2024 Census
Morocco HCP, legal population of communes, 2024 Census
Malaysia OpenDOSM, district estimates for 2026
Poland GUS, 30 June 2026 for towns and gminy; 2021 Census for villages
Austria, Belgium, Czechia, Germany, Hungary, Iceland, Latvia, Luxembourg, Norway, Slovakia, Slovenia, Spain, Sweden their national statistics offices, 2025 or 2026 figures
Croatia, Ireland, Italy (localities), Portugal, Serbia their 2021 or 2022 censuses
Italy (comuni) ISTAT, 1 January 2026

Each source, its licence and the exact reuse clause are credited in
.github/licenses/SOURCES.txt.

Types and levels

level is the depth in each country's official hierarchy, with the same meaning in states, counties and cities.
China's city rows now follow it for 2,019 rows (prefectures at 2, county-level units at 3), and 968 Philippine cities
and municipalities get their level and type from their PSGC code. Types follow
TYPE_FIELD.md, which gains
sections for the United States, Uruguay, Germany, Canada, Ukraine, Australia, Portugal and China. In Guangdong, 99
districts, counties and townships get their parent unit as parent_id, and 5 rows their Chinese name, checked against
the Ministry of Civil Affairs place-names register (contributed in #2108).

Time zones

2,374 cities take the IANA zone that contains their own point (timezone-boundary-builder 2026e, ODbL), for example
Brazil's north-east off São Paulo time, Puerto Rico's towns on Atlantic time, Western Australian shires on Perth time
and Russian Far East towns off Moscow time. Every country keeps its own zone name: Dutch cities stay
Europe/Amsterdam even though tzdata now links it to Europe/Brussels.

Manitoba stays on UTC−5 all year from 31 October 2026 (tzdata 2026e), so Canada's America/Winnipeg and
America/Rainy_River entries in countries.json now give UTC−05:00 (EST) as their standard offset.

Wikidata items

Items are added where a row's own official code or own GeoNames feature proves its item, and cleared where an item
belonged to another place (for example a district carrying its town's item). Items shared by two city rows were
reviewed: wrong ones are cleared, and pairs that are the same place stored twice are listed for the next major.

What stays the same

No ids, names, countries, states or postcodes change meaning. Rows in disputed or special territories were left as
they were, with one exception: Sevastopol's row takes the category Ukraine's KATOTTH codifier gives it, a city with special
status, like Kyiv. Every change is traced, record by record, in the ledgers under
.github/fixes-docs/ledgers/.

v5.0.0-export.1

Choose a tag to compare

@github-actions github-actions released this 19 Oct 12:48
4a3485f

v5.0.0-export.1 - October 19, 2026

Data export build for v5.0.0.

Data Statistics

  • Regions: 6
  • Subregions: 22
  • Countries: 250
  • States: 5327
  • Counties: 14058
  • Cities: 152378
  • Postcodes: 725993

Formats

JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet

Licence and credits

ODbL 1.0, attribution required. Some values come from sources that ask for credit (see the README). Their
notices are attached as NOTICE-*.txt and must be kept with every copy of this data.

Migration files

Each migrations-from-<release>.tar.gz says how ids changed since that release: removals and where they went,
added ids, identity decisions and changed fields. See migrations/README.md.


Auto-generated by GitHub Actions export workflow

v5.0.0

Choose a tag to compare

@dr5hn dr5hn released this 19 Oct 12:18
4a3485f

Countries States Cities Database v5.0.0

Counts describe source commit
d8a54626622012ee9f520108fddfdd8d11f29ae8,
compared with the v4.0 snapshot.

What this release changes

v5 is the corrective major after v4. It repairs ids that disappeared during the v4 export series,
separates administrative territories from the places that serve as their seats, and replaces
postcode values whose source support was missing. It also introduces cities without a state and
counties that belong to several regions.

This is a major because it removes keys, repairs ids that had come to denote another entity,
and changes the schema and documented settlement filters. From v5 onward, an id identifies one
geographic entity within its table. Regular releases can correct its facts and add records;
removals and incompatible contract changes wait for a major. Retired ids cannot be assigned to
another entity. A reviewed restoration of the same entity is allowed.
See the data versioning contract.

Breaking changes

Removed and repaired ids

Keys present in v4.0 but absent from this candidate:

Table Removed ids Main reasons
Countries 0 No country id retired in this comparison.
States 8 Achaea moved to counties; seven states retired by the four reforms below.
Counties 9 Connecticut's 8 historical counties, with no successor; Alaska's Valdez-Cordova, split in two.
Cities 3,485 Administrative units moved to other tables, unit/seat distinctions, reviewed duplicates, no proved successors, and identity repairs.
Postcodes 133,243 Unsupported source or locality scope, replaced code namespaces, and reviewed duplicate removal.

These are endpoint counts, not a count of all historical removal events. The migration manifest
also reports events and restorations. Use the individual reviewed reason, rather than assuming
that a retired row represents a place or postal code that disappeared in the real world.

1,353 city ids that had come to denote a different entity are retired, with fresh ids for
the later entity. An administrative district and its seat town are distinct entities even when
their names match. Do not replace every retired unit id with its seat's id. The migration files
separately describe the original entity and the later entity.

Cities without a state

state_id and state_code may both be null for a city in a country with no states. Accept the
null pair in storage, response models and filters. A mandatory join through states would lose
these cities. In nested country exports, read the country-level cities array as well as cities
inside states; MongoDB omits a state reference for such a city.

Western Sahara has 3 such cities in contributions/cities/EH.json: Gueltat Zemmour, Imlili
and Smara. Their city ids stay the same when they move from MA to EH. They do not acquire a
Moroccan state or a fabricated EH state.
See the nullable-state change
and the territory data changes.

Counties in several regions

7 New Zealand councils now have 16 county-region links. A county either has its
usual state pair, or has both fields null and a states list of {state_id, state_code} pairs.
A linked city still has its own state, which must be one of the county's regions.

Relational exports use county_states (county_id, state_id). CSV and PLIST supply a separate
county-state relation file; Parquet and TOON encode the list as JSON text. Update consumers
that assume a county always has one state. See the format and schema changes.

Schema and SQL imports

Apply the nullable city-state and county-region schema upgrades before loading into an existing
database, or rebuild using the schema supplied with this snapshot. SQL INSERT statements now
name their columns. Importers that parse positional INSERTs must accept column lists; a custom
schema must still provide the named columns and compatible types.
See the database upgrade instructions
and the dump change.

Migrating ids you have stored

Pin the exact data snapshot you use. An API protocol version or npm/PyPI package version alone
is not a data snapshot. The owner will confirm API and package rollout dates separately; this
page does not mean those products have already switched.

The first v5 export's builder supplies migrations-from-v4.0.tar.gz, with
MIGRATIONS_SHA256SUMS and MIGRATIONS_SOURCE. Verify the archive checksum and source commit.
Inside, release_manifest.json identifies from.sha, to.sha, release versions, per-table
counts and file checksums. The candidate uses migration format 3.

Use removed_ids.jsonl (or its CSV view) to look up (old_table, old_id), not an id alone.
Check present_at_from, present_at_to and restored_at: the file is a history of removals,
and a key that was later restored and is present at the target is not currently retired.
current_targets follows relations to the end of the interval. Multiple targets need a choice;
empty targets or a terminal no-successor outcome supply no replacement.

Read identity_changes.jsonl too. For a repaired id, current_targets refers to what the id
originally denoted; later_entity_targets refers to what it later came to denote. Match the
meaning in your stored record. A prior entity marked ended or unrecorded can have no target.
Neither identity repair nor territorial succession, split, dataset move or seat relationship
permits an automatic redirect.

Only a current_targets entry whose automatic_redirect is true can be applied automatically:
every step must be a reviewed merge of the same entity. For example, the reviewed duplicate
postcode 85289 → 85290 keeps the existing Larnaka record; the
postcode change records that merge.
A guarded lookup looks like this:

import json
for line in open('removed_ids.jsonl', encoding='utf-8'):
    event = json.loads(line)
    if (event['old_table'], event['old_id']) != ('postcodes', 85289):
        continue
    if event['present_at_to']:
        continue  # not retired at the target snapshot
    for target in event['current_targets']:
        if target['automatic_redirect']:
            print(target['table'], target['id'])  # postcodes 85290

Back up your mappings, apply reviewed choices to your own references, and check that every
resulting (table, id) exists in the pinned v5 snapshot. Keep unresolved cases for manual review.
added_ids.jsonl lists additions; changed_fields.jsonl gives typed before/after values and
presence flags for retained keys.

If you use a later v4 export, load v5 data fresh and use the cumulative history to map the ids
you stored. Do not patch that export with the cumulative added/changed files: those are relative
to v4.0, and some ids in later exports did not exist at that baseline. The current builder does
not supply an export.51 delta. Subsequent v5 exports supply a step from the previous published
v5 snapshot; apply matching steps in order.
See the migration files and archive rules.

Unresolved records and strict use

This candidate retains 12,140 keys whose latest identity decision is unresolved.
The data does not yet prove whether each legacy row originally denoted a settlement or a
territory. Independently proved facts can remain, while unproved category, hierarchy or item
changes are withheld. An unresolved row never redirects automatically.

Start with the cumulative identity_changes.jsonl, including its baseline: true entries.
Keep the latest decision for each (table, id) in file order; apply later releases' decisions
and reviewed removals. Strict territorial users exclude retained keys whose latest outcome is
unresolved. Absence from a later file does not resolve a key. A settlement type filter alone
is not a substitute for this exclusion. Disclosure of an unresolved key does not approve
a pending name or territorial change; outstanding publication holds still need a decision.

Data changes to check before switching

Postcode coverage

Removed postcode ids since v4.0 include Malta 25,813, China 19,255, Myanmar 17,331,
Paraguay 8,644, Tunisia 4,860, Nigeria 3,728, Tanzania 3,684,
Argentina 10,628, South Africa 4,953, Ukraine 4,422, and Spain 8,124.
The full country/outcome breakdown is in appendix_postcode_removals_by_country.csv.

A replacement product must support the entity the id denoted: sometimes a code alone,
sometimes a code plus locality, district or delivery kind. Malta's locality prefixes and China's
general codes cannot silently replace finer delivery codes. Some rows retire even though their
code occurs in the replacement product. A removal for missing source support is not a finding
that mail cannot be delivered there. Supported values were re-derived; unsupported points,
localities and links may be null. Spanish municipality codes used as postal ids were replaced
with actual postal-code coverage rather than redirected by number.

After those removals, 4,137 postcodes were added for 24 countries left with little or no coverage, fr...

Read more

v4.0-export.51

Choose a tag to compare

@github-actions github-actions released this 12 Oct 23:10
bed35e9

v4.0-export.51 - October 12, 2026

Data export build for v4.0.

Data Statistics

  • Regions: 6
  • Subregions: 22
  • Countries: 250
  • States: 5328
  • Counties: 12306
  • Cities: 152021
  • Postcodes: 846973

Formats

JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet


Auto-generated by GitHub Actions export workflow

v4.0-export.50

Choose a tag to compare

@github-actions github-actions released this 12 Oct 08:07
f3946e4

v4.0-export.50 - October 12, 2026

Data export build for v4.0.

Data Statistics

  • Regions: 6
  • Subregions: 22
  • Countries: 250
  • States: 5328
  • Counties: 10639
  • Cities: 152152
  • Postcodes: 844248

Formats

JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet


Auto-generated by GitHub Actions export workflow

v4.0-export.49

Choose a tag to compare

@github-actions github-actions released this 11 Oct 21:32
90e7482

v4.0-export.49 - October 11, 2026

Data export build for v4.0.

Data Statistics

  • Regions: 6
  • Subregions: 22
  • Countries: 250
  • States: 5328
  • Counties: 10636
  • Cities: 152330
  • Postcodes: 844248

Formats

JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet


Auto-generated by GitHub Actions export workflow

v4.0-export.48

Choose a tag to compare

@github-actions github-actions released this 11 Oct 12:06
4912597

v4.0-export.48 - October 11, 2026

Data export build for v4.0.

Data Statistics

  • Regions: 6
  • Subregions: 22
  • Countries: 250
  • States: 5328
  • Counties: 10635
  • Cities: 152571
  • Postcodes: 844248

Formats

JSON, MySQL, PostgreSQL, SQLite, SQL Server, XML, YAML, CSV, GeoJSON, Toon, MongoDB, Parquet


Auto-generated by GitHub Actions export workflow