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.
Qué consultas se paginan
Section titled “Qué consultas se paginan”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 |
Cómo paginar
Section titled “Cómo paginar”- Pide la primera página.
limitva de 1 a 500 (50 si no lo mandas). - Si la respuesta trae un
next_cursor, repite la misma petición agregandocursor=<next_cursor>. - Cuando
next_cursorseanull, 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"{ "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"{ "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 paginadaasync 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);import osimport requests
def todas(url, params): """Devuelve todos los resultados de una consulta paginada.""" resultados, cursor = [], None while True: pagina = {**params, "limit": 500} if cursor: pagina["cursor"] = cursor res = requests.get( url, params=pagina, headers={"x-api-key": os.environ["COLONIX_API_KEY"]}, timeout=10, ) data = res.json() if not res.ok: raise RuntimeError(f"{data['type']}: {data['detail']}") resultados += data["data"] cursor = data["next_cursor"] if not cursor: return resultados
romas = todas("https://colonix.silgaru.mx/v1/settlements", {"q": "roma"})print(len(romas))Cada página cuenta como una consulta: con limit=500 gastas menos.
Los cursores
Section titled “Los cursores”- 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
400concursor-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.
La versión del dato
Section titled “La versión del dato”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.
Caché y revalidación
Section titled “Caché y revalidación”Las respuestas correctas traen:
Cache-Control: public, max-age=86400, stale-while-revalidate=604800, stale-if-error=604800Es 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/06700Cache-Control: public, max-age=86400, stale-while-revalidate=604800, stale-if-error=604800ETag: "2026.11.05-36a7823b+10"X-Data-Version: 2026.11.05-36a7823bSi 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.
Mantener tu copia al día
Section titled “Mantener tu copia al día”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.
© 2026 Silgaru