Autocompletar la colonia en un formulario
Tu usuario empieza a escribir su colonia y el formulario le sugiere las correctas, con su código postal, aunque se equivoque en una letra. Así no llegan direcciones mal escritas a tus envíos ni a tus facturas. Esta guía arma ese formulario sin gastar una consulta por cada tecla.
Necesitas: cualquier plan, también el Gratis.
Dos formas de llenar la dirección
Section titled “Dos formas de llenar la dirección”| Si tu usuario escribe primero | Consulta | Consultas que gasta |
|---|---|---|
| El código postal (recomendado) | GET /v1/postal-codes/{code} y le muestras sus colonias en una lista para elegir |
Una |
| La colonia | GET /v1/autocomplete mientras escribe, con una pausa |
Una por cada pausa |
Pedir primero el código postal es lo más rápido y lo más barato: casi todos lo saben de memoria y un
código postal tiene pocas colonias (el 03100 tiene dos: Del Valle Centro e Insurgentes San Borja).
El autocompletado sirve cuando no lo saben o para corregir la colonia.
La llave se queda en tu servidor
Section titled “La llave se queda en tu servidor”El navegador nunca llama a Colonix directamente: tu página llama a tu servidor y tu servidor llama a Colonix con la llave. Así nadie puede copiarla desde el navegador.
Navegador → tu servidor (/api/colonias?q=…) → colonix.silgaru.mx/v1/autocompleteEste servidor mínimo en Node 18 o más reciente reenvía la búsqueda y guarda cada respuesta un día,
como indica Cache-Control: si dos usuarios escriben lo mismo, la segunda no gasta consulta.
import { createServer } from "node:http";
const LLAVE = process.env.COLONIX_API_KEY;const UN_DIA = 24 * 60 * 60 * 1000;const cache = new Map(); // texto buscado → { cuando, cuerpo }
createServer(async (req, res) => { const url = new URL(req.url, "http://localhost"); const q = (url.searchParams.get("q") ?? "").trim().toLowerCase(); if (url.pathname !== "/api/colonias" || q.length < 3) { res.writeHead(400).end(); return; }
let guardado = cache.get(q); if (!guardado || Date.now() - guardado.cuando > UN_DIA) { const colonix = new URL("https://colonix.silgaru.mx/v1/autocomplete"); colonix.searchParams.set("q", q); colonix.searchParams.set("fuzzy", "true"); colonix.searchParams.set("limit", "8"); const r = await fetch(colonix, { headers: { "x-api-key": LLAVE }, signal: AbortSignal.timeout(5000), }); if (!r.ok) { res.writeHead(502).end(); return; } guardado = { cuando: Date.now(), cuerpo: await r.text() }; cache.set(q, guardado); } res.writeHead(200, { "content-type": "application/json" }).end(guardado.cuerpo);}).listen(3000);En producción usa el caché y el marco de tu aplicación (Express, Laravel, Django…); lo importante es que la llave no salga del servidor y que repitas lo menos posible la misma búsqueda.
La pausa al escribir
Section titled “La pausa al escribir”Si consultas en cada tecla, escribir “insurgentes” gasta 11 consultas. Con una pausa, solo consultas cuando el usuario deja de teclear un momento: normalmente una o dos por colonia.
<input id="colonia" autocomplete="off" placeholder="Colonia" /><ul id="sugerencias"></ul>
<script type="module"> const campo = document.getElementById("colonia"); const lista = document.getElementById("sugerencias"); let espera = null; let enCurso = null;
campo.addEventListener("input", () => { clearTimeout(espera); const q = campo.value.trim(); if (q.length < 3) { lista.replaceChildren(); return; } // Solo consulta cuando el usuario deja de escribir 300 ms espera = setTimeout(() => buscar(q), 300); });
async function buscar(q) { enCurso?.abort(); // descarta la búsqueda anterior si sigue en camino enCurso = new AbortController(); try { const res = await fetch(`/api/colonias?q=${encodeURIComponent(q)}`, { signal: enCurso.signal }); if (!res.ok) return; const { data } = await res.json(); lista.replaceChildren( ...data.map((s) => { const li = document.createElement("li"); li.textContent = `${s.name}, ${s.postal_code} · ${s.municipality.name}, ${s.state.name}`; li.addEventListener("click", () => { campo.value = s.name; // Llena también el código postal, el municipio y el estado con s.postal_code, etc. lista.replaceChildren(); }); return li; }), ); } catch (e) { if (e.name !== "AbortError") throw e; } }</script>Tres detalles que hacen la diferencia:
- Desde 3 letras. La API acepta 2, pero con 3 las sugerencias ya son útiles y gastas menos.
- Descarta lo viejo. Si el usuario sigue escribiendo, una respuesta lenta de una búsqueda
anterior no debe tapar la nueva: por eso
AbortController. textContent, nuncainnerHTML. Los nombres vienen de un catálogo, pero así tu página no interpreta nada como HTML.
Cómo lee lo que escribe tu usuario
Section titled “Cómo lee lo que escribe tu usuario”Tu usuario no escribe la colonia como el catálogo de SEPOMEX, y no tiene por qué. El autocompletado lee la búsqueda como la lee la validación:
| Si escribe | Entiende | Primera sugerencia |
|---|---|---|
col roma |
El tipo al inicio no cuenta | Roma Sur y Roma Norte (06700), de Cuauhtémoc |
roma nte |
Las abreviaturas comunes (nte, col, fracc, sta…) |
Roma Norte (06700) |
lomas chapultepec 3a |
Los artículos que faltan y el ordinal en cualquier forma (3a, 3ra, tercera, III) |
Lomas de Chapultepec III Sección (11000) |
06700 roma |
Un código postal junto con palabras: solo los de ese código (o los que empiezan con esos dígitos) | Roma Norte (06700) |
En qué orden sugiere
Section titled “En qué orden sugiere”Sin filtros, primero van las colonias urbanas de las zonas metropolitanas más grandes (la Ciudad de México, Monterrey y Guadalajara, en ese orden, y luego las demás por tamaño), con los municipios centrales antes que los de alrededor; después, lo urbano fuera de una zona metropolitana y al final lo rural. Dentro de cada grupo, el nombre exacto, luego los que empiezan con lo escrito y después el resto, primero los más cortos. Así “polanco” sugiere Polanco I, V y II Sección de Miguel Hidalgo antes que cualquier otro Polanco del país.
Los tipos que no son vivienda (Equipamiento, Aeropuerto, Zona industrial, militar, naval, federal o comercial, Puerto y Campamento) van al final de la lista: siguen apareciendo si tu usuario los busca, pero no tapan a las colonias.
Si tu usuario no vive en la Ciudad de México, el orden nacional no le sirve: manda su estado y
municipio. “centro” sin filtros empieza por el Barrio Centro de Milpa Alta (12400); con
state=14&municipality=039 empieza por Guadalajara Centro (44100), Centro Barranquitas (44280)
y Obrera Centro (44140).
Errores de dedo
Section titled “Errores de dedo”Con fuzzy=true, las sugerencias toleran un error por palabra (dos en palabras largas). Por ejemplo,
“insurjentes” en la Ciudad de México (state=09):
curl -G -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/autocomplete \ --data-urlencode "q=insurjentes" -d state=09 -d fuzzy=true -d limit=3Sugiere Insurgentes (09750), Insurgentes Mixcoac (03920) y Tepeyac Insurgentes (07020). Las
coincidencias exactas siempre van antes que las aproximadas, y las palabras de tres letras o menos
tienen que estar bien escritas.
Si el usuario escribe solo números, el autocompletado sugiere por el inicio del código postal.
Antes de guardar, valida
Section titled “Antes de guardar, valida”El autocompletado ayuda a escribir, pero el usuario puede ignorarlo. Antes de guardar la dirección,
valida el par código postal + colonia una vez con GET /v1/validate/postal-code-settlement: te dice
si es correcto y, si no, qué colonia quiso decir o en qué código postal está. Detalle en
Validar una dirección para CFDI 4.0.
Guarda el código postal como texto, nunca como número. 685 códigos postales empiezan con cero
(todos de la Ciudad de México, del 01000 al 09970), y un campo numérico, Excel o una hoja de
cálculo convierten 09700 en 9700. Si a Colonix le llega un código de 4 dígitos, responde 400
y, cuando existe el mismo código con un cero adelante, lo sugiere en detail (“Did you mean
09700?”). No lo corrige solo: arréglalo en tu base de datos o en tu archivo.
© 2026 Silgaru