API Reference

Look up a Mexican zip code

Send a zip code and get its state, municipality, city, and settlements (colonias) from Correos de México's catalogue.

POST /v1/geo/zip

Returns what a Mexican zip code (código postal) covers: its state, municipality, city, and every settlement (colonia) it serves. Answered from our copy of the Catálogo Nacional de Códigos Postales that Correos de México (SEPOMEX) publishes, refreshed daily, so it completes in milliseconds.

Use it to fill in an address form from the zip code, or to check that the zip, colonia, and municipality a customer typed belong together.

Pricing: free for users on any active plan. Pay-as-you-go callers (no plan, balance only) pay 1 credit per call.

Request body

Field Type Required Description
zip string Yes The five-digit zip code, as a string so a leading zero is kept ("06600").

Try it

POST /v1/geo/zip
Try it

Sign in to send a real request from this page.

New accounts get a $5 USD signup credit, no card required.

Example request

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"}'

Response (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"}
  ]
}
Field Description
found true when the catalogue has the zip code. false when it does not: the place fields are then null and settlements is empty. That answer is charged like any other.
state, state_code The state as Correos de México names it ("Veracruz de Ignacio de la Llave", "México" for the State of Mexico) and its two-digit INEGI code.
municipality, municipality_code The municipality, or the alcaldía in Mexico City, and its three-digit INEGI code within the state. A zip code belongs to exactly one.
city The city, when the zip code is in one. Null for most rural zip codes.
settlements Every settlement the zip code serves, in alphabetical order: its name, its type (Colonia, Fraccionamiento, Ejido, Pueblo, Ranchería...), and its zone (Urbano, Semiurbano, or Rural).

A zip code the catalogue does not have

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": []
}

Errors

A zip that is not five digits returns 422 with error invalid_fields and fields ["zip"], and is not charged. See the errors page for the codes every endpoint shares.