Skip to content

Examples

This page provides practical examples for using the ENTSO-E API Python package.

All available endpoints are listed in ENTSOE Overview and a dictionary with EIC codes and their corresponding names and tags can be found in Mappings.

Working with API Results

Converting Results to DataFrames

All API results are returned as Pydantic models with nested structures. To convert them into flat records suitable for pandas DataFrames, use the extract_records() function:

from pandas import DataFrame
from entsoe.Market import EnergyPrices
from entsoe.utils import extract_records, add_timestamps

# Query energy prices
result = EnergyPrices(
    in_domain="10YNL----------L", # Netherlands
    out_domain="10YNL----------L",
    period_start=202012312300,
    period_end=202101022300,
).query_api()

# Convert to DataFrame-ready records
records = extract_records(result)
records = add_timestamps(records)
df = DataFrame(records)

Note

The extract_records function automatically removes m_rid and time_series.m_rid metadata fields. This mitigates duplicates due to internal splitting of queries, see #68. You may extend the ignore_fields parameter as needed (for exampe with "created_date_time", "time_period_time_interval.start","time_period_time_interval.end"). See extract_records for more details.

See also Utilities for more details on the utility functions.

Extracting Specific Domains

You can extract specific parts of the result by specifying a domain:

# Extract only time series data
time_series_records = extract_records(result, domain="time_series")
time_series_df = DataFrame(time_series_records)

JSON Export and Import

All API result objects are Pydantic models that provide built-in JSON serialization. Use the model_dump_json() method to convert results to JSON:

# Convert with indentation for pretty printing
import json

pydantic_model = result[0]
json_dict = pydantic_model.model_dump(mode="json")
pretty_json = json.dumps(json_dict, indent=2)
print(pretty_json)

Advanced JSON Options

The model_dump_json() method supports various options for customization:

# Include None values (excluded by default)
json_with_none = pydantic_model.model_dump_json(exclude_none=False)

# Exclude specific fields
json_filtered = pydantic_model.model_dump_json(exclude={"mrid", "created_date_time"})

# Include only specific fields
json_minimal = pydantic_model.model_dump_json(include={"time_series", "period"})

# Use different serialization mode
json_python = pydantic_model.model_dump_json(mode="python")  # Uses Python types