v3.2-export.2

v3.2-export.2 - April 28, 2026

Data export build for v3.2.

Data Statistics

• Regions: 6
• Subregions: 22
• Countries: 250
• States: 5308
• Cities: 154223
• Postcodes: 660381

Formats

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

---

Auto-generated by GitHub Actions export workflow

v3.2 — France data corrections + state leveling + postcodes batch

Major data-correction release. Behaviour changes for FR/IT consumers — see CHANGELOG callouts.

Highlights

France — mainland city remap (region → department)

• 8,727 cities re-parented from 13 ISO-3166-2:FR regions to their correct INSEE department (#1352 PR-E, #1484). The FR equivalent of the IT region→province remap shipped earlier this month.
• +455 missing metropolitan communes added from data.gouv.fr (Cherbourg-en-Cotentin, Évry-Courcouronnes, Saint-Ouen-sur-Seine, Oullins-Pierre-Bénite, Herblay-sur-Seine, …) automatically remapped to the correct department (#1352 PR-A, #1394).
• FR state metadata polish: corrupted native field values restored (Ain, Aude, Eure, …) (#1352 PR-B, #1393).

Consumer-visible behaviour change: querying cities by region state_code (ARA, IDF, NOR, PDL, NAQ, BRE, OCC, GES, CVL, BFC, HDF, PAC, 20R) now returns []. Use the department state_code (03, 13, 2A, 2B, 75C, …) instead, or traverse the parent_id hierarchy.

France — overseas territories

• 9 new state records + 31 city files for GF (Guyane), BL (Saint-Barthélemy), MF (Saint-Martin), PM (Saint-Pierre-et-Miquelon), TF (TAAF) (#1352 PR-D, #1400).
• Documented dual-representation policy in MULTI_LEVEL_TERRITORIES.md (#1352 PR-C, #1392).

Italy — completes the #1349 cleanup

• Dropped 88 placeholder "Provincia di X" pseudo-cities (#1349, #1482).
• Merged the 2 ISTAT-canonical comune dedup pairs that were intentionally deferred from #1399: Sermide e Felonica (MN), Corteolona e Genzone (PV) (#1349, #1481).

State leveling normalised (FR + IT)

• All FR + IT state rows now carry consistent level values: level=1 = region, level=2 = department / province / metropolitan city / equivalent (#1489). Downstream consumers can now filter by level reliably.

Postcodes infrastructure (#1039)

• Bulk imports for KH (1,640), VE (1,187), MG (111), MZ (161), MU (1,874), MT (26,593), BN (547), HU (3,569), CN (22,656), MM (17,331), LU (4,491) — completing roughly 50 country postcode datasets total.
• Export pipeline updated to gzip postcode export files and route them to GitHub Releases instead of git commits (#1490).

Data statistics (post-release)

To be populated by the export pipeline running off this tag.

Migration notes for downstream tools

• csc-export-tool / countrystatecity SDKs: nothing to change. APIs use state_code and state_id; both remain valid. Consumers who hardcoded region codes for FR or IT will get empty arrays and should migrate to department / province codes. Hierarchical traversal via parent_id continues to work.
• Direct DB consumers: see CHANGELOG callouts for FR and IT region→department/province remaps.

Full changelog

See CHANGELOG.md.

Refs: #1039, #1349, #1352

v3.2-export.1

v0.0-export.1 - April 27, 2026

Data export build for v0.0.

Data Statistics

• Regions: 6
• Subregions: 22
• Countries: 250
• States: 5308
• Cities: 154223
• Postcodes: 660381

Formats

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

---

Auto-generated by GitHub Actions export workflow

v3.1-export.4

v3.1-export.4 - April 27, 2026

Data export build for v3.1.

Data Statistics

• Regions: 6
• Subregions: 22
• Countries: 250
• States: 5308
• Cities: 153768
• Postcodes: 629118

Formats

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

---

Auto-generated by GitHub Actions export workflow

v3.1-export.3

v3.1-export.3 - April 25, 2026

Data export build for v3.1.

Data Statistics

• Regions: 6
• Subregions: 22
• Countries: 250
• States: 5299
• Cities: 153832
• Postcodes: 0

Formats

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

---

Auto-generated by GitHub Actions export workflow

v3.1-export.2

v3.1-export.2 - March 28, 2026

Data export build for v3.1.

Data Statistics

• Regions: 6
• Subregions: 22
• Countries: 250
• States: 5296
• Cities: 153823

Formats

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

---

Auto-generated by GitHub Actions export workflow

v3.1-export.1

v3.1-export.1 - March 28, 2026

Data export build for v3.1.

Data Statistics

• Regions: 6
• Subregions: 22
• Countries: 250
• States: 5296
• Cities: 153732

Formats

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

---

Auto-generated by GitHub Actions export workflow

v3.1

Changelog — v3.1

🌍 New Data Added

• Add missing cities for Saudi Arabia, Japan, fix data quality issues and remove duplicates
• Add population and GDP column in countries and native data
• Add population in cities table
• Add timezone support for all cities using geographic coordinates
• Add translations.csv export for country, region, and subregion name translations
• Add DuckDB import script and GitHub Actions integration for database format conversion
• Add MCP Server Integration for GitHub Copilot Agents
• Add Claude Code GitHub Workflow
• Add toon & geojson script

Countries & Regions

• Afghanistan — Add missing Wardak province and cities
• Angola — Add missing Namibe province and cities with translations (ISO 3166-2:AO)
• Azerbaijan — Add 3 missing municipalities with Wikipedia-sourced translations (ISO 3166-2:AZ)
• Bahamas — Align districts with ISO 3166-2:BS (42→32 states)
• Bangladesh — Add 64 districts with multilingual support and reassign cities (ISO 3166-2:BD)
• Botswana — Fix missing districts, towns and cities
• Cabo Verde — Add missing São Salvador do Mundo municipality (CV-SS)
• Cambodia — Add missing Tboung Khmum province (ISO 3166-2:KH)
• Côte d'Ivoire — Restructure administrative divisions per ISO 3166-2:CI
• Dominican Republic — Add missing province and 10 regions per ISO 3166-2:DO
• Equatorial Guinea — Add missing Djibloho province (GQ-DJ)
• Estonia — Add municipalities and update county ISO codes per ISO 3166-2:EE
• Ethiopia — Add missing Sidama (ET-SI) and Southwest Ethiopia Peoples (ET-SW) states; reassign 12 cities
• France — Add missing Nouvelle-Calédonie (New Caledonia) overseas collectivity
• Guinea-Bissau — Add missing Bissau autonomous sector (GW-BS)
• Iceland — Add 64 missing municipalities per ISO 3166-2:IS
• Indonesia — Add 7 missing geographical units per ISO 3166-2:ID
• Iraq — Add missing Kurdistan Region (IQ-KR) per ISO 3166-2:IQ
• Italy — Add 15 missing administrative divisions per ISO 3166-2:IT
• Libya — Add missing Al Butnan province and cities per ISO 3166-2:LY
• Lithuania — Add 7 city municipalities per ISO 3166-2:LT
• Maldives — Fix administrative divisions per ISO 3166-2:MV
• Malta — Add missing Safi local council (MT-47)
• Marshall Islands — Add 24 municipalities per ISO 3166-2:MH
• Moldova — Add missing Leova district (ISO 3166-2:MD)
• Monaco — Add 14 missing quarters per ISO 3166-2:MC with translations
• Montenegro — Add missing municipalities
• Niger — Add missing Niamey urban community (NE-8)
• North Korea — Add missing metropolitan cities (Nampho, Kaesong)
• North Macedonia — Update municipality data
• Oman — Fix governorate structure per ISO 3166-2:OM
• Pakistan — Remove deprecated FATA state, merge cities into Khyber Pakhtunkhwa (ISO 3166-2:PK)
• Panama — Add missing Naso Tjër Di indigenous region (PA-NT)
• Paraguay — Add 4 cities to Central department and fix Asuncion
• Peru — Add missing PE-LMA (Municipalidad Metropolitana de Lima)
• São Tomé and Príncipe — Fix administrative divisions per ISO 3166-2:ST
• Serbia — Add missing administrative divisions per ISO 3166-2:RS
• Seychelles — Add 3 missing districts per ISO 3166-2:SC
• Sierra Leone — Add missing province and cities
• Slovenia — Add missing Velenje urban municipality (SI-133)
• Somalia — Add missing Sool and Woqooyi Galbeed regions (ISO 3166-2:SO)
• Spain — Add 3 missing autonomous communities per ISO 3166-2:ES; fix 474 city name prefixes and apostrophes
• Taiwan — Add missing Chiayi County (TW-CYQ) and Hsinchu County (TW-HSQ)
• Tajikistan — Add missing capital territory Dushanbe (TJ-DU)
• Timor-Leste — Add missing Oecusse-Ambeno special administrative region
• Trinidad and Tobago — Fix administrative divisions to match ISO 3166-2
• UK — Update countries to include states and cities
• Wallis and Futuna Islands — Add missing administrative precincts (ISO 3166-2:WF)
• Yemen — Add missing Ad Dali' governorate (YE-DA); fix city timezones, remove duplicates

🐛 Bug Fixes

• Fix duplicate states: remove 16 duplicate state records and reassign 30 cities
• Fix city assignments: move 130 Irkutsk Oblast cities from Sevastopol to correct state
• Fix Åland Islands duplication: remove duplicate state entry from Finland
• Fix 178 data integrity issues in contributions JSON files
• Fix Poland cities: remove 314 powiats incorrectly classified as cities
• Fix Chile: remove comunas incorrectly listed as cities in Región Metropolitana
• Fix timezone inconsistencies: add Etc/GMT filtering and update states data
• Fix NULL handling in export workflow (Antarctica subregion_id)
• Fix DuckDB conversion failure with individual SQLite table files
• Fix Bahrain: remove Central governorate
• Fix Bosnia and Herzegovina: remove extra cantons
• Fix Saint Lucia: remove extra districts
• Fix state & city names across multiple countries
• Fix currency and currency_symbol for Western Sahara and Congo
• Fix Vietnam state codes and The Gambia country name whitespace
• Fix Albania states and Greece states and cities
• Fix Ivory Coast English and Native Name
• Fix French cities native names
• Fix state population cast to integer in JSON exporter
• Add missing timezones and fix typos
• Remove duplicate cities (Shaw/US, Canberra/Australia)

🗄️ Schema & Infrastructure

• Refactor world.sql: clean up table drop statements, add timezone field
• Fix schema file formats: add PostgreSQL schema export, remove SQL Server schema
• Restructure contributions workflow
• Streamline README content and improve clarity
• Add changelog functionality
• Add GitHub Copilot instructions

New Contributors

• @Copilot made their first contribution in [#1067](#1067)
• @tomaytotomato made their first contribution in [#1106](#1106)
• @edyhvh made their first contribution in [#1108](#1108)
• @Towbee05 made their first contribution in [#1213](#1213)
• @Charles-Chrismann made their first contribution in [#1238](#1238)
• @swkim0911 made their first contribution in [#1321](#1321)

Full Changelog: v3.0...v3.1

v3.0

!!Breaking Change

• BREAKING CHANGE: Updated keys in states.json from 'state_code' to 'iso2' for consistency.

What's Changed

• Cities Updates by @Aakash315 in #987
• change state name of UAE, Egypt and Kuwait by @Aakash315 in #995
• changes some data and also add data by @Aakash315 in #996
• add missing states and cities by @Aakash315 in #998
• Fix: optimize prisma seeder to reduce DB queries and improve performance by @Khuzaima01 in #999
• changes in cities table by @Aakash315 in #1001
• update netherland provinces by @Aakash315 in #1003
• update france & brazil cities by @Aakash315 in #1021
• upadte maxico by @Aakash315 in #1022
• Improve Workflow by @dr5hn in #1033
• Fix Norway county and cities by @Aakash315 in #1037
• Add breton (br) language by @YoruNoHikage in #1035
• remove duplicate cities and states or add capital city of mongolia by @Aakash315 in #1046
• Fix/json error by @Aakash315 in #1054

New Contributors

• @Khuzaima01 made their first contribution in #999
• @YoruNoHikage made their first contribution in #1035

Full Changelog: v2.6...v3.0

v2.6

What's NEW!

• SQL Server support by @dr5hn in #906
• MongoDB support by @dr5hn in #967
• Added Parent ID and Levels in States table to accomodate different hierarchies of countries with different structures.

What's Changed

• fix: Add Missing cities in Isle of Man and Jersey by @Aakash315 in #899
• fix: Solve inconsistent languages issue by @Aakash315 in #905
• fix: Update Cities And States Of Greece by @Aakash315 in #904
• Fix some currencies by @mtsfer in #909
• Fix: Update Cities on Banten, Indonesia by @Aakash315 in #911
• fix: Insert Missing data in Vietnam by @Aakash315 in #912
• fix: Solve cities problem in Argentina by @Aakash315 in #910
• Fix: world.sql import error by @souravdutt in #931
• update table by @Aakash315 in #928
• add states by @Aakash315 in #935
• update types by @Aakash315 in #936
• add column by @Aakash315 in #943
• fix: JSON export region_id type consistency by @gschaer in #957
• feat: add if exists flag in postgresql by @dr5hn in #963
• fix: #951 INSERT conflicts with FOREIGN KEY by @dr5hn in #964
• Correction/telangana by @Aakash315 in #975
• Correction/china by @Aakash315 in #976
• Correction/srilanka by @Aakash315 in #980
• Correction of City and Municipaliy iin Aklan and Antique Provinces, P… by @Aakash315 in #974
• Corrections by @Aakash315 in #978
• Level/parent by @Aakash315 in #981
• Fix/poland by @Aakash315 in #985
• Add/cities by @Aakash315 in #986

BREAKING Change

• Drop support for additional xml, sqlite, yml combination files by @dr5hn in #907
• Removed states+cities.json file. by @dr5hn in b19d5b7
• Optimised countries+states.json and countries+cities.json file content with only name of the entities. by @dr5hn in b19d5b7

New Contributors

• @souravdutt made their first contribution in #931
• @gschaer made their first contribution in #957

Full Changelog: v2.5...v2.6