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"). |


## 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.