/v1/geo/zip-search
Finds the zip codes of a place. Search by state, municipality, and settlement (colonia) name, by the first digits of the zip code, or by any mix of them. Each result is a settlement with its zip code. Answered from our copy of the Catálogo Nacional de Códigos Postales that Correos de México (SEPOMEX) publishes, in milliseconds.
Use it when you have an address without a zip code, or to offer the colonias of a municipality as someone types.
Pricing: free for users on any active plan. Pay-as-you-go callers (no plan, balance only) pay 1 credit per call.
Request body
Send at least one of zip, municipality, or settlement. state narrows a search and cannot be sent alone.
| Field | Type | Description |
|---|---|---|
zip |
string | The first two to five digits of the zip code ("664" finds 66400 to 66499). |
state |
string | The state's name, or how it starts: "Veracruz" finds Veracruz de Ignacio de la Llave. "Estado de México" and "CDMX" are understood. A name that fits no state, or more than one, returns 422. |
municipality |
string | Three or more letters found anywhere in the municipality's name ("san nicolas" finds San Nicolás de los Garza). |
settlement |
string | Three or more letters found anywhere in the settlement's name. |
limit |
integer | How many results to return, 1 to 200. Defaults to 50. |
Names match whatever their accents and capitals: "juarez" finds Juárez.
Try it
/v1/geo/zip-search
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-search \
-H "x-api-key: rfc_your_api_key" \
-H "Content-Type: application/json" \
-d '{"state": "Nuevo León", "municipality": "San Nicolás de los Garza", "settlement": "miraflores"}'
Response (200)
{
"count": 1,
"truncated": false,
"results": [
{
"zip": "66410",
"settlement": "Miraflores",
"type": "Colonia",
"zone": "Urbano",
"municipality": "San Nicolás de los Garza",
"state": "Nuevo León"
}
]
}
| Field | Description |
|---|---|
count |
How many results this response carries. |
truncated |
true when more settlements matched than limit. Narrow the search or raise limit. |
results |
The matching settlements, ordered by zip code and then by name. Empty when nothing matched, which is charged like any other answer. |
Errors
A search it cannot run returns 422 with error invalid_fields and the fields at fault, and is not charged: nothing to search by, a zip prefix that is not two to five digits, a name under three letters, an unknown state, or a limit outside 1 to 200.