Protocolo público · versión 2.2.0
Este documento describe exactamente cómo se solicitan, conservan, limpian, transforman y publican los datos. El objetivo es que otra persona pueda repetir el proceso, verificar una respuesta original y obtener el mismo resultado.
HidroCol · Observatorio del agua y la energía en Colombia
HidroCol es un observatorio académico público de la reserva energética del Sistema Interconectado Nacional (SIN), el volumen útil de los embalses y la generación eléctrica observada en Colombia. Permite consultar históricos, fechas de corte, cobertura y trazabilidad en vistas y una API pública de lectura.
Las series energéticas proceden de la API de XM. Sus respuestas originales, huellas SHA-256 y revisiones se conservan para comprobar las transformaciones. Las consultas almacenadas permiten explorar el histórico aunque la fuente externa esté temporalmente fuera de servicio.
El módulo de agua potable de Medellín se mantiene separado de la reserva energética. Las lecturas oficiales se identifican con su fuente y los datos faltantes no se estiman. Las alertas son académicas y exploratorias: HidroCol no es una autoridad de alertas ni reemplaza las publicaciones de XM/EPM.
Para citar una consulta, use la citación sugerida y conserve la fecha observada, la fuente y el lote original cuando esté disponible. Este protocolo publica las fórmulas y limitaciones para facilitar su revisión.
El trabajador consulta a las 06:00 en America/Bogota, sin deriva; revisa siete días y recupera fechas pendientes. Cada 7 días vuelve a consultar los últimos 90 días completos. Los parciales de XM esperan el siguiente horario; solo los fallos reales se reintentan, hasta 3 veces, con espera exponencial desde 60 minutos y tope de 360 minutos.
Envía solicitudes POST deterministas a la API de XM.
Guarda la respuesta gzip y calcula su huella SHA-256.
Convierte fechas y decimales; no imputa valores faltantes.
Aplica fórmulas explícitas de porcentaje y generación.
Comprueba rangos, unidades, unicidad y resultado de la carga.
Sirve vistas y API desde la misma base histórica.
Adquisición
Cada petición conserva endpoint, cuerpo JSON, rango temporal y hora de recepción. Las consultas diarias se dividen en bloques de 30 días; la generación, en bloques de 7 días.
POST https://servapibi.xm.com.co/daily
{
"MetricId": "PorcVoluUtilDiar",
"StartDate": "2026-08-22",
"EndDate": "2026-08-29",
"Entity": "Sistema"
}Evidencia primaria
Antes de transformar, los bytes exactos recibidos se comprimen con gzip. La huella SHA-256 permite comprobar que el archivo descargado no cambió.
X-Content-SHA256.Diccionario de transformación
| Conjunto | Endpoint | MetricId / entidad | Unidad de entrada | Unidad pública | Fórmula |
|---|---|---|---|---|---|
| Reserva agregada del SIN | /daily | PorcVoluUtilDiarSistema | razón respecto a la capacidad de referencia; puede superar 1 | % | porcentaje = Value × 100 |
| Volumen útil por embalse | /daily | PorcVoluUtilDiarEmbalse | razón respecto a la capacidad de referencia; puede superar 1 | % | porcentaje útil = Value × 100 |
| Generación por recurso | /hourly | GeneRecurso | kWh por hora | GWh por día | GWh observados = suma de horas numéricas válidas ÷ 1.000.000; cobertura = horas válidas / 24 |
| Catálogo de recursos | /lists | ListadoRecursos— | catálogo | catálogo | Code enlaza cada lectura con Name y Type |
| Participación por tecnología | derivado de /hourly + /lists | Gene agrupada por TypeTecnología | GWh por recurso y día | % y GWh por tecnología | % tecnología = Σ GWh de la tecnología ÷ Σ GWh de todas las tecnologías × 100 |
Limpieza determinista
Control de calidad
Transparencia
Registro auditable
| Recepción | Métrica | Rango | Ítems | SHA-256 | Verificaciones sin cambios | Original |
|---|---|---|---|---|---|---|
| 7 nov 2026 · 06:03 | Gene hourly · Recurso | 31 oct 2026 → 6 nov 2026 | 2746 | e546f03d51c76a7f… | 0 Última 7 nov 2026 · 06:03 | Descargar JSON |
| 7 nov 2026 · 06:03 | ListadoRecursos lists · catálogo | — → — | 2508 | 1c8ffb3305d772da… | 0 Última 7 nov 2026 · 06:03 | Descargar JSON |
| 7 nov 2026 · 06:03 | PorcVoluUtilDiar daily · Embalse | 31 oct 2026 → 6 nov 2026 | 149 | 667f4dd029473f6f… | 0 Última 7 nov 2026 · 06:03 | Descargar JSON |
| 7 nov 2026 · 06:03 | PorcVoluUtilDiar daily · Sistema | 31 oct 2026 → 6 nov 2026 | 7 | 9e4a165c1b2530ba… | 0 Última 7 nov 2026 · 06:03 | Descargar JSON |
| 6 nov 2026 · 06:04 | Gene hourly · Recurso | 30 oct 2026 → 5 nov 2026 | 2754 | 211cdf609c096e55… | 0 Última 6 nov 2026 · 06:04 | Descargar JSON |
| 6 nov 2026 · 06:03 | ListadoRecursos lists · catálogo | — → — | 2502 | f642e17389731660… | 0 Última 6 nov 2026 · 06:03 | Descargar JSON |
| 6 nov 2026 · 06:03 | PorcVoluUtilDiar daily · Embalse | 30 oct 2026 → 5 nov 2026 | 148 | 57a403e6718a1441… | 0 Última 6 nov 2026 · 06:03 | Descargar JSON |
| 6 nov 2026 · 06:03 | PorcVoluUtilDiar daily · Sistema | 30 oct 2026 → 5 nov 2026 | 7 | 0a98dcf1672fcf1e… | 0 Última 6 nov 2026 · 06:03 | Descargar JSON |
| 5 nov 2026 · 06:03 | Gene hourly · Recurso | 29 oct 2026 → 4 nov 2026 | 2752 | 8b413f71bd454244… | 0 Última 5 nov 2026 · 06:03 | Descargar JSON |
| 5 nov 2026 · 06:03 | ListadoRecursos lists · catálogo | — → — | 2502 | b7f014c7423d5b11… | 0 Última 5 nov 2026 · 06:03 | Descargar JSON |
| 5 nov 2026 · 06:03 | PorcVoluUtilDiar daily · Embalse | 29 oct 2026 → 4 nov 2026 | 149 | 550340161e537776… | 0 Última 5 nov 2026 · 06:03 | Descargar JSON |
| 5 nov 2026 · 06:03 | PorcVoluUtilDiar daily · Sistema | 29 oct 2026 → 4 nov 2026 | 7 | 3c801a7fc4c6bad9… | 0 Última 5 nov 2026 · 06:03 | Descargar JSON |
Verificación independiente
Descarga un lote desde la tabla y calcula su SHA-256. El resultado debe coincidir con la huella completa publicada en el JSON metodológico.
# Windows (PowerShell)
Get-FileHash .\xm-lote.json -Algorithm SHA256
# Linux
sha256sum xm-lote.json
# macOS
shasum -a 256 xm-lote.json
# Debe coincidir con:
GET /api/v1/metodologia/ → recent_batches[].sha256Especificación pública
El código del aplicativo no es público; está disponible para revisión académica bajo solicitud.
El cálculo del verificador ocurre en tu navegador; su JavaScript legible puede revisarse. Esto verifica datos y transformaciones, sin demostrar todos los comportamientos del código privado.
Citación sugerida
HidroCol. Metodología y reproducibilidad, versión 2.2.0.Incluya fecha de consulta, URL de la vista o API, fecha observada del dato, fuente XM/EPM y SHA-256 del lote cuando esté disponible.
La reserva debe tener como máximo 3 días de antigüedad. La comparación de 30 días admite 3 días de tolerancia; se muestra el intervalo real. El percentil necesita 30 observaciones de al menos 2 años anteriores.
SHA-256 acredita igualdad con el original archivado. La cadena de manifiestos requiere una huella anclada externamente para acreditar una fecha anterior.
Consultar revisiones y trazabilidad por lecturaAutoría y reutilización
HidroCol · Juan Camilo Muñoz.
CC BY 4.0: textos, metodología y materiales originales de HidroCol; atribuir a HidroCol y Juan Camilo Muñoz e indicar cambios. Consultar CC BY 4.0.
Los originales de XM conservan la titularidad y condiciones de su fuente; esta licencia no los relicencia ni abarca el código privado del aplicativo. Condiciones de XM.
Visitas al sitio
HidroCol puede habilitar Google Analytics 4 para conocer cuántas visitas recibe, qué páginas se consultan, de dónde proceden y cómo se usa el sitio. Esta medición es opcional: Google Analytics sólo se carga cuando aceptas. Rechazar no cambia el acceso a los datos, gráficos o descargas.
Si aceptas, Google recibe información de la visita, como la ruta de la página, el sitio de procedencia, características del navegador y dispositivo y duración de la interacción. La integración elimina parámetros de consulta y fragmentos de las direcciones enviadas; no envía campos de formularios ni identificadores de usuarios de HidroCol. Google también recibe la dirección IP al establecer la conexión con sus servidores.
Google Analytics utiliza cookies con nombres _ga y _ga_* para distinguir visitas. HidroCol guarda tu elección en el almacenamiento local del navegador. Puedes cambiarla en Privacidad de visitas, disponible en las páginas con medición habilitada. Al rechazar, se detiene la medición y se eliminan estas cookies del sitio; esto no borra información ya recibida por Google. Si tu navegador impide guardar la elección, ésta sólo se aplica a la página abierta.
La integración mantiene desactivadas las señales de Google y la personalización publicitaria. Consulta la política de privacidad de Google y cómo utiliza Google la información de sitios que usan sus servicios.
Las tipografías se alojan en HidroCol; cargarlas no envía solicitudes a Google. Google Analytics sólo se solicita tras aceptar la medición.