API Reference

Search Mexican zip codes

Find the zip codes of a place by state, municipality, settlement (colonia) name, or the first digits of the zip.

POST /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

POST /v1/geo/zip-search
Try it

Sign in to send a real request from this page.

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

or
or

Example request

curl bash
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)

200 OK json
{
  "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.