Search Mexican colonias by name
People remember the name of their neighbourhood. They rarely remember its postal code. This is the lookup that runs in that direction: type part of a colonia name, get every match in the country with the code, municipio and estado attached.
When you have the name and not the number
Two situations produce this, and they look nothing alike from the outside.
-
A form where the postal code field is empty.
Someone is entering an address they know by sight rather than by paperwork. Let them start from the colonia and fill the code in for them, rather than sending them off to look it up and lose the checkout.
-
A table of addresses somebody typed years ago.
Legacy customer records usually captured a colonia name and nothing to join it to. Matching those names back to real settlements is how you get a postal code onto rows that never had one.
Partial name in, matches out
Two characters is the minimum, which is enough to drive a type-ahead without asking the whole catalog for the letter A.
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://api.postalkit.mx/v1/settlements?q=Polanco&page=1"
Response
{
"data": [
{
"id": 8421,
"name": "Polanco I Sección",
"type": "Colonia",
"postal_code": "11510",
"municipality": "Miguel Hidalgo",
"state": "Ciudad de México"
}
],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "total": 6, "per_page": 20 }
}
Every match carries its own municipio and estado. That is not padding — it is the only thing that makes the result usable, because a colonia name on its own does not identify a place.
Before you ship it
Name matching in Mexico is not a solved problem
-
“Centro” is not one place.
Common names repeat across states, and a search for one will return many. Never take the first result. This endpoint takes a name and nothing else, so either show the municipio and estado in the picker and let a person choose, or — when you already know the state — run the geographic search instead, which filters by estado, municipio and colonia together.
-
Results are paginated, twenty at a time.
The meta block carries the true total. A type-ahead that only ever reads page one is fine; a data-cleaning job that does the same silently drops most of its candidates.
-
The catalog spells names the way SEPOMEX spells them.
Accents included, and abbreviations expanded. Your legacy rows almost certainly do neither, so expect to match on a normalised form of what you have rather than on the raw string.
-
Store the id, not the name.
Once a person has picked the right settlement, keep its id. It survives the monthly refresh, and it means you never run this search on the same record twice.