API_XM: A Python repository from EquipoAnaliticaXM

Índice

Conceptos generales de la API XM
Variables disponibles para consumir en la API XM
Soluciones diseñadas para consumir la API
Cómo realizar solicitudes filtrando por atributos específicos?
Restricciones de la API
Comentarios finales
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

¿Cómo se pueden consultar el listado de métricas disponibles en la API XM a través de códido?

Para conocer el listado de métricas disponibles se puede consultar el método get_collections() como se muestra a continuación:

from pydataxm import * # Importa la libreria que fue instalada con pip install pydataxm o tambien desde GitHub
objetoAPI = pydataxm.ReadDB() # Construir la clase que contiene los métodos de pydataxm
objetoAPI.get_collections()

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
Listado recursos AGPE

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:

Agente (código SIC del agente i.e. CASC, EPMC, ENDG, entre otros)
Recurso (código SIC del recurso i.e. EPFV, TBST, JEP1, entre otros)
Embalse (nombre del embalse i.e. EL QUIMBO, GUAVIO, PENOL, entre otros)
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:

Método: POST
Endpoint:

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: https://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:

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

Body:
{"MetricId": "ListadoMetricas"}

EquipoAnaliticaXM/API_XM