ENTSO-E Python API Wrapper

0.8.0 · active · verified Thu Apr 16

entsoe-py is a Python API wrapper for the ENTSO-E Transparency Platform. It simplifies querying electricity data such as day-ahead prices, generation, and capacity, primarily returning data as pandas DataFrames. The library is actively maintained, with version 0.8.0 being the latest, and sees regular updates to address API changes and add new functionality.

Common errors

```
Missing API key. Please set the 'ENTSOE_API_KEY' environment variable or pass 'api_key' to the constructor.
```
cause The ENTSO-E API key was not provided to the EntsoePandasClient constructor or found in the `ENTSOE_API_KEY` environment variable.

fix Ensure you have obtained an API key from the ENTSO-E Transparency Platform and set it as the `ENTSOE_API_KEY` environment variable, or pass it directly: `client = EntsoePandasClient(api_key='YOUR_API_KEY')`.
```
AttributeError: 'EntsoePandasClient' object has no attribute 'query_intraday_offered_capacity' (or similar error after upgrading to v0.8.0)
```
cause The `query_intraday_offered_capacity` function underwent a significant redesign in `v0.8.0`, potentially changing its name, signature, or parameters.

fix Consult the `entsoe-py` documentation or source code for `v0.8.0` to verify the correct function name and parameters for querying intraday offered capacity.
```
KeyError: "['some_column_name'] not found in axis" or ValueError: cannot reindex on an axis with duplicate labels
```
cause Older versions (pre `v0.7.3`) had a bug related to internal DataFrame column renaming during parsing, which could lead to crashes, as reported in GitHub issue #428.

fix Upgrade to `entsoe-py>=0.7.3` to resolve known parsing stability issues and avoid errors related to DataFrame column operations.
```
xml.etree.ElementTree.ParseError: no element found: line 1, column 0
```
cause The ENTSO-E API sometimes returned unexpected content types or malformed XML responses that older `entsoe-py` versions (pre `v0.7.6`) failed to parse correctly.

fix Upgrade to `entsoe-py>=0.7.6` to benefit from fixes that improve handling of various API responses, including unexpected content types and malformed XML.

Warnings

breaking The `query_intraday_offered_capacity` function's signature and behavior were redesigned in `v0.8.0` due to changes related to 'IDA go live'. Existing code calling this specific function may break.
Fix: Review the `entsoe-py` documentation and examples for `v0.8.0` regarding `query_intraday_offered_capacity` to adapt your function calls and parameters.
gotcha Prior to `v0.7.10`, there were reported inconsistencies in how timezones (e.g., lower case 'z' vs 'Z' in timestamps) were handled, potentially leading to parsing errors or incorrect time alignments in retrieved data.
Fix: Upgrade to `entsoe-py>=0.7.10` to ensure consistent and correct timezone parsing across all endpoints.
gotcha Versions of `entsoe-py` prior to `v0.7.9` were known to enable all warnings upon import, which could lead to excessively verbose logs in applications.
Fix: Upgrade to `entsoe-py>=0.7.9` to prevent the library from enabling all warnings on import, resulting in cleaner application logs.
gotcha In `v0.7.5`, the `query_day_ahead_prices` function was refined to strictly return day-ahead prices. If you were implicitly relying on it to retrieve intraday prices for some zones, its behavior might have changed.
Fix: For intraday prices, use the `query_intraday_prices` function, which was introduced in `v0.7.5` specifically for this purpose. Check the documentation for its usage.

Install

pip install entsoe-py Install latest version

Imports

EntsoePandasClient
wrong:
```
from entsoe.entsoe import EntsoePandasClient
```
correct:
```
from entsoe import EntsoePandasClient
```
EntsoePandasClient is the main client for interacting with the ENTSO-E API and returning data as pandas DataFrames. EntsoeRawClient is available for raw XML output.

Quickstart

This quickstart initializes the EntsoePandasClient with an API key, preferably from an environment variable, and demonstrates how to query day-ahead electricity prices for a specified country and date range. The result is a pandas Series.

import os
from entsoe import EntsoePandasClient
import pandas as pd

# Ensure you have an ENTSO-E API key from https://transparency.entsoe.eu/content/static_content/Static%20content/web%20api/API%20Documentation.html
# Set it as an environment variable or pass directly: api_key='YOUR_API_KEY'
api_key = os.environ.get('ENTSOE_API_KEY', '')

if not api_key:
    print("Warning: ENTSOE_API_KEY environment variable not set. Using a placeholder.")
    print("Please obtain a key from ENTSO-E and set it before running.")
    # Use a dummy key if not set, for the example to at least initialize
    # In a real scenario, this would likely cause an authentication error later.
    api_key = "dummy_api_key_for_example"

client = EntsoePandasClient(api_key=api_key)

start = pd.Timestamp('20230101', tz='Europe/Brussels')
end = pd.Timestamp('20230102', tz='Europe/Brussels')
country_code = 'BE'

try:
    # Query day-ahead prices for Belgium
    day_ahead_prices = client.query_day_ahead_prices(country_code, start=start, end=end)
    print(f"Day-ahead prices for {country_code} (first 5 rows):\n{day_ahead_prices.head()}")
except Exception as e:
    print(f"An error occurred during API query: {e}")
    print("Please ensure your API key is correct and valid, and the country code/date range are supported.")

view raw JSON →