Ir al contenido

El código postal desde unas coordenadas

Si tienes la ubicación de tu usuario o de una entrega, Colonix te dice en qué código postal cae y cuáles están alrededor. Sirve para llenar la dirección con un toque, calcular coberturas de envío o revisar que una dirección declarada esté cerca de donde dice.

Necesitas: plan Básico o superior. En el plan Gratis, los cinco códigos postales de demostración responden con su ubicación (include=location) para que la pruebes.

GET /v1/reverse recibe una latitud y una longitud en grados decimales (WGS 84) y responde el código postal cuya área contiene ese punto. Mándalas como te las da el GPS del celular o el navegador, con todos sus decimales:

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/reverse?lat=19.4195&lon=-99.1617"
200 OK
{
"postal_code": "06700",
"in_sepomex_catalog": true,
"state": { "id": "09", "name": "Ciudad de México" },
"municipality": { "id": "015", "name": "Cuauhtémoc" },
"settlement_count": 1,
"precision": "postal_code_polygon",
"source_date": "2026-01-05",
"data_version": "2026.11.05-36a7823b"
}

La respuesta dice el código postal, el estado y el municipio. Para mostrar sus colonias, pide después GET /v1/postal-codes/06700 y deja que tu usuario elija la suya: un punto en el mapa no basta para saber la colonia exacta.

  • in_sepomex_catalog: false: el área existe en el mapa oficial de códigos postales, pero SEPOMEX no tiene colonias registradas para ella (pasa en unos 4,500 códigos postales rurales).
  • Un punto justo en el límite entre dos códigos postales puede dar el vecino: las áreas están simplificadas a unos 10 metros.
  • Si el punto no cae en ningún área (en el mar, fuera de México o con la latitud y la longitud invertidas), la respuesta es 404 con location-not-covered.
  • Los 537 códigos postales sin área propia (los que se ubican por su localidad o su municipio, abajo) nunca salen aquí: su punto de referencia cae dentro del área de otro código postal. Así vienen en el mapa oficial.

Se aceptan hasta 20 decimales y se redondean a 6, que ya son unos 10 centímetros: dos lecturas del mismo punto dan la misma respuesta. Con más de 20 decimales, o con un número escrito de otra forma (1e2, 19,42), la respuesta es 400.

GET /v1/nearby da los códigos postales cuyo punto de referencia está dentro de un radio, del más cercano al más lejano. radius_km va de más de 0 a 50 (hasta 3 decimales) y limit, de 1 a 50:

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/nearby?lat=19.4195&lon=-99.1617&radius_km=1&limit=3"
200 OK
{
"data": [
{
"postal_code": "06700",
"state": { "id": "09", "name": "Ciudad de México" },
"municipality": { "id": "015", "name": "Cuauhtémoc" },
"settlement_count": 1,
"distance_km": 0.165,
"location": {
"lat": 19.418352,
"lon": -99.162691,
"bbox": [-99.17671, 19.41045, -99.15366, 19.42585],
"precision": "postal_code_polygon",
"source_date": "2026-01-05"
}
},
{
"postal_code": "06600",
"state": { "id": "09", "name": "Ciudad de México" },
"municipality": { "id": "015", "name": "Cuauhtémoc" },
"settlement_count": 1,
"distance_km": 0.852,
"location": {
"lat": 19.427159,
"lon": -99.161573,
"bbox": [-99.17642, 19.42081, -99.14974, 19.43546],
"precision": "postal_code_polygon",
"source_date": "2026-01-05"
}
}
],
"data_version": "2026.11.05-36a7823b"
}

En un radio de 1 km solo hay dos: limit es un máximo, no una cantidad garantizada. Si no hay ninguno, data llega vacío.

Si tienes el código postal y quieres su punto en el mapa, agrega include=location a la consulta del código postal: GET /v1/postal-codes/06700?include=location agrega el mismo bloque location de arriba.

Son puntos de referencia, nunca la dirección exacta de una casa: sirven para ubicar la zona. Cada ubicación dice de dónde sale en precision:

precision De dónde sale Qué tan preciso
postal_code_polygon Un punto dentro del área oficial del código postal (SEPOMEX): su centro o, si el centro cae fuera del área, un punto interior El más preciso: casi todos los códigos postales
locality_centroid La localidad del INEGI con el mismo nombre que una colonia o la ciudad del código postal Aproximado: la localidad puede ser más grande o más chica que el código postal
municipality_centroid El centro de las áreas de códigos postales del municipio Solo para ubicar la región

bbox es la caja que encierra el área ([oeste, sur, este, norte], en grados); con locality_centroid es null. source_date es la fecha de la fuente. Un código postal sin ubicación responde "location": null. La API nunca entrega las áreas completas (polígonos).