Colonia (neighbourhood) name from GeoNames -- empty on rows recovered only from SEPOMEX's official code list (no name in that source)
Place Name
admin_name1
string
State (32 federal entities)
Administrative Name 1
admin_code1
string
ISO 3166-2:MX code
Administrative Code 1
admin_name2
string
Municipio, from GeoNames
Administrative Name 2
admin_code2
string
GeoNames municipio code
Administrative Code 2
admin_name3
string
From GeoNames -- equals admin_name2 on roughly a fifth of rows, a distinct sub-municipal value on the rest, per the source
Administrative Name 3
admin_code3
string
From GeoNames
Administrative Code 3
latitude
number
SEPOMEX official polygon centroid where available, else GeoNames-estimated
Latitude
longitude
number
See latitude
Longitude
accuracy
string
POSTAL_CODE where sourced from a SEPOMEX official polygon centroid; otherwise GeoNames' own code (1=estimated, 4=gazetteer match, 6=centroid of addresses/shape)
Accuracy
alternative_city_name
string
Not populated in this release
Alternative City Name
Part of a data solution
Postal Codes Solution
Every worldwide postal-code dataset in one bundle — the ultimate global reference for precise postal codes.
Two independently licence-clean sources exist. Both verified downloadable on
this date; both CC BY 4.0, which permits commercial redistribution on
attribution alone.
Licence: CC-BY-4.0. Verified against export/zip/readme.txt on
2026-08-27 — that readme flags per-country restrictions for GB, CL, CN, IE,
MT, AR and BR only. Mexico carries no caveat.
accuracy scale is documented in the same readme: 1 = estimated,
4 = geonameid, 6 = centroid of addresses or shape.
Source 2 — SEPOMEX "Códigos postales por entidad federativa" (authority)
Publisher: Servicio Postal Mexicano, via datos.gob.mx. Licence
CC-BY-4.0. Last updated 2026-01-29 (data vintage 2025).
Discover the resource URLs via the CKAN API — do not hardcode them:
https://www.datos.gob.mx/api/3/action/package_show?id=codigos_postales_entidad_federativa
-> 32 resources, one per entidad federativa, format SHP
-> https://repodatos.atdt.gob.mx/api_update/sepomex/codigos_postales_entidad_federativa/CP_{ST}.zip
Total download ~110 MB. Each shapefile has exactly one attribute, d_cp
(5-char postal code), plus polygon geometry. So it is an authoritative code
list plus boundaries and carries no names — it must be joined to GeoNames
for place_name / admin_name*.
Value it adds over GeoNames alone: the definitive code list, and real
POSTAL_CODE-accuracy centroids derived from official polygons rather than
GeoNames' estimated points.
The old tabular SEPOMEX catalogue is dead.(Corrected 2026-10-12, see the owner decision at the end: it is not dead; it answers from some networks and was updated 2026-10-07. Only the check from 2026-08-27 below was wrong in calling it dead.) Both
correosdemexico.gob.mx/SSLServicios/ConsultaCP/CodigoPostal_Exportar.aspx
and the datosabiertos/cp/cpdescarga.txt path returned nothing at all
(no response, not a 404) on 2026-08-27. datos.gob.mx/busca/dataset/ catalogo-nacional-de-codigos-postales returns 404. Do not build against them.
Download trap — parallel fetch truncates silently
Fetching the 32 archives with xargs -n1 -P8 curl -s -O exited 0 and
produced 32 files of plausible size, but 8 were silently truncated
(CP_BCS, CP_CDMX, CP_Camp, CP_Chih, CP_Mich, CP_NL, CP_Pue, CP_Tab). The
failure surfaced only as BadZipFile at parse time. Re-fetching those 8
serially with --retry 3 produced files 2–7× larger.
Any build script MUST run unzip -tqq over every archive and re-fetch
failures serially before parsing.
Cross-check against what is currently sold (2026-08-27)
Compared the SEPOMEX code list against the live mx/mx.csv on R2:
count
SEPOMEX official codes (35,898 polygons, 1:1 with codes)
35,898
R2 mx/mx.csv rows
144,655
R2 distinct postal codes
32,448
in both
30,081
official codes MISSING from R2
5,817 (16% of the official list)
R2 codes with no official SEPOMEX polygon
2,367
Defects in the currently-published file
mx/mx.csv on R2 is a GeoNames re-export (row count matches
MX.zip exactly: 144,655) that was round-tripped through pandas and
corrupted:
Leading zeros stripped from admin codes — GeoNames admin_code1=01 →
published 1; admin_code2=001 → 1.
Integer codes written as floats — admin_code3=01 → 1.0.
admin_code1 is the GeoNames numeric scheme (01…32), not
ISO 3166-2:MX (AGU, BCN, …).
Fix by rebuilding with dtype=str throughout and deriving real ISO 3166-2
codes.
Attribution is currently absent from the sold product. R2 carries only
mx/mx.csv — no README.md, no datapackage.json, no ATTRIBUTION.txt,
no mx.zip. The repo datapackage.yml lists sources: [{title: "Multiple sources"}] with no licenses[]. CC BY 4.0 attribution is a licence
condition, so this is a live breach on a paid product — same failure class as
datahub-next#941.
Also: datapackage.yml sets is_premium: true with no premium_tier and
no premium_source_key, and there is no zip in R2 for a key to point at. A
buyer pays and receives nothing.
licence_status (proposed — needs human sign-off before shipping)
Both licences are unambiguous CC BY 4.0 and verified from the publishers'
own statements, but no human has signed these off yet — treat decision as
provisional until they do.
Proposed tier
A ($99). Two authoritative sources consolidated onto each other
(GeoNames names + SEPOMEX official code list and geometry), and the
consolidation demonstrably recovers 5,817 codes the single-source build
misses. Same shape as CA.
Build — 2026-08-28 (local only, not published)
Built via datasets/mx/scripts/fetch_sepomex.py + build_postal_codes_product.py.
Reconfirmed the download trap from the first pass on a fresh fetch: even
fetching all 32 archives strictly serially with --retry 3, one archive
(CP_Gro.zip) still came back truncated (4.83 MB) and failed unzip -tqq;
a single re-fetch produced a valid 6.09 MB file. Confirms this is not purely
a parallelism artifact — every archive must be verified with unzip -tqq
regardless of fetch strategy, not just when fetching in parallel.
Results, verified directly against the built file (not assumed from the
pre-build estimate):
Codes recovered from SEPOMEX only (no GeoNames match)
5,817 — matches the pre-build estimate exactly
Rows upgraded to a real SEPOMEX polygon centroid (accuracy=POSTAL_CODE)
141,160 / 144,655 GeoNames rows
Recovered rows carry a verified state (unambiguous — one shapefile per state)
and an official polygon centroid, but no place_name/admin_name2/
admin_name3 — SEPOMEX's shapefiles carry only d_cp and geometry, no
names. Disclosed in data/README.md and data/ATTRIBUTION.txt, not
papered over.
admin_code1 derived to ISO 3166-2:MX via a verified crosswalk (Wikipedia,
checked 2026-08-28), replacing GeoNames' bare INEGI numbering (01-32).
"Distrito Federal" (GeoNames' pre-2016 name) normalised to "Ciudad de
México" on output — disclosed correction.
Frictionless validation: valid: True.
Status: built and validated locally only. Nothing published to R2,
nothing committed to git.
2026-10-12 — owner decision: ship under CC BY 4.0
Decision (owner, 2026-10-12): the Mexico dataset ships under CC BY 4.0, on the strength of the licence that the datos.gob.mx dataset page for "Códigos postales por entidad federativa" states for the SEPOMEX shapefiles ("Licencia: Creative Commons Attribution 4.0", Wayback capture of the dataset page, 2026-01-30), together with GeoNames' CC BY 4.0. The shipped README, ATTRIBUTION and licenses in the descriptor already say CC BY 4.0 for both sources, so no shipped file changes. The two decision: "compatible" entries in the proposal above are now owner-approved (decided_by: owner, decided_at: 2026-10-12, channel postal-codes-r2).
Basis, and sources not to substitute:
datos.gob.mx's general terms ("Libre Uso MX", 2014-era text; the current text could not be read from our network) permit commercial exploitation with source citation; the dataset's own CC BY label governs here.
Sources that do NOT carry the dataset page's CC BY grant and must not be substituted: the Correos catalogue itself (pipe TXT/XLS/XML), gomflo/codigos-postales-mexico and postali.app (copies of it, with no CC BY grant of their own), jesusalcalaluna/Geojson_Codigos_Postales_Mexico (no licence file), datamx.io cp21.gz (third-party CC0 label on Correos data).
Why the producer cannot always fetch from the official site (P5):datos.gob.mx, repodatos.atdt.gob.mx and the Correos site return an Akamai 403 or time out from our network. The research on 2026-10-12 found the download URLs unchanged (Wayback shows repodatos.atdt.gob.mx/api_update/sepomex/codigos_postales_entidad_federativa/CP_{ST}.zip through 2026-03; the discovery path of the old script still applies), and US and European datacentre probes were refused too. So the producer tries the official site first and falls back to our private mirror of the 2026-08-28 snapshot (next section). A GeoNames-only build is not an option: it would drop the 5,817 codes only SEPOMEX has and the POSTAL_CODE-accuracy coordinates.
2026-10-12 — private R2 mirror of the SEPOMEX snapshot
The producer's fallback source is an unaltered copy of the SEPOMEX shapefiles (the .shp and .dbf of the 32 states) downloaded from datos.gob.mx on 2026-08-28, kept in our private premium bucket under mx/_sources/sepomex/2026-08-28/ (a sub-folder of the country prefix; the owner chose this over a bucket-root _sources/) with a manifest.json recording the source URL, the licence statement (Creative Commons Attribution 4.0, as stated on the dataset page), the snapshot date and per-file sha256. CC BY 4.0 permits copying and storing; its sharing conditions (credit, licence link, note of changes) are met in the shipped README and ATTRIBUTION, and a private copy is not shared at all. The mirror must stay non-public: the owner confirmed on 2026-10-12 that the postal-codes (premium) bucket is private, and the owner confirmed the access keys can write to it.
API access
Access dataset files directly from scripts, code, or AI agents.
Each file has a stable URL (r-link) that you can use directly in scripts, apps, or AI agents. These URLs are permanent and safe to hardcode.