Primeros pasos con la API de códigos postales de México
Colonix te dice qué colonias tiene un código postal, revisa que una dirección esté bien escrita y te da las claves del SAT que pide una factura. Tú le mandas un código postal, el nombre de una colonia o unas coordenadas, y te responde con los datos oficiales de SEPOMEX, el SAT, el INEGI y CONAPO, ya cruzados y revisados.
Es una API REST que responde en JSON. En esta página haces tu primera consulta y conoces las reglas que valen para todas las demás.
Lo que necesitas
Section titled “Lo que necesitas”- Una llave. La creas en tu cuenta de Colonix y empieza con
clx_. Va en el encabezadox-api-keyde cada petición. - Cualquier cliente HTTP:
curlen tu terminal, o el lenguaje de tu aplicación.
Tu primera consulta
Section titled “Tu primera consulta”Pide los datos del código postal 06700, en la Ciudad de México. Copia el ejemplo, cambia
TU_LLAVE por tu llave y ejecútalo:
curl -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/postal-codes/06700Funciona igual en macOS, Linux y Windows. En Windows PowerShell escribe curl.exe en lugar
de curl.
// Node 18 o más reciente: guárdalo como consulta.mjs y ejecuta `node consulta.mjs`const res = await fetch("https://colonix.silgaru.mx/v1/postal-codes/06700", { headers: { "x-api-key": "TU_LLAVE" }, signal: AbortSignal.timeout(5000),});const data = await res.json();if (!res.ok) throw new Error(`${data.type}: ${data.detail}`);
console.log(data.settlements.map((s) => s.name));# Requiere requests (pip install requests): guárdalo como consulta.py y ejecuta `python consulta.py`import requests
res = requests.get( "https://colonix.silgaru.mx/v1/postal-codes/06700", headers={"x-api-key": "TU_LLAVE"}, timeout=5,)data = res.json()if not res.ok: raise RuntimeError(f"{data['type']}: {data['detail']}")
print([s["name"] for s in data["settlements"]])<?php// Guárdalo como consulta.php y ejecuta `php consulta.php`$ch = curl_init("https://colonix.silgaru.mx/v1/postal-codes/06700");curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["x-api-key: TU_LLAVE"], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 5,]);$data = json_decode(curl_exec($ch), true);if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) { throw new RuntimeException("{$data['type']}: {$data['detail']}");}
print_r(array_column($data["settlements"], "name"));La respuesta
Section titled “La respuesta”Recibes el estado, el municipio y todas las colonias de ese código postal. El 06700 tiene una sola, la Roma Norte:
Content-Type: application/json; charset=utf-8Cache-Control: public, max-age=86400, stale-while-revalidate=604800, stale-if-error=604800ETag: "2026.11.05-36a7823b+10"X-Data-Version: 2026.11.05-36a7823b{ "postal_code": "06700", "state": { "id": "09", "name": "Ciudad de México" }, "municipality": { "id": "015", "name": "Cuauhtémoc" }, "office": "06401", "settlement_count": 1, "settlements": [ { "id": "09015-0947", "name": "Roma Norte", "type": "Colonia", "zone": "Urbano", "city": "Ciudad de México" } ], "data_version": "2026.11.05-36a7823b"}| Campo | Qué es |
|---|---|
postal_code |
El código postal, siempre con 5 dígitos (texto, no número: conserva el cero inicial). |
state |
Estado: id es su clave de 2 dígitos del INEGI y name, su nombre oficial. |
municipality |
Municipio o alcaldía: id es su clave de 3 dígitos dentro del estado. |
office |
Oficina postal que atiende el código. |
settlement_count |
Cuántos asentamientos tiene el código postal. |
settlements |
Los asentamientos (colonias, fraccionamientos, barrios, rancherías…), todos, sin paginar. |
settlements[].id |
Clave del asentamiento: no cambia si SEPOMEX le corrige el nombre o lo mueve a otro código postal. Guárdala junto con el nombre y el código postal (por qué). |
settlements[].type |
Tipo de asentamiento, como lo publica SEPOMEX: Colonia, Fraccionamiento, Barrio… |
settlements[].zone |
Urbano, Rural o Semiurbano. |
settlements[].city |
Ciudad, o null si el asentamiento no pertenece a una. |
data_version |
Versión del dato con la que se respondió (también en X-Data-Version). |
Los nombres de los campos están en inglés y los valores del catálogo, en español, tal como los publican las fuentes oficiales.
Reglas que valen para toda la API
Section titled “Reglas que valen para toda la API”Dirección y versión. Todas las peticiones van a https://colonix.silgaru.mx/v1/… por HTTPS
(TLS 1.2 o más reciente); es la única dirección de la API, y cualquier otra responde 421. Dentro de
/v1 los cambios solo agregan: endpoints, parámetros o campos
opcionales nuevos. Tu código debe ignorar los campos que no conozca; un cambio incompatible
llegaría en /v2.
Métodos. Solo GET y HEAD. Cualquier otro método responde 405.
Parámetros. Cada endpoint acepta solo sus parámetros, una vez cada uno. Uno que no existe, o
que es de otro endpoint, responde 400 con unknown-parameter y no se ignora: así un nombre mal
escrito no te devuelve resultados sin filtrar. Ver Errores.
Formato. Las respuestas son JSON en UTF-8. Las fechas siguen ISO 8601 y las coordenadas son grados decimales (WGS 84).
Errores. Cuando algo sale mal recibes un estado HTTP de error y un cuerpo
application/problem+json (RFC 9457). Decide con el
campo type, que no cambia; title y detail son para personas. Por ejemplo, sin llave:
Content-Type: application/problem+jsonCache-Control: no-store{ "type": "/errors/missing-api-key", "title": "Missing API key", "status": 401, "detail": "Send your key in the x-api-key header."}Consumo. Cada respuesta correcta (estado 2xx o 304) cuenta como una consulta de tu plan.
Las respuestas con error no cuentan, incluido el 404 de un código postal que no existe. La
consulta en lote cuenta una por código postal.
Versión del dato. El catálogo se revisa cada semana. Cada respuesta dice con qué versión se
respondió (data_version y X-Data-Version), y puedes guardarla en caché el tiempo que indica
Cache-Control.
© 2026 Silgaru