Códigos postales cercanos a un punto
/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ámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
laten la consultaobligatorio | nú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 consultaobligatorio | nú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 consulta | nú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 consulta | entero | 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"const url = new URL("https://colonix.silgaru.mx/v1/nearby");url.searchParams.set("lat", "19.4195");url.searchParams.set("lon", "-99.1617");url.searchParams.set("radius_km", "1");url.searchParams.set("limit", "2");
const res = await fetch(url, { headers: { "x-api-key": process.env.COLONIX_API_KEY }, signal: AbortSignal.timeout(5000),});const data = await res.json();if (!res.ok) throw new Error(`${data.type}: ${data.detail}`);
console.log(data);import osimport requests
res = requests.get( "https://colonix.silgaru.mx/v1/nearby", params={"lat": "19.4195", "lon": "-99.1617", "radius_km": "1", "limit": "2"}, headers={"x-api-key": os.environ["COLONIX_API_KEY"]}, timeout=5,)data = res.json()if not res.ok: raise RuntimeError(f"{data['type']}: {data['detail']}")
print(data)<?php$url = "https://colonix.silgaru.mx/v1/nearby?" . http_build_query(["lat" => "19.4195", "lon" => "-99.1617", "radius_km" => "1", "limit" => "2"]);$ch = curl_init($url);curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("COLONIX_API_KEY")], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 5,]);$data = json_decode(curl_exec($ch), true);if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) { throw new RuntimeException("{$data['type']}: {$data['detail']}");}
print_r($data);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.
{ "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
| Campo | Tipo | Descripción |
|---|---|---|
data | lista de objetos | |
data[].postal_code | texto | Có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[].state | objeto | Elemento de un catálogo. |
data[].municipality | objeto | Elemento de un catálogo. |
data[].settlement_count | entero | Número de asentamientos |
data[].distance_km | número | Distancia en km a la ubicación de referencia |
data[].location | objeto | Ubicació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_version | texto | Versión del dato |
Errores
Todos en formato application/problem+json; ninguno cuenta para tu cuota. Qué hacer con cada uno: Errores.
| Estado | Cuándo |
|---|---|
400 | Pará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). |
401 | Credenciales faltantes (/errors/missing-api-key) o inválidas (/errors/invalid-api-key). |
403 | Llave suspendida (/errors/api-key-suspended) o endpoint fuera de tu plan (/errors/plan-not-allowed). |
429 | Se 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. |
5XX | Error 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. |
© 2026 Silgaru