Ir al contenido

Códigos postales cercanos a un punto

GET/v1/nearbyPlanes de pago (Básico o superior)

¿Qué hace?

Los códigos postales alrededor de un punto, del más cercano al más lejano; por ejemplo, para revisar la cobertura de entrega alrededor de una tienda.

Códigos postales cuya ubicación de referencia está dentro de radius_km del punto. La distancia se mide a la ubicación de referencia, no al borde del área. Solo se consideran los códigos postales con precisión postal_code_polygon o locality_centroid. Sin paginar.

La petición

ParámetroTipoValores aceptadosDescripción
laten la consultaobligatorionúmero
de -90 a 90
Latitud en grados decimales (WGS84), hasta 20 decimales (como la da un GPS o un navegador); se redondea a 6 (unos 10 cm).
lonen la consultaobligatorionúmero
de -180 a 180
Longitud en grados decimales (WGS84), hasta 20 decimales (como la da un GPS o un navegador); se redondea a 6 (unos 10 cm).
radius_kmen la consultanúmero
más de 0 y hasta 50
por omisión: 5
Radio de búsqueda en kilómetros (mayor que 0, máximo 50, hasta 3 decimales).
limiten la consultaentero
de 1 a 50
por omisión: 10
Número máximo de códigos postales (1–50).

Ejemplo

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/nearby?lat=19.4195&lon=-99.1617&radius_km=1&limit=2"

Cambia TU_LLAVE por tu llave; en los lenguajes, se lee de la variable de entorno COLONIX_API_KEY. Esta petición es la que produjo la respuesta de abajo.

La respuesta

Respuesta real a la petición del ejemplo. Viene con los encabezados ETag, X-Data-Version, Cache-Control.

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"
}

Campos

CampoTipoDescripción
datalista de objetos
data[].postal_codetextoCódigo postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700).
data[].stateobjetoElemento de un catálogo.
data[].municipalityobjetoElemento de un catálogo.
data[].settlement_countenteroNúmero de asentamientos
data[].distance_kmnúmeroDistancia en km a la ubicación de referencia
data[].locationobjetoUbicación de referencia de un código postal. Nunca es una dirección exacta. postal_code_polygon: un punto dentro del área del código postal (su centroide, o un punto interior cuando el centroide queda fuera) y la caja que contiene el área. locality_centroid: la localidad del INEGI con el mismo nombre que un asentamiento o la ciudad del código postal (sin caja). municipality_centroid: el centro de las áreas de los códigos postales del municipio, para códigos postales sin área ni localidad que coincida.
data_versiontextoVersión del dato

Errores

Todos en formato application/problem+json; ninguno cuenta para tu cuota. Qué hacer con cada uno: Errores.

EstadoCuándo
400Parámetro inválido o repetido (/errors/invalid-parameter), un parámetro que el endpoint no tiene (/errors/unknown-parameter), cursor vencido (/errors/cursor-expired), versión del dato desconocida (/errors/unknown-version) o as_of fuera del historial registrado (/errors/as-of-out-of-range).
401Credenciales faltantes (/errors/missing-api-key) o inválidas (/errors/invalid-api-key).
403Llave suspendida (/errors/api-key-suspended) o endpoint fuera de tu plan (/errors/plan-not-allowed).
429Se alcanzó la cuota mensual (/errors/quota-exceeded) o el límite por minuto (/errors/rate-limited). La respuesta del límite por minuto trae el mismo cuerpo, pero con Content-Type: application/json.
5XXError inesperado (/errors/internal-error) o servicio no disponible por un momento (503, que puede llegar sin cuerpo). Reintenta unas cuantas veces, esperando cada vez más.