Look up a Mexican postal code from your own application
Somebody typed five digits into a form. You need to know which estado and municipio that is, and which colonias they could possibly have meant, before they can finish the address. That is one request.
What you are actually trying to do
A Mexican address is not a free-text field. A postal code determines the estado and the municipio outright, and it narrows the colonia down to a short list. Every checkout, every delivery form and every CRM import in the country is doing the same three things with that fact.
-
Filling in the fields the customer should not have to type.
Estado and municipio follow from the code. Asking for them again is three more chances to get a delivery address wrong.
-
Offering the colonia as a list rather than a text box.
This is where addresses actually go wrong. Left to type it, people give you “Centro”, “centro”, “Col. Centro” and “Guadalajara Centro” for one place.
-
Rejecting a code that does not exist, at the point it is typed.
A five-digit number passing a regex is not a real postal code. The lookup answers 404 when nothing is there, which is the cheapest validation you will ever write.
One request, everything the form needs
Send the code, get the record. 06600 is the Colonia Juárez end of the Cuauhtémoc borough in Mexico City, and it is the code the examples throughout the reference use, so it is an easy one to compare against.
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/postal-codes/06600
Response
{
"data": {
"id": 384,
"code": "06600",
"state": { "id": 1, "name": "Ciudad de México", "code": "09" },
"municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" },
"city": { "id": 1, "name": "Ciudad de México" },
"settlements": [
{ "id": 532, "name": "Juárez", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
]
}
}
The estado and municipio go straight into their fields. The settlements array is the colonia dropdown — render name, keep id. That id is what you store on the order, because it still means the same colonia after the catalog refreshes and a name string does not.
If you already have the estado and municipio on the record and only need the list again — the customer changed their mind, or you are re-rendering a saved address — there is a slimmer call that skips the rest:
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/postal-codes/06600/settlements
Response
{
"data": [
{ "id": 532, "name": "Juárez", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
]
}
Before you ship it
Four things that catch people out
-
Postal codes are strings, not integers.
Every code in Ciudad de México and much of the centre of the country begins with a zero. Parse 06600 as a number anywhere in your stack and you will be asking for 6600, which is somewhere else entirely.
-
404 is an answer, not a failure.
An unknown code returns 404 with a message naming the code. Treat it as “no such postal code” and show the field error; do not retry it or log it as an outage.
-
A colonia is not always a colonia.
settlement_type distinguishes Colonia from Fraccionamiento, Barrio, Unidad habitacional and the rest. Show the name alone in a dropdown and two different places under one code can read identically.
-
Cache it. It changes monthly at most.
The catalog is re-checked against the source on the first of each month and nothing moves unless the source moved. GET /v1/account/db-version tells you which version answered you, so a cache keyed on it invalidates itself.