entsoe-py

The package provides two primary clients for interacting with the ENTSO-E REST API:

1. EntsoeRawClient: Returns data in its original format. Methods return either XML strings or ZIP files (bytes).
2. EntsoePandasClient: Returns data parsed into high-level Python structures. Methods return either Pandas Series or Pandas DataFrames. This client automatically handles time periods spanning more than one year and splits large requests across multiple API calls.

Important for EntsoePandasClient: You must provide start and end parameters as pandas Timestamps with a timezone. Failure to do so will result in an exception.

from entsoe import EntsoeRawClient, EntsoePandasClient
import pandas as pd

# For Raw data
raw_client = EntsoeRawClient(api_key='YOUR_API_KEY')

# For Pandas data (requires timezone-aware timestamps)
start = pd.Timestamp('20171201', tz='Europe/Brussels')
end = pd.Timestamp('20180101', tz='Europe/Brussels')
pandas_client = EntsoePandasClient(api_key='YOUR_API_KEY')

You can use load_zones to retrieve a GeoDataFrame of bidding zones and then use plotly.express to visualize them. The load_zones function returns a GeoDataFrame where the index typically represents the zone identifiers.

Note: The geojson files in this package are compliant with RFC 7946 ring winding order, making them directly compatible with Plotly.

from utils import load_zones
import plotly.express as px
import pandas as pd

# Define the list of zone codes you want to load
zones = ['some', 'ISO2', 'codes']

# Load the GeoDataFrame for a specific date
geo_df = load_zones(zones, pd.Timestamp('somedate'))

# Assign a value for coloring the map
geo_df['value'] = range(1, len(geo_df) + 1)

# Create the choropleth map
fig = px.choropleth(geo_df,
                   geojson=geo_df.geometry,
                   locations=geo_df.index,
                   color="value",
                   projection="mercator",
                   color_continuous_scale='rainbow')

# Adjust the map to fit the loaded locations
fig.update_geos(fitbounds="locations", visible=False)
fig.show()

Use EntsoeRawClient to fetch raw data directly from the API. Some methods return XML strings, while others return ZIP files as bytes.

To perform a request not explicitly covered by a named method, you can use the private _base_request method by passing a dictionary of parameters.

from entsoe import EntsoeRawClient
import pandas as pd

client = EntsoeRawClient(api_key=<YOUR API KEY>)
start = pd.Timestamp('20171201', tz='Europe/Brussels')
end = pd.Timestamp('20180101', tz='Europe/Brussels')
country_code = 'BE'

# Example: Querying XML
xml_string = client.query_day_ahead_prices(country_code, start, end)
with open('outfile.xml', 'w') as f:
    f.write(xml_string)

# Example: Querying ZIP bytes
zip_bytes = client.query_unavailability_of_generation_units(country_code, start, end)
with open('outfile.zip', 'wb') as f:
    f.write(zip_bytes)

# Example: Custom request using _base_request
params = {
    'documentType': 'A44',
    'in_Domain': '10YBE----------2',
    'out_Domain': '10YBE----------2'
}
response = client._base_request(params=params, start=start, end=end)
print(response.text)

The EntsoeFileClient (from the entsoe.files subpackage) allows you to interact with the ENTSOE File Library (which replaced SFTP).

1. Use list_folder(folder) to get a dictionary mapping {filename: unique_id}.
2. Use download_single_file(folder, filename) to download a specific file by its name.
3. Use download_multiple_files(list_of_ids) to download multiple files using their unique IDs.

from entsoe.files import EntsoeFileClient

client = EntsoeFileClient(username=<YOUR ENTSOE USERNAME>, pwd=<YOUR ENTSOE PASSWORD>)

# List files in a folder (returns dict of {filename: unique_id})
file_list = client.list_folder('AcceptedAggregatedOffers_17.1.D')

# Download one file by name
df = client.download_single_file(folder='AcceptedAggregatedOffers_17.1.D', filename=list(file_list.keys())[0])

# Download multiple files by unique_id
df = client.download_multiple_files(['a1a82b3f-c453-4181-8d20-ad39c948d4b0', '64e47e15-bac6-4212-b2dd-9667bdf33b5d'])