French-postal-code-4.0.0

First release of the rebuilt dataset. The 2018 builder (manual INSEE files, regular expressions, HTML scraping, Google Maps) is replaced by a pipeline built on the official open data, so the files can be refreshed in about 15 minutes instead of by hand.

Highlights

• One GPS point per postal code. Each commune and postal code pair has its own point, the median of the addresses of the Base Adresse Nationale: 99.4 % of the points come from the BAN, 184 from Nominatim and 36 fall back to the centre of the commune. The coordinate_source column always tells which.
• History of the changes. An old INSEE code is followed to the commune and postal codes that replace it, with the date and the kind of change: merger, split, code reuse, deletion. Saint-Florent-des-Bois, merged into Rives de l'Yon in 2016, resolves to the new commune.
• Stable identifiers. A row is never deleted: its validity is closed (valid_from, valid_to) and a closed city points to its replacement, so an application can reference cities by a foreign key.
• A pipeline that checks itself. The official files are downloaded, versioned and imported, the points are computed in parallel, and a reconciliation step marks the data complete only when nothing is missing.

Breaking changes

This version is not compatible with 3.0.0.

• New schema: one row per commune and postal code, with valid_from and valid_to columns.
• New file layout: one CSV and one JSON file per table, plus the history files.
• Commands are in the dataset: namespace (dataset:update, dataset:status, dataset:resolve, dataset:export).
• Requires PHP 8.4 and Laravel 13.

The dataset in numbers

Regions	18
Departments and overseas collectivities	110
Communes	35,015
Cities (commune + postal code)	35,510
Code successions	8,480
Sources	INSEE COG 2026, La Poste 2026-10

Files

• french-postal-code-4.0.0-csv.zip: one CSV file per table.
• french-postal-code-4.0.0-json.zip: one JSON file per table.
• french-postal-code-4.0.0-sql.zip: a MySQL dump of the same tables.
• statistics.json: the figures above and the versions of the sources.
• SHA256SUMS: checksums of the files.

Migrating your data

commune_successions and replaced_by_city_id in cities map every old code to its successors. To check one code, run make resolve CODE=85043 POSTAL_CODE=85310. See "Migrating old codes" in the README.

Known limits

• The INSEE publishes no event for postal codes: their history starts at the first import kept, and is less reliable than the one of the communes.
• Paris, Lyon and Marseille have no city of their own, their arrondissements carry the postal codes; 9 communes are in that case, with a few territories without a postal code.
• The overseas collectivities have no history before this import.

Sources and licences

INSEE, La Poste, geo.api.gouv.fr and the BAN are under the Licence Ouverte; Nominatim (OpenStreetMap) is under the ODbL. The code is under the MIT licence.