python-entsoe

Python client for the ENTSO-E Transparency Platform API.

Typed, namespace-organized access to European electricity market data — load, prices, generation, transmission, and balancing.

pip install python-entsoe

Quick Start

from entsoe import Client

client = Client()  # reads ENTSOE_API_KEY from environment

df = client.load.actual("2024-06-01", "2024-06-08", country="FR")

Strings are interpreted as timestamps in Europe/Brussels (CET — the ENTSO-E standard). You can override this per-client or pass pd.Timestamp objects directly:

client = Client(tz="UTC")  # override default timezone

# pd.Timestamp still works — its timezone takes priority
import pandas as pd
start = pd.Timestamp("2024-06-01", tz="Europe/Paris")
df = client.load.actual(start, "2024-06-08", country="FR")

Every method returns a pandas.DataFrame with a timezone-aware timestamp column and a value column.

Authentication

Get a free API key at https://transparency.entsoe.eu/ (register, then request a token via email).

Set it as an environment variable:

export ENTSOE_API_KEY=your-token-here

Or pass it directly:

client = Client(api_key="your-token-here")

API Reference

client.load

df = client.load.actual(start, end, country="FR")
df = client.load.forecast(start, end, country="FR")

client.prices

df = client.prices.day_ahead(start, end, country="FR")
# Returns: timestamp, value, currency, price_unit

# DE_LU and AT also publish the separate EXAA auction (10:15 CET)
exaa = client.prices.day_ahead(start, end, country="DE_LU", sequence=2)

client.generation

# All generation types
df = client.generation.actual(start, end, country="FR")

# Solar only
df = client.generation.actual(start, end, country="FR", psr_type="B16")

# Installed capacity
df = client.generation.installed_capacity(start, end, country="FR")

client.transmission

df = client.transmission.crossborder_flows(
    start, end, country_from="FR", country_to="ES"
)

client.balancing

df = client.balancing.imbalance_prices(start, end, country="FR")

Country Codes

Use standard ISO codes. Some bidding zones have specific codes:

Note: For day-ahead prices and balancing data, use DE_LU instead of DE. See data availability notes for details.

Full list of 60+ supported areas in _mappings.py.

PSR Types (Fuel Types)

Use PSR codes to filter generation by fuel type:

Full list in _mappings.py. Human-readable names available via:

from entsoe._mappings import PSR_TYPES
print(PSR_TYPES["B16"])  # "Solar"

Timestamps

All start and end parameters accept date strings or tz-aware pd.Timestamp objects:

# Simple — just strings (uses client's default tz: Europe/Brussels)
df = client.load.actual("2024-01-01", "2024-01-07", country="FR")

# pd.Timestamp with explicit timezone — takes priority over default
df = client.load.actual(
    pd.Timestamp("2024-01-01", tz="Europe/Paris"),
    pd.Timestamp("2024-01-07", tz="Europe/Paris"),
    country="FR",
)

# Mixing is fine
df = client.load.actual("2024-01-01", pd.Timestamp("2024-01-07", tz="UTC"), country="FR")

# Naive pd.Timestamp (no tz) — still raises InvalidParameterError
start = pd.Timestamp("2024-01-01")  # ← no tz, will error

Timezones

The client tz setting interprets input date strings (default Europe/Brussels); it does not control returned timestamps. The separate output_tz setting controls results: "UTC" (default, unchanged behavior), "local" (the requested area's timezone), or a fixed IANA timezone such as "Europe/Madrid". Every namespace method also accepts output_tz= for one call. The CLI accepts --tz on data commands, or entsoe config set output-tz local as a persistent default; --tz takes precedence.

For a multi-area request, "local" requires matching clock offsets throughout the returned period (for example, FR and ES); otherwise choose "UTC" or a fixed IANA zone. Cross-border results use the first importing (in_domain) zone. During the October DST fall-back, local wall-clock times repeat; each row retains its offset, but timestamps cease to be unique if the timezone is stripped.

Features

• Autocomplete-friendly — type client. and see all domains, then drill into methods
• Automatic year-splitting — requests spanning more than 1 year are split transparently
• ZIP handling — endpoints returning compressed responses are decompressed automatically
• Retry with backoff — rate-limited requests (HTTP 429) are retried with exponential backoff
• Clear errors — NoDataError, InvalidParameterError, RateLimitError with descriptive messages

Error Handling

from entsoe import Client, NoDataError, InvalidParameterError

client = Client()

try:
    df = client.prices.day_ahead(start, end, country="FR")
except NoDataError:
    print("No data available for this period")
except InvalidParameterError as e:
    print(f"Bad parameters: {e}")

Examples

See the examples/ directory for Jupyter notebooks with plotly visualizations:

• load.ipynb — actual load, forecast comparison, multi-country profiles
• prices.ipynb — day-ahead prices, distributions, hourly heatmap
• generation.ipynb — generation mix, solar vs wind, installed capacity
• transmission.ipynb — cross-border flows, bidirectional charts, NTC
• balancing.ipynb — imbalance prices, multi-country, distribution

Development

git clone git@gitlab.com:datons.com/libraries/python-entsoe.git
cd python-entsoe
uv sync

# Run tests (requires ENTSOE_API_KEY in .env)
uv run pytest tests/ -v

# Regenerate example notebooks
uv run python scripts/generate_notebooks.py

License

MIT