Ir al contenido

Paginación y versión del dato

Algunas búsquedas traen cientos o miles de resultados: Colonix te los entrega por páginas y tú pides la siguiente cuando la necesitas. Además, cada respuesta dice con qué versión del catálogo se respondió, para que sepas cuándo cambió algo y no vuelvas a pedir lo que ya tienes.

Paginadas (con limit y cursor) Sin paginar
GET /v1/postal-codes (listado y búsqueda de códigos postales) GET /v1/postal-codes/{code}: siempre todos sus asentamientos
GET /v1/settlements (búsqueda de asentamientos) GET /v1/postal-codes/{code}/history: todo el historial del código
GET /v1/municipalities/{state}/{municipality}/settlements GET /v1/autocomplete: las mejores sugerencias, hasta limit (1–20)
GET /v1/changes GET /v1/nearby: los más cercanos, hasta limit (1–50)
GET /v1/sat/discrepancies Catálogos: estados, municipios de un estado y tipos de asentamiento
GET /v1/postal-codes/batch: hasta 100 códigos por petición
  1. Pide la primera página. limit va de 1 a 500 (50 si no lo mandas).
  2. Si la respuesta trae un next_cursor, repite la misma petición agregando cursor=<next_cursor>.
  3. Cuando next_cursor sea null, ya tienes todo.

No hay un valor de limit “sin límite”: para obtener todos los resultados, sigue los cursores. Un data vacío con next_cursor: null significa que no hay resultados.

Por ejemplo, los asentamientos que se llaman “Roma”, de dos en dos:

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/settlements?q=roma&limit=2"
Primera página
{
"data": [
{ "id": "09015-0947", "postal_code": "06700", "name": "Roma Norte", "type": "Colonia", "…": "…" },
{ "id": "09015-0966", "postal_code": "06760", "name": "Roma Sur", "type": "Colonia", "…": "…" }
],
"next_cursor": "MjAyNi4xMS4wNS0zNmE3ODIzYnw1MzQ",
"data_version": "2026.11.05-36a7823b"
}
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/settlements?q=roma&limit=2&cursor=MjAyNi4xMS4wNS0zNmE3ODIzYnw1MzQ"
Segunda página
{
"data": [
{ "id": "02002-0113", "postal_code": "21250", "name": "Roma", "type": "Colonia", "…": "…" },
{ "id": "02002-2706", "postal_code": "21355", "name": "Quinta Roma (Quinta Córdova)", "type": "Fraccionamiento", "…": "…" }
],
"next_cursor": "MjAyNi4xMS4wNS0zNmE3ODIzYnwzNDI0",
"data_version": "2026.11.05-36a7823b"
}

Para recorrer todas las páginas:

// Devuelve todos los resultados de una consulta paginada
async function todas(url) {
const resultados = [];
let cursor = null;
do {
const pagina = new URL(url);
pagina.searchParams.set("limit", "500");
if (cursor) pagina.searchParams.set("cursor", cursor);
const res = await fetch(pagina, {
headers: { "x-api-key": process.env.COLONIX_API_KEY },
signal: AbortSignal.timeout(10000),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.type}: ${data.detail}`);
resultados.push(...data.data);
cursor = data.next_cursor;
} while (cursor);
return resultados;
}
const romas = await todas("https://colonix.silgaru.mx/v1/settlements?q=roma");
console.log(romas.length);

Cada página cuenta como una consulta: con limit=500 gastas menos.

  • Son opacos. Mándalos tal cual los recibiste; no los armes, no los cambies ni dependas de lo que contienen.
  • Solo valen para la versión del dato que los emitió. Si el catálogo se actualiza mientras recorres las páginas, el siguiente cursor responde 400 con cursor-expired: vuelve a empezar desde la primera página. Así nunca mezclas resultados de dos versiones.
  • No los guardes para después. Sirven para recorrer una consulta en el momento, no como marcador entre días.

El catálogo se revisa cada semana y, si algo cambió en alguna de las fuentes, se publica una versión nueva. Cada respuesta correcta dice con qué versión se respondió, en dos lugares con el mismo valor:

Dónde Ejemplo
Campo data_version del cuerpo "data_version": "2026.11.05-36a7823b"
Encabezado X-Data-Version X-Data-Version: 2026.11.05-36a7823b

Trátala como un texto opaco: compárala solo por igualdad (“¿cambió desde la última vez?”). No la ordenes ni dependas de su forma: dos versiones pueden empezar con la misma fecha.

Para saber cuál es la versión vigente sin consultar un código postal, usa GET /v1/meta: además de data_version, trae la fecha de cada fuente y los totales del catálogo.

Las respuestas correctas traen:

Cache-Control: public, max-age=86400, stale-while-revalidate=604800, stale-if-error=604800

Es decir: puedes guardarlas un día y, pasado ese día, seguir usándolas hasta una semana más mientras las revalidas en segundo plano, o si en ese momento la API no responde (stale-if-error; ver Si la API no responde). Para revalidar, manda el ETag que recibiste en If-None-Match:

curl -i -H "x-api-key: TU_LLAVE" -H 'If-None-Match: "2026.11.05-36a7823b+10"' \
https://colonix.silgaru.mx/v1/postal-codes/06700
304 Not Modified
Cache-Control: public, max-age=86400, stale-while-revalidate=604800, stale-if-error=604800
ETag: "2026.11.05-36a7823b+10"
X-Data-Version: 2026.11.05-36a7823b

Si la respuesta no cambió, recibes 304 sin cuerpo: sigue usando lo que tienes. Si cambió, recibes 200 con la respuesta nueva y su ETag nuevo. El 304 cuenta como consulta, pero no trae el cuerpo.

El ETag lleva la versión del dato y la de las reglas con que se unen las colonias del SAT y de SEPOMEX (cómo funciona): cambia si cambia cualquiera de las dos. Trátalo también como opaco; para saber la versión del dato, lee X-Data-Version.

Si guardas códigos postales o colonias en tu base de datos, no necesitas volver a consultarlos todos cuando cambia la versión: GET /v1/changes?since=<tu data_version> te da solo lo que se agregó, se eliminó o se modificó desde tu versión (plan Negocio). Para un solo código postal, GET /v1/postal-codes/{code}/history da todos sus cambios en cualquier plan.