Índice

1. Conceptos generales de la API XM
2. Variables disponibles para consumir en la API XM
3. Soluciones diseñadas para consumir la API
4. Cómo realizar solicitudes filtrando por atributos específicos?
5. Restricciones de la API
6. Comentarios finales
7. Elementos necesarios para utilizar el servicio desde cualquier cliente

Conceptos generales de la API XM

Este repositorio se crea con el fin de compartir herramientas de consulta para extraer información relevante del Mercado de Energía Mayorista colombiano usando la API XM. A partir de esta guía, el lector estará en capacidad de construir clientes que consuman el servicio utilizando la herramienta de su preferencia. Posteriormente, detallaremos dos aproximaciones utilizando VBA y Python.

Para utilizar la API XM no se requiere gestionar ningún usuario o clave

Variables disponibles para consumir en la API XM

A continuación, se listan las variables que se encuentran disponibles para su consulta, las cuales se encuentran clasificadas por tema:

Hidrología

• Volumen Útil Diario (Energía)
• Volumen Útil Diario por Embalse (Energía)
• Aportes Diarios (Energía)
• Aportes Diarios por Río (Energía)
• Capacidad útil del SIN (Energía)
• Capacidad Útil por Embalse (Energía)
• Media Histórica de Aportes del SIN (Energía)
• Media Histórica de Aportes por Río (Energía)

Demanda

• Demanda Comercial Total
• Demanda Comercial por Agente Comercializador
• Demanda del SIN
• Demanda por Operador de Red
• Perdidas de Energía
• Demanda No Atendida Programada por Área
• Demanda No Atendida Programada por Subárea
• Demanda No Atendida No Programada por Área
• Demanda No Atendida No Programada por Subárea
• Demanda Comercial Regulada por Agente
• Demanda Comercial No regulada por Agente
• Demanda Comercial Regulada (Total SIN)
• Demanda Comercial No Regulada (Total SIN)
• Demanda Comercial No Regulada por CIIU
• Demanda Máxima Potencia
• Demanda Energía Escenario UPME Alto
• Demanda Energía Escenario UPME Medio
• Demanda Energía Escenario UPME Bajo

Oferta y Generación

• Generación Real Total
• Generación Real por Recurso (Planta de Generación)
• Generación Ideal
• Generación Ideal por Recurso (Planta de Generación)
• Consumo de Combustible por Recurso (Planta de Generación)
• Listado de Recursos de generación con sus principales atributos (Agente Generador, Tipo, Capacidad Efectiva Neta, entre otros)
• Generación de Seguridad por Recurso
• Generación Fuera de Mérito por Recurso
• Obligaciones de Energía Firme por Recurso
• Generación Programada Despacho
• Generación Programada Redespacho
• Disponibilidad Real
• Disponibilidad Comercial
• Disponibilidad Declarada
• Reconciliación Positiva Energía
• Reconciliación Negativa Energía
• Desviaciones Energía
• Compras AGPE

Transacciones y Precios

• Costo de las Restricciones que se trasladan a la demanda (Restricciones finales)
• Precio de Escasez de Activación
• Precio de Bolsa Nacional
• Máximo Precio de Oferta
• Remuneración Real Individual Diaria del Cargo por Confiablidad (RRID)
• Precio de Oferta del Despacho
• Precio Promedio Contratos Regulado
• Precio Promedio Contratos No Regulado
• Ventas en Contratos Energía por Agente
• Ventas en Contratos Energía (Total SIN)
• Compras en Contrato Energía por Agente
• Compras en Contrato Energía (Total SIN)
• Compras en Bolsa Nacional Energía por Agente
• Compras en Bolsa Nacional Energía (Total SIN)
• Responsabilidad Comercial AGC
• Reconciliación Positiva Moneda
• Reconciliación Negativa Moneda
• Restricciones sin alivios
• Restricciones aliviadas
• Desviaciones Moneda
• DDV Contratada
• FAZNI Moneda
• FAER Moneda
• PRONE Moneda
• MC
• Compras Contratos Energía  Mercado Regulado
• Compras Contratos Energía  No Mercado Regulado
• Rentas de congestión para cubrir restricciones
• Saldo Neto TIE Mérito
• Saldo Neto TIE Fuera de Mérito
• Compras Contratos Energía  Mercado Regulado por Agente
• Compras Contratos Energía  No Mercado Regulado por Agente
• Precio de Bolsa Nacional TX1
• CERE
• CEE
• Ejecución Garantías
• Compras Contratos de Respaldo
• Compras Contratos de Respaldo por Recurso
• Ventas Contratos de Respaldo
• Ventas Contratos de Respaldo por Recurso
• Cargos por Uso STN
• Cargos por Uso STR
• Precio liquidado del Cargo por Confiabilidad
• Cargo Máximo T Prima
• Cargo Mínimo T Prima
• Cargo Media T Prima
• Compras Bolsa TIE Moneda Sistema
• Compras Bolsa Internacional Moneda Sistema
• Compras Bolsa TIE Moneda Agente
• Compras Bolsa Internacional Moneda Agente
• Ventas Bolsa TIE Moneda Sistema
• Ventas Bolsa Internacional Moneda Sistema
• Ventas Bolsa TIE Moneda Agente
• Ventas Bolsa Internacional Moneda Agente

Intercambios Internacionales

• Importaciones en Energía
• Exportaciones en Energía

Cálculo de emisiones de CO₂

• Emisiones de CO₂
• Emisiones de CH₄
• Emisiones de N₂O
• Emisiones de CO₂eq
• Consumo Combustible Aproximado para el Factor Emisión
• Factor de Emisión de la Matriz Energética (CO₂eq/kWh)

Listados

• Listado Recursos con atributos
• Listado de agentes con atributos
• Listado de métricas
• Listado de ríos
• Listado de embalses

Soluciones diseñadas para consumir la API

Tal como se indicó al inicio, el equipo de Analítica ha diseñado dos aproximaciones para consumir el servicio en los siguientes lenguajes:

Lenguaje	Nombre	Tipo	Instalación	Habilidad requerida
Python	pydataxm	Librería	$ pip install pydataxm	Low Code
Excel (VBA)	Consulta_API_XM.xlsm	Macro	No Aplica	No Code

¿Cómo realizar solicitudes filtrando por atributos específicos? (Parámetro opcional)

En caso de no ser especificado dentro de la solicitud, el servicio retornará todos los registros disponibles.

Con este parámetro se permite extraer datos para una serie de entidades personalizada. Las métricas que pueden ser filtradas son todas aquellas que tienen cruces por:

1. Agente (código SIC del agente i.e. CASC, EPMC, ENDG, entre otros)
2. Recurso (código SIC del recurso i.e. EPFV, TBST, JEP1, entre otros)
3. Embalse (nombre del embalse i.e. EL QUIMBO, GUAVIO, PENOL, entre otros)
4. Río (nombre del río i.e. FLORIDA II, BOGOTA N.R., DESV. MANSO, entre otros)

Para conocer el detalle de los códigos SIC de cada recurso o agente le invitamos a consultar las métricas ListadoRecursos y ListadoAgentes disponibles en este mismo servicio.

Para conocer el detalle de los nombres de cada río o embalse le invitamos a consultar las métricas ListadoRios y ListadoEmbalse disponibles en este mismo servicio.

En la carpeta examples encontrará los ejemplos para consumir el servicio usando filtros. Ir a ejemplos

Restricciones de la API:

Con el fin de no congestionar el servicio, se han establecido restricciones a las consultas así:

• Para datos horarios y diarios, máximo 30 días por llamado
• Para datos mensuales, máximo 731 días por llamado
• Para datos anuales, máximo 366 días por llamado

Comentarios finales

Tener en cuenta que el formato de fecha que recibe la API es YYYY-MM-DD

Elementos necesarios para utilizar el servicio desde cualquier cliente

A continuación, presentamos el listado de métricas disponibles y los parámetros requeridos para realizar peticiones de información:

1. Método: POST
2. Endpoint:

• www.servapibi.xm.com.co/hourly
• www.servapibi.xm.com.co/daily
• www.servapibi.xm.com.co/monthly
• www.servapibi.xm.com.co/lists

3. Body petición:

{"MetricId": "MetricID",
"StartDate": _"YYYY-MM-DD",
"EndDate":_"YYYY-MM-DD",
"Entity": "Cruce",
"Filter":["Listado de codigos"]}

Nota: El parámetro Filter es opcional y solo aplica para variables diferente al cruce por Sistema

Ejemplo para realizar una petición

POST: http://servapibi.xm.com.co/hourly

Body:
{"MetricId": "Gene",
"StartDate":"2022-09-01",
"EndDate":"2022-09-02",
"Entity": "Recurso",
"Filter":["TBST","GVIO"]}

Para conocer el inventario total de variables, cruces y filtros opcionales, consultar:

http://servapibi.xm.com.co/lists

Body:
{"MetricId": "ListadoMetricas"}