Búsqueda de asentamientos
/v1/settlementsTodos los planes¿Qué hace?
Busca asentamientos por nombre, código postal, estado o ciudad; por ejemplo, para encontrar el código postal de una colonia cuando el usuario solo sabe su nombre.
Requiere al menos uno de q, postal_code, state o city. Ordenados por código postal y nombre. Paginada: sigue next_cursor para obtener todos los resultados (por ejemplo, los 434 asentamientos de la ciudad de Guadalajara caben en una página con limit=500).
La petición
| Parámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
qen la consulta | texto | de 2 a 100 caracteres | Texto a buscar, sin importar mayúsculas ni acentos (de 2 a 100 caracteres, hasta 12 palabras). |
postal_codeen la consulta | texto | 5 dígitos | Código postal de 5 dígitos. |
stateen la consulta | texto | 2 dígitos | Clave INEGI del estado, 2 dígitos (ver /v1/states). |
municipalityen la consulta | texto | 3 dígitos | Clave INEGI del municipio, 3 dígitos; requiere state. |
cityen la consulta | texto | — | Nombre de la ciudad como lo escribe SEPOMEX ("Ciudad de México", no "CDMX"), sin importar mayúsculas ni acentos; un nombre que no coincide no da resultados. |
typeen la consulta | texto | 2 dígitos | Clave del tipo de asentamiento, 2 dígitos (ver /v1/settlement-types). |
zoneen la consulta | texto | urbanruralsemiurban | Zona. También se aceptan los valores del catálogo (urbano, semiurbano). |
fuzzyen la consulta | booleano | por omisión: false | Tolera errores de escritura en q (uno por palabra de 4 a 7 letras, dos en palabras más largas; las de 3 letras o menos deben ser exactas). Cada resultado indica match: exact o approximate. |
limiten la consulta | entero | de 1 a 500 por omisión: 50 | Tamaño de página (1–500, 50 por omisión). No existe un valor "sin límite": para obtener todos los resultados, sigue next_cursor hasta que sea null. |
cursoren la consulta | texto | — | Valor opaco de next_cursor de la página anterior, enviado tal cual. Solo vale para la versión del dato que lo emitió (si no, 400 /errors/cursor-expired). |
Ejemplo
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/settlements?q=roma&limit=2"const url = new URL("https://colonix.silgaru.mx/v1/settlements");url.searchParams.set("q", "roma");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/settlements", params={"q": "roma", "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/settlements?" . http_build_query(["q" => "roma", "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": [ { "id": "09015-0947", "postal_code": "06700", "name": "Roma Norte", "type": "Colonia", "zone": "Urbano", "city": "Ciudad de México", "state": { "id": "09", "name": "Ciudad de México" }, "municipality": { "id": "015", "name": "Cuauhtémoc" } }, { "id": "09015-0966", "postal_code": "06760", "name": "Roma Sur", "type": "Colonia", "zone": "Urbano", "city": "Ciudad de México", "state": { "id": "09", "name": "Ciudad de México" }, "municipality": { "id": "015", "name": "Cuauhtémoc" } } ], "next_cursor": "MjAyNi4xMS4wNS0zNmE3ODIzYnw1MzQ", "data_version": "2026.11.05-36a7823b"}Campos
| Campo | Tipo | Descripción |
|---|---|---|
data | lista de objetos | |
data[].id | texto | Clave EEMMM-NNNN (estado, municipio, id SEPOMEX): no cambia cuando SEPOMEX le cambia el nombre o lo mueve a otro código postal; otro municipio es otra clave |
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[].name | texto | Nombre del asentamiento |
data[].type | texto | Tipo de asentamiento |
data[].zone | texto | ZonaUrbanoRuralSemiurbano |
data[].city | texto o null | Ciudad, o null si no tiene |
data[].state | objeto | Elemento de un catálogo. |
data[].municipality | objeto | Elemento de un catálogo. |
data[].matchno siempre viene | texto | Solo con fuzzy=true: si el resultado coincide con q exactamente o con erroresexactapproximate |
next_cursor | texto o null | Cursor opaco de la página siguiente; null si no hay más resultados. |
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