Saltar al contenido

Lista todos los códigos postales de un estado o municipio de México

Hay preguntas que no son sobre una dirección. ¿Qué códigos cubre esta paquetería? ¿Cuáles caen dentro de aquel territorio de ventas? ¿Qué va en el desplegable una vez que el cliente eligió Jalisco? Esas son consultas por región, y llamar en un ciclo a una consulta de un solo código es la forma equivocada de resolverlas.

Tres maneras de pedir una región

Se diferencian por lo que traes en la mano al preguntar, que suele ser el factor que decide.

  • Tienes nombres, de un formulario o de una hoja de cálculo.

    La búsqueda geográfica recibe un estado y, si quieres, un municipio y una colonia, como texto. Es la que hay que usar cuando la entrada vino de una persona.

  • Tienes un identificador, de una llamada anterior.

    Si ya recorriste la jerarquía y tienes el id de un estado o un municipio, pide sus códigos postales directamente. Sin emparejar nombres, sin ambigüedad, y pagina limpio.

  • Tienes los primeros dígitos.

    La búsqueda por prefijo existe para el caso del autocompletado: alguien va a medio escribir un código y quieres las terminaciones plausibles.

Buscar por estado, municipio y colonia

El estado es obligatorio; lo demás acota. El emparejamiento es difuso por defecto, que es lo que quieres cuando el texto vino de una persona, y exact=true lo desactiva cuando no.

Solicitud

curl 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes/search?state=Jalisco&municipality=Guadalajara&colonia=Centro"

Respuesta

200 Éxito (paginado) 
{
  "data": [
    {
      "id": 3,
      "code": "44100",
      "state": { "id": 14, "name": "Jalisco", "code": "14" },
      "municipality": { "id": 39, "name": "Guadalajara", "code": "039" },
      "city": { "id": 1, "name": "Guadalajara" },
      "settlements": [
        { "id": 5, "name": "Guadalajara Centro", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "total": 1, "per_page": 20 }
}

Si omites el estado obtienes un 422 en lugar del país entero, y es a propósito: un recorrido sin límites del catálogo nunca es la consulta que alguien quiso escribir.

Listar por identificador

Cuando la región viene del catálogo y no de una persona, pídela por id. Esta es la llamada detrás de un desplegable en cascada, y detrás de cualquier proceso que recorra el país municipio por municipio.

Solicitud

curl 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/2/postal-codes

Respuesta

200 Éxito (paginado) 
{
  "data": [
    {
      "id": 1,
      "code": "20000",
      "state": { "id": 2, "name": "Aguascalientes", "code": "01" },
      "municipality": { "id": 1, "name": "Aguascalientes", "code": "001" },
      "city": { "id": 1, "name": "Aguascalientes" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 100, "per_page": 20 }
}

La misma llamada existe un nivel más abajo, en /v1/municipalities/{id}/postal-codes, para cuando un estado entero es más de lo que querías.

Completar un código a medio escribir

Dos dígitos o más, ordenados por código, y es la única de las tres que responde algo útil mientras alguien sigue escribiendo.

Solicitud

curl 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes?q=066&page=1"

Los 32 estados, uno por uno

Cada estado tiene su propia página: todos sus municipios, con su clave INEGI, cuántos códigos postales tiene cada uno y el rango que cubren.

Antes de publicarlo

Las consultas por región son donde se va la cuota

  • Veinte filas por página, en todas estas.

    Un estado grande son muchas páginas, y cada página es una solicitud contra tu cuota mensual. Lee meta.total primero y decide si de verdad lo quieres todo antes de arrancar el ciclo.

  • Baja la región una vez, no por visitante.

    El conjunto de códigos postales de un municipio no cambia entre dos cargas de página. Tráelo de forma programada, guárdalo y sirve tu propio desplegable desde tu propia base de datos.

  • El emparejamiento difuso está activo salvo que lo apagues.

    Eso está bien para una caja de búsqueda y mal para una importación nocturna, donde un casi-acierto escribe en silencio el municipio equivocado en una fila. Pasa exact=true para entradas de máquina.

  • Cada respuesta te dice cuánto te queda.

    X-RateLimit-Limit y X-RateLimit-Remaining traen tu cuota mensual y lo que resta de ella. Un proceso masivo que las vigila se detiene en sus propios términos y no a medio camino.

Baja una región y mira qué tan grande es.

100 solicitudes al mes, gratis, sin tarjeta. Suficiente para dimensionar el trabajo antes de comprometerte con un plan.

curl -s "https://api.postalkit.mx/v1/postal-codes/search?state=Jalisco" -H "Authorization: Bearer YOUR_API_KEY"
Obtén tu API key gratis Ver precios