List every colonia in a Mexican municipio
The postal code lookup answers “which colonias are under these five digits”. This one answers the bigger question above it: everything inside a municipio, each row carrying the postal code it belongs to.
When the municipio is the thing you know
This is the last step of a cascade, and it is also the shape of most bulk work against the catalog.
-
The third dropdown.
Estado, municipio, colonia. By the time somebody reaches the third field you already hold a municipio id, and the list of colonias follows from it without asking for a postal code first.
-
Checking what you already store.
Pull the real list for a municipio and diff it against the colonia names in your own tables. What does not match is the part of your address data that was never right.
-
Working out where you actually deliver.
Coverage is usually decided a municipio at a time and then expressed in colonias and postal codes. This is the call that turns one into the other.
A municipio id in, colonias out
Alphabetical, paginated, and every row carries the postal code that colonia sits in — which is what makes the response useful on its own rather than a list of names to look up again.
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/municipalities/6/settlements
Response
{
"data": [
{
"id": 532,
"name": "Juárez",
"zone": "Urbano",
"settlement_type": { "id": 1, "name": "Colonia" },
"postal_code": { "id": 384, "code": "06600" }
}
],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "total": 230, "per_page": 20 }
}
There is a second route to the same list, nested under the estado, for when you are walking the hierarchy down and hold both ids:
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/1/municipalities/6/settlements
Same payload. The nested form checks that the municipio really belongs to that estado, so it fails loudly on a mismatched pair instead of quietly answering about somewhere else.
Before you ship it
A municipio is bigger than it looks
-
Hundreds of colonias is normal.
At twenty a page that is a lot of requests for one dropdown. If it is going in a form, fetch it once on a schedule and serve it from your own store; if it is going in a report, read meta.total before you loop.
-
One name can appear more than once.
A large municipio can hold several settlements with the same name under different postal codes. Key your dropdown on id and show the code beside the name, or people will pick the wrong one and you will never hear about it.
-
Read settlement_type, not just the name.
The list mixes Colonia, Fraccionamiento, Barrio, Pueblo, Unidad habitacional and more. Labelling the whole thing “colonia” in your interface is what people expect; storing it that way loses information the catalog gave you.
-
zone tells you urbano from rural.
It is the field to look at if delivery, pricing or coverage rules differ between the two, and it is already in the response you are reading.