Ir al contenido

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.

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.

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/autocomplete

Este 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.

servidor.mjs
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.

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.

formulario.html
<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, nunca innerHTML. Los nombres vienen de un catálogo, pero así tu página no interpreta nada como HTML.

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)

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).

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=3

Sugiere 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.

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.