Los 32 estados y sus municipios, con las claves oficiales del INEGI
Todo formulario de dirección en México empieza con los mismos dos desplegables, y todo sistema que tenga que hablar con otro acaba teniendo que ponerse de acuerdo en cómo se llama un municipio. Esta es la capa que hay debajo de ambos problemas.
Dos trabajos, un catálogo
-
Desplegables en cascada que no se desfasan.
Estado, luego municipio, luego ciudad. Dejar esas listas fijas en el código funciona hasta el día en que un nombre cambia y tu copia y la de los demás dejan de coincidir.
-
Hablar INEGI con los sistemas que lo esperan.
La facturación, los trámites de gobierno, los socios logísticos y los conjuntos de datos públicos identifican un municipio por su clave numérica oficial, no por su nombre. Emparejar por nombre al cruzar esa frontera es como se pierden registros.
Empieza por arriba
La lista de estados es pequeña, fija y la primera llamada natural. Cada entrada trae los dos identificadores: id es el nuestro, code es la clave INEGI de dos dígitos.
Solicitud
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states
Respuesta
{
"data": [
{ "id": 2, "name": "Aguascalientes", "code": "01" },
{ "id": 1, "name": "Ciudad de México", "code": "09" }
]
}
Luego baja un nivel. Los municipios vienen con su propia clave de tres dígitos, que es el número único dentro del estado, no dentro del país.
Solicitud
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/1/municipalities
Respuesta
{
"data": [
{ "id": 1, "name": "Álvaro Obregón", "code": "010" },
{ "id": 6, "name": "Cuauhtémoc", "code": "015" }
]
}
Las ciudades cuelgan del estado y no del municipio, y un código postal no siempre tiene una: el campo llega en null cuando no hay. GET /v1/states/{id}/cities las lista para un estado cuando tu formulario necesita ese campo.
Entrar por el lado del INEGI
Si tus registros ya traen la clave oficial del estado, no tienes que buscar antes nuestro id, y de hecho no tienes que guardar nuestros ids en absoluto. Direcciona el estado por su clave:
Solicitud
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/by-code/09/municipalities
Ese endpoint existe por exactamente una razón: para que un sistema construido alrededor de la numeración del INEGI pueda usar esta API sin adoptar un segundo juego de identificadores que después tendría que mantener sincronizado.
Antes de publicarlo
Las claves son cadenas con ceros a la izquierda
-
«01» no es 1, y «010» no es 10.
Las claves de estado son de dos dígitos y las de municipio de tres, las dos con ceros a la izquierda, las dos cadenas. Convierte cualquiera a entero y los ceros se van para siempre, que es justo lo que rompe la relación por la que las agregaste.
-
Una clave de municipio solo significa algo junto a su estado.
«015» es Cuauhtémoc en la Ciudad de México y otra cosa en otro estado. La llave es el par; el número de municipio por sí solo no lo es.
-
Dos identificadores, y los dos son estables.
Los nuestros sobreviven a la actualización mensual, así que un id guardado sigue resolviendo. Aun así prefiere la clave INEGI si algo fuera de tu sistema va a leer ese valor alguna vez.
-
Esta lista es lo único que vale la pena copiar completo.
Treinta y dos estados y sus municipios son una tabla pequeña y casi estática. Tráela una vez, guárdala y revisa GET /v1/account/db-version de forma programada en lugar de pedirla en cada carga de página.