Referencia de la API

Consulta un código postal de México

Envía un código postal y recibe su estado, municipio, ciudad y colonias, del catálogo de Correos de México.

POST /v1/geo/zip

Regresa lo que cubre un código postal de México: su estado, municipio, ciudad y cada asentamiento (colonia) que atiende. Se responde desde nuestra copia del Catálogo Nacional de Códigos Postales que publica Correos de México (SEPOMEX), actualizada a diario, así que termina en milisegundos.

Úsalo para llenar un formulario de dirección a partir del código postal, o para revisar que el código postal, la colonia y el municipio que escribió un cliente correspondan entre sí.

Precios: gratis para usuarios con cualquier plan activo. Quienes pagan por uso (sin plan, solo saldo) pagan 1 crédito por llamada.

Cuerpo de la solicitud

Campo Tipo Requerido Descripción
zip string Sí El código postal de cinco dígitos, como texto para conservar el cero inicial ("06600").

Pruébalo

POST /v1/geo/zip
Pruébalo

Inicia sesión para enviar una solicitud real desde esta página.

Las cuentas nuevas reciben $5 USD de crédito al registrarse, sin tarjeta.

Solicitud de ejemplo

curl bash
curl -X POST https://mexcheck.com/v1/geo/zip \
  -H "x-api-key: rfc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"zip": "22000"}'

Respuesta (200)

200 OK json
{
  "zip": "22000",
  "found": true,
  "message": "Zip code found.",
  "state": "Baja California",
  "state_code": "02",
  "municipality": "Tijuana",
  "municipality_code": "004",
  "city": "Tijuana",
  "settlements": [
    {"name": "Zona Centro", "type": "Colonia", "zone": "Urbano"},
    {"name": "Zona Este", "type": "Colonia", "zone": "Urbano"},
    {"name": "Zona Norte", "type": "Colonia", "zone": "Urbano"}
  ]
}
Campo Descripción
found true cuando el catálogo tiene el código postal. false cuando no: los campos del lugar van en null y settlements va vacío. Esa respuesta se cobra como cualquier otra.
state, state_code El estado como lo nombra Correos de México ("Veracruz de Ignacio de la Llave", "México" para el Estado de México) y su clave INEGI de dos dígitos.
municipality, municipality_code El municipio, o la alcaldía en la Ciudad de México, y su clave INEGI de tres dígitos dentro del estado. Un código postal pertenece exactamente a uno.
city La ciudad, cuando el código postal está en una. Null en la mayoría de los códigos postales rurales.
settlements Cada asentamiento que atiende el código postal, en orden alfabético: su nombre, su tipo (Colonia, Fraccionamiento, Ejido, Pueblo, Ranchería...) y su zona (Urbano, Semiurbano o Rural).

Un código postal que el catálogo no tiene

200 OK json
{
  "zip": "99999",
  "found": false,
  "message": "Correos de México's catalogue has no zip code 99999.",
  "state": null,
  "state_code": null,
  "municipality": null,
  "municipality_code": null,
  "city": null,
  "settlements": []
}

Errores

Un zip que no tiene cinco dígitos regresa 422 con error invalid_fields y fields ["zip"], y no se cobra. Consulta la página de errores para los códigos que comparten todos los endpoints.