Índice

• Conceptos generales
• Librería python
  • Instalación
  • Objetos SIMEM
    • Catalogos de SIMEM.co
    • Conjuntos de datos disponibles
    • ¿Cuál conjunto contiene una variable?
    • Ejemplo de uso
  • Objetos SINERGOX - XM
    • ¿Cómo se pueden consultar el listado de métricas disponibles en la API XM a través de python?
• Excel (VBA)
  • SIMEM
  • SINERGOX - XM
• Endpoints API
  • SIMEM
    • Restricciones
    • Elementos para su uso
  • SINERGOX - XM
    • Restricciones:
    • Variables disponibles para consumir en la API XM
    • ¿Cómo realizar solicitudes filtrando por atributos específicos? (Parámetro opcional)
    • Elementos necesarios para utilizar el servicio desde cualquier cliente
    • Ejemplo para realizar una petición

Conceptos generales

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 las librerías asociadas a las api XM y api SIMEM. A partir de esta guía, el lector estará en capacidad de construir clientes que consuman el servicio utilizando la herramienta de su preferencia: python, excel con VBA o directamente la api.

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

El equipo de Analítica ha diseñado herramientas 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_SINERGOX_XM.xlsm	Macro	No Aplica	No Code
Excel (VBA)	Consulta_API_SIMEM.xlsm	Macro	No Aplica	No Code

Librería python

Warning

La librería pydataxm es compatible con versiones superior o iguales a python 3.10.4

Cada página web de información tiene objetos de python relacionados directamente, se pueden utilizar con la misma librería y realizando los importes correspondientes.

• Objetos SIMEM
• Objetos SINERGOX

Instalación

pip install pydataxm

También se puede clonar el repositorio en la ruta de preferencia:

git clone https://github.com/EquipoAnaliticaXM/API_XM.git "C:\Users\Public\Documents"

Objetos SIMEM

Importación en proyecto

from pydataxm.pydatasimem import ReadSIMEM, CatalogSIMEM

Catalogos de SIMEM.co

Important

El objeto de los catálogos funciona diferente al objeto de lectura de conjuntos de datos.

Se puede solicitar la información utilizando el objeto asociado a los catálogos de la página. Instanciar la clase guarda toda la información en atributos que pueden leerse utilizando las funciones .get_atributo

Conjuntos de datos disponibles

# Importación
from pydataxm.pydatasimem import CatalogSIMEM

# Crear una instancia de catalogo con el tipo
catalogo_conjuntos = CatalogSIMEM('Datasets')

# Extraer información a utilizar
print("Nombre: ", catalogo_conjuntos.get_name())
print("Metadata: ", catalogo_conjuntos.get_metadata())
print("Columnas: ", catalogo_conjuntos.get_columns())

#  Dataframe con información de los conjuntos de datos
data = catalogo_conjuntos.get_data()
print(data)

¿Cuál conjunto contiene una variable?

# Importación
from pydataxm.pydatasimem import CatalogSIMEM

# Crear una instancia de catalogo con el tipo
catalogo_vbles = CatalogSIMEM('variables')

# Extraer información a utilizar
print("Nombre: ", catalogo_vbles.get_name())
print("Metadata: ", catalogo_vbles.get_metadata())
print("Columnas: ", catalogo_vbles.get_columns())

# Dataframe con información de las variables
data = catalogo_vbles.get_data()
print(data)

Ejemplo de uso

Note

La ejecución del snippet con las fechas definidas tarda entre 1 y 2 minutos en ejecutar completamente. Se recomienda usar un cuaderno Jupyter similar a los ejemplos.

El siguiente snippet busca el conjunto asociado a la generación real y realiza una consulta para unas fechas arbitrarias sin el uso de los filtros.

# Importación
from pydataxm.pydatasimem import ReadSIMEM, CatalogSIMEM

# Buscar el id del conjunto de datos
catalogo = CatalogSIMEM('Datasets')
data_catalogo = catalogo.get_data()
print(data_catalogo.query("nombreConjuntoDatos.str.contains('Generación Real')"))

# Crear una instancia de ReadSIMEM
dataset_id = 'E17D25'
fecha_inicio = '2024-04-01'
fecha_fin = '2024-04-30'
generacion = ReadSIMEM(dataset_id, fecha_inicio, fecha_fin)

# Recuperar datos
data = generacion.main(filter=False)
print(data)

Objetos SINERGOX - XM

Importación en proyecto

from pydataxm.pydataxm import ReadDB

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

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

from pydataxm.pydataxm import ReadDB

# Construir la clase que contiene los métodos de pydataxm
objetoAPI = pydataxm.ReadDB()
objetoAPI.get_collections()

Excel (VBA)

Otra herramienta que se puede utilizar para obtener información de las API disponibles, son los archivos de excel publicados en el repositorio

SIMEM

En ListadoVariables se puede realizar la búsqueda del dataset necesario en relación a la variable; por ejemplo, si se desea conocer la Demanda real voy a tener disponible los conjuntos con datasetID c1b851 y b7917; los cuales se diferencian en la cantidad de desagregaciones disponibles, con uno de estos ID y las fechas para extraer datos se puede realizar la solicitud en la hoja Princpal, que además de presentar los datos en la sección inferior, muestra información relacionada al conjunto de datos consultado.

SINERGOX - XM

La hoja1 y hoja2 presentan 2 ejemplos de información disponible; la casilla "NombreMetrica" o "Variable" permite elegir entre una lista desplegable los datos que se desean extraer; la única otra opción disponible es la casilla "Filtro" donde se puede realizar un filtrado a través del campo que presenta en "Desagregación".

Important

El campo fechas puede ser modificado pero no puede superar los días máximos que condiciona automáticamente cada variable.

Endpoints API

También se pueden utilizar los enlaces directos con herramientas alternativas a las presentadas en el repositorio usando los enlaces y métodos disponibles.

Warning

Ambas APIs tienen restricciones para evitar la congestión del servicio, si se desean utilizar de forma directa, recuerde considerar esta información.

Important

El formato de fecha que recibe la API es YYYY-MM-DD

SIMEM

Restricciones

Las restricciones existen en relación a la granularidad de cada conjunto de datos. La cantidad de días se mide con la diferencia entre el parámetro startDate y endDate.

• Catálogos: No aplica.
• Horaria y Diaria: Máximo 31 días por llamado
• Semanal y Mensual: Máximo 731 días por llamado
• Anual: Máximo 1827 días por llamado

Elementos para su uso

Se utiliza el método GET para traer la información utilizando el siguiente enlace:

Important

El parámetro datasetid es obligatorio para cualquier consulta.

https://www.simem.co/backend-files/api/PublicData?datasetid={}

Parámetros:

• datasetId = Código único de 6 dígitos alfanuméricos que representa el conjunto de datos a consultar
• startDate = Fecha del primer dato
• endDate = Fecha del último dato
• columnDestinyName = Columna por la que se hará filtrado
• values = Lista de valores a filtrar en la columna definida. Separados por "," (coma) si es más de uno.

SINERGOX - XM

Restricciones:

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

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

¿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

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:

• https://servapibi.xm.com.co/hourly
• https://servapibi.xm.com.co/daily
• https://servapibi.xm.com.co/monthly
• https://servapibi.xm.com.co/lists

1. Body petición:

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

Note

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"}