Ir al contenido

Autocompletado de direcciones

GET/v1/autocompleteTodos los planes

¿Qué hace?

Sugiere asentamientos mientras tu usuario escribe, aunque se equivoque, para que elija el correcto en lugar de escribirlo.

q se lee como la validación lee el nombre de una colonia: entiende las abreviaturas comunes ("col", "nte", "fracc", "sta"), el tipo de asentamiento al inicio ("colonia roma norte") y un ordinal en cualquier forma ("3a", "3ra", "tercera" y "III"). Si q solo tiene dígitos, sugiere por el inicio del código postal; los dígitos junto con palabras ("06700 roma") dejan los asentamientos de los códigos postales que empiezan con ellos.

Orden: primero los asentamientos urbanos de las zonas metropolitanas más grandes (por número de asentamientos; los municipios centrales antes que los exteriores) y, dentro de cada tamaño, el nombre exacto, los que empiezan con q y luego el resto, primero los más cortos. Los tipos de asentamiento que no son vivienda (Equipamiento, Aeropuerto, Zona industrial, militar, naval, federal o comercial, Puerto, Campamento) van al final. Filtra por state y municipality para sugerir solo cerca de tu usuario.

Sin paginar: regresa las mejores limit sugerencias. Con fuzzy=true, las sugerencias con errores de escritura van después de las exactas. Llámalo desde tu servidor y espera una pausa al escribir (debounce): cada petición cuenta.

La petición

ParámetroTipoValores aceptadosDescripción
qen la consultaobligatoriotexto
de 2 a 100 caracteres
Texto que escribe el usuario (de 2 a 100 caracteres, hasta 12 palabras).
stateen la consultatexto
2 dígitos
Clave INEGI del estado, 2 dígitos (ver /v1/states).
municipalityen la consultatexto
3 dígitos
Clave INEGI del municipio, 3 dígitos; requiere state.
fuzzyen la consultabooleano
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 consultaentero
de 1 a 20
por omisión: 10
Número máximo de sugerencias (1–20).

Ejemplo

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/autocomplete?q=roma%20nor&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": [
{
"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"
}
}
],
"data_version": "2026.11.05-36a7823b"
}

Campos

CampoTipoDescripción
datalista de objetos
data[].idtextoClave 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_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[].nametextoNombre del asentamiento
data[].typetextoTipo de asentamiento
data[].zonetextoZona
UrbanoRuralSemiurbano
data[].citytexto o nullCiudad, o null si no tiene
data[].stateobjetoElemento de un catálogo.
data[].municipalityobjetoElemento de un catálogo.
data[].matchno siempre vienetextoSolo con fuzzy=true: si el resultado coincide con q exactamente o con errores
exactapproximate
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.