/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
/v1/geo/zip
Sign in to send a real request from this page.
New accounts get a $5 USD signup credit, no card required.
Example request
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)
{
"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
{
"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.