Código postal con todos sus asentamientos
/v1/postal-codes/{code}Todos los planes¿Qué hace?
Todo sobre un código postal: su estado, su municipio y todos sus asentamientos (colonias, fraccionamientos, barrios...). Úsalo para llenar un formulario de dirección en cuanto el usuario escribe su código postal.
Regresa todos los asentamientos (sin paginar; el código postal más grande tiene 291). Bloques opcionales con include: location (punto de referencia), metro (zona metropolitana) y sat (claves del SAT para CFDI 4.0) en los planes de pago; los códigos postales de demostración dan los tres bloques en todos los planes. Un código postal que no existe responde 404 /errors/postal-code-not-found, que no cuenta para tu cuota.
Con as_of obtienes el código postal como lo tenía SEPOMEX en una fecha pasada: sus asentamientos de ese día, según el archivo de SEPOMEX más reciente de esa fecha o anterior (as_of.sepomex_date). Sirve para revisar una dirección que se capturó o se facturó entonces. Las fechas van desde history_since (ver /v1/meta) hasta hoy; una anterior responde 400 /errors/as-of-out-of-range, porque no hay registro de lo que decía el catálogo antes. Un código postal que no existía en esa fecha responde 404. include no se combina con as_of.
La petición
| Parámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
codeen la rutaobligatorio | texto | 5 dígitos | Código postal de 5 dígitos. |
fieldsen la consulta | lista de textoseparados por comas | postal_codestatemunicipalityofficesettlement_countsettlementsdata_versionsatlocationmetro_areaas_of | Campos de primer nivel a regresar, separados por comas. Permitidos: postal_code, state, municipality, office, settlement_count, settlements, data_version, sat (con include=sat), location (con include=location), metro_area (con include=metro) y as_of (con as_of). |
includeen la consulta | lista de textoseparados por comas | satlocationmetro | Bloques opcionales a agregar, separados por comas (sat,location,metro). sat: datos del SAT para CFDI 4.0; requiere un plan de pago. location: ubicación de referencia del código postal; requiere un plan de pago. metro: zona metropolitana del código postal; requiere un plan de pago. Los códigos postales de demostración en /v1/postal-codes/{code} dan los tres bloques en todos los planes. |
as_ofen la consulta | fecha | — | Fecha (AAAA-MM-DD) para obtener el código postal como lo tenía SEPOMEX ese día, desde history_since (ver /v1/meta) hasta hoy en la Ciudad de México. No se combina con include. |
Ejemplo
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/postal-codes/06700"const url = new URL("https://colonix.silgaru.mx/v1/postal-codes/06700");
const res = await fetch(url, { headers: { "x-api-key": process.env.COLONIX_API_KEY }, signal: AbortSignal.timeout(5000),});const data = await res.json();if (!res.ok) throw new Error(`${data.type}: ${data.detail}`);
console.log(data);import osimport requests
res = requests.get( "https://colonix.silgaru.mx/v1/postal-codes/06700", headers={"x-api-key": os.environ["COLONIX_API_KEY"]}, timeout=5,)data = res.json()if not res.ok: raise RuntimeError(f"{data['type']}: {data['detail']}")
print(data)<?php$url = "https://colonix.silgaru.mx/v1/postal-codes/06700";$ch = curl_init($url);curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("COLONIX_API_KEY")], 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($data);Cambia TU_LLAVE por tu llave; en los lenguajes, se lee de la variable de entorno COLONIX_API_KEY. Esta petición es la que produjo la respuesta de abajo.
La respuesta
Respuesta real a la petición del ejemplo. Viene con los encabezados ETag, X-Data-Version, Cache-Control.
{ "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"}Campos
| Campo | Tipo | Descripción |
|---|---|---|
postal_code | texto | Código postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700). |
state | objeto | Elemento de un catálogo. |
state.id | texto | Clave oficial |
state.name | texto | Nombre |
municipality | objeto | Elemento de un catálogo. |
municipality.id | texto | Clave oficial |
municipality.name | texto | Nombre |
office | texto | Oficina postal que atiende el código |
settlement_count | entero | Número de asentamientos |
satno siempre viene | objeto | Datos del SAT de un código postal (CFDI 4.0 y Carta Porte). |
sat.in_sat | booleano | El código postal está en c_CodigoPostal (válido para CFDI) |
sat.in_sepomex | booleano | El código postal está en el catálogo de SEPOMEX |
sat.state | objeto o null | Clave del estado en el SAT y en el INEGI, o null si no está en el SAT |
sat.municipality | objeto o null | Clave del SAT con su nombre, o null |
sat.locality | objeto o null | Clave del SAT con su nombre, o null |
sat.border_stimulus | texto o null | Estímulo fiscal de la región fronteriza: north (norte), south (sur) o null. El código postal no basta para aplicarlo: ver border_stimulus_decreenorthsouth |
sat.border_stimulus_decree | objeto o null | Vigencia del decreto del estímulo fiscal de la región fronteriza, o null si el código postal no está en una región fronteriza. El contribuyente debe presentar un aviso ante el SAT (requires_sat_notice) y cumplir sus requisitos; después de valid_until el estímulo deja de aplicar, salvo que un decreto nuevo lo prorrogue |
sat.time_zone | objeto o null | Huso horario como lo publica el SAT, más el huso real (iana y sus diferencias con UTC), o null si no está en el SAT. En las franjas fronterizas de Chihuahua el SAT sigue la letra de la ley de husos horarios y difiere de la hora que se usa en la práctica (matches_sat: false) |
sat.settlements | lista de objetos | Colonias del SAT (c_Colonia) del código postal |
sat.settlements_missing_in_sat | lista de objetos | Asentamientos de SEPOMEX del código postal sin clave del SAT: ninguna colonia del SAT tiene el mismo nombre ni uno equivalente, o las que lo tienen ya son de otro asentamiento con ese nombre |
sat.sat_revision | objeto | Versión del archivo de catálogos del SAT que se usó. |
locationno siempre viene | objeto o null | Con include=location: ubicación de referencia, o null si no hay |
location.lat | número | Latitud (WGS84), con 6 decimales como máximo |
location.lon | número | Longitud (WGS84), con 6 decimales como máximo |
location.bbox | lista de número o null | [oeste, sur, este, norte] en grados, o null para una localidad |
location.precision | texto | De dónde sale el puntopostal_code_polygonlocality_centroidmunicipality_centroid |
location.source_date | fecha | Fecha del dato de la fuente |
metro_areano siempre viene | objeto o null | Con include=metro: zona metropolitana del municipio, o null si no está en ninguna |
metro_area.id | texto | Clave oficial de la metrópoli |
metro_area.name | texto | Nombre de la metrópoli |
metro_area.type | texto | Tipo tal como se publica (en español)Zona metropolitanaMetrópoli municipalZona conurbada |
metro_area.municipality_role | texto | Si el municipio del código postal es central o exterior en la metrópolicentralexterior |
settlements | lista de objetos | Asentamientos del código postal |
settlements[].id | texto | Clave del asentamiento: no cambia cuando SEPOMEX le cambia el nombre o lo mueve a otro código postal, así que guarda también el nombre y el código postal |
settlements[].name | texto | Nombre del asentamiento |
settlements[].type | texto | Tipo de asentamiento |
settlements[].zone | texto | ZonaUrbanoRuralSemiurbano |
settlements[].city | texto o null | Ciudad, o null si no tiene |
data_version | texto | Versión del dato |
Campos con as_of
Un código postal como lo tenía SEPOMEX en la fecha as_of.
| Campo | Tipo | Descripción |
|---|---|---|
postal_code | texto | Código postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700). |
state | objeto | Elemento de un catálogo. |
state.id | texto | Clave oficial |
state.name | texto | Nombre |
municipality | objeto | Elemento de un catálogo. |
municipality.id | texto | Clave oficial |
municipality.name | texto | Nombre |
office | texto | Oficina postal que atendía el código |
settlement_count | entero | Número de asentamientos en esa fecha |
settlements | lista de objetos | Asentamientos en esa fecha, por nombre |
settlements[].id | texto | Clave del asentamiento |
settlements[].name | texto | Nombre del asentamiento |
settlements[].type | texto | Tipo de asentamiento |
settlements[].zone | texto | ZonaUrbanoRuralSemiurbano |
settlements[].city | texto o null | Ciudad, o null si no tiene |
as_of | objeto | En qué se basa la respuesta |
as_of.date | fecha | La fecha que pediste |
as_of.sepomex_date | fecha | Fecha del archivo de SEPOMEX que da la respuesta: el más reciente de esa fecha o anterior |
as_of.data_version | texto | Versión del dato que publicó ese archivo |
data_version | texto | Versión del dato de esta respuesta (la vigente) |
Errores
Todos en formato application/problem+json; ninguno cuenta para tu cuota. Qué hacer con cada uno: Errores.
| Estado | Cuándo |
|---|---|
400 | Parámetro inválido o repetido (/errors/invalid-parameter), un parámetro que el endpoint no tiene (/errors/unknown-parameter), cursor vencido (/errors/cursor-expired), versión del dato desconocida (/errors/unknown-version) o as_of fuera del historial registrado (/errors/as-of-out-of-range). |
401 | Credenciales faltantes (/errors/missing-api-key) o inválidas (/errors/invalid-api-key). |
403 | Llave suspendida (/errors/api-key-suspended) o endpoint fuera de tu plan (/errors/plan-not-allowed). |
404 | El recurso no existe (/errors/postal-code-not-found, /errors/state-not-found, /errors/municipality-not-found, /errors/location-not-covered o /errors/route-not-found). No cuenta para tu cuota. |
429 | Se alcanzó la cuota mensual (/errors/quota-exceeded) o el límite por minuto (/errors/rate-limited). La respuesta del límite por minuto trae el mismo cuerpo, pero con Content-Type: application/json. |
5XX | Error inesperado (/errors/internal-error) o servicio no disponible por un momento (503, que puede llegar sin cuerpo). Reintenta unas cuantas veces, esperando cada vez más. |
© 2026 Silgaru