Ir al contenido

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.

  • Una llave. La creas en tu cuenta de Colonix y empieza con clx_. Va en el encabezado x-api-key de cada petición.
  • Cualquier cliente HTTP: curl en tu terminal, o el lenguaje de tu aplicación.

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

Funciona igual en macOS, Linux y Windows. En Windows PowerShell escribe curl.exe en lugar de curl.

Recibes el estado, el municipio y todas las colonias de ese código postal. El 06700 tiene una sola, la Roma Norte:

200 OK
Content-Type: application/json; charset=utf-8
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
{
"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.

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:

401 Unauthorized
Content-Type: application/problem+json
Cache-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.