ESIOS API in Python: Spain energy data analysis

Step by step, you'll learn how to download, preprocess, and visualize data from the Spanish Electric Grid's API using Python.

Spain’s electrical system works with more than 10,000 indicators that are updated every moment.

ESIOS REE website cover

If you work with these indicators for your business processes, you’ll agree with me that using Excel with so much manual downloading, clicking here, clicking there is a real drag.

Imagine your company owns a hydroelectric plant and you want to analyze the Scheduled Generation PBF Hydraulic UGH indicator, how do you automate the download process with Python?

Daily Hydraulic UGH Generation January 2024


  1. How to obtain a token for the ESIOS API?
  2. What is an indicator in the ESIOS API and how do you access it?
  3. How are data from a specific indicator downloaded?
  4. How do you build a data table from the API response?
  5. How are the downloaded data processed and visualized with Python?
  6. How do you adjust the date range for data download?



To request information from the Red Eléctrica (REE) systems, you’ll need an authentication code (known in computer jargon as a token).

You must send an email to REE requesting the token to be associated with your email account (so they keep an eye on you in case you get heavy with too many API calls). Navigate to the official page and click on Personal token request to send the email.


headers = {
    'Host': '',
    'x-api-key': API_TOKEN

List of Indicators

To download the data for the Scheduled Generation PBF Hydraulic UGH indicator, we need the associated code. We’ll find it in the list of indicators provided by the API.

APIs work with URLs. Therefore, we create a url to locate all the indicators.

ENDPOINT = 'indicators/'


We use the get function from the requests library to obtain the resources from the url by validating our call with the token stored in headers.

import requests

res = requests.get(url, headers=headers)
data = res.json()

Available indicators in ESIOS API

The id associated with the desired indicator is 1. Therefore, we add the code to the url.


We make the call again and process the information with functions from the pandas library to represent it in a table.

res = requests.get(url, headers=headers)
data = res.json()

df = pd.DataFrame(data['indicator']['values'])
df = df[['datetime_utc', 'geo_id', 'geo_name', 'value']]

Table (DataFrame) constructed with ESIOS API data

We only get data for one day. How could we obtain data for a month?

By adding parameters to the call.

params = {
    'start_date': '2024-01-01T00',
    'end_date': '2024-01-31T23'

res = requests.get(url, headers=headers, params=params)

DataFrame updated according to date range

Having a month of information, we could visualize the total daily generation.


Daily Hydraulic UGH Generation January 2024


Thanks to this tutorial, you’ve learned several important aspects about ESIOS, APIs, and Python:

  1. Token: You learned how to obtain a token to access the ESIOS API.
  2. Indicators: You identified and accessed specific indicators.
  3. Data Download: You managed to download data using Python.
  4. Table Construction: You created data tables from API responses, a key skill for organizing and preparing data for analysis.
  5. Visualization: You processed and visualized data to better interpret it.
  6. Date Range: You adjusted the date range for your specific needs.

Do you think this tutorial could be useful to a colleague? You know, sharing is caring.

Great! You’ve successfully signed up.

Welcome back! You've successfully signed in.

You've successfully subscribed to datons.

Success! Check your email for magic link to sign-in.

Success! Your billing info has been updated.

Your billing was not updated.