downloader.entsoe.download_new_data

downloader.entsoe.download_new_data(
    api_key,
    country_code='FR',
    start=None,
    end=None,
    force=False,
    keep_forecast_future=False,
    timeout=60.0,
)

Download new load and forecast data from ENTSO-E.

This function queries the ENTSO-E Transparency Platform for a given period. If no start date is provided, it automatically resumes from the last available data point. Should the trailing rows hold a published day-ahead forecast but no Actual Load yet (ENTSO-E publishes actuals with a lag and occasionally backfills them days later), the fetch window is extended back to the first hour whose actuals are still missing, bounded by _MAX_BACKFILL_DAYS, so late-published values heal automatically on the next incremental download.

Parameters

Name	Type	Description	Default
api_key	str	The ENTSO-E API key.	required
country_code	str	The country code to query (e.g., ‘FR’, ‘DE’). Defaults to “FR”.	`'FR'`
start	str \| None	Start date in ‘YYYYMMDDHH00’ format.	`None`
end	str \| None	End date in ‘YYYYMMDDHH00’ format.	`None`
force	bool	If True, bypass the 24h cooldown check.	`False`
keep_forecast_future	bool	If True, retain rows after the current UTC moment when building the interim file, preserving ENTSO-E’s day-ahead `Forecasted Load` for tomorrow. Defaults to False (future rows are dropped, the leakage-free input for training). The flag only keeps rows the query window already covers, so pass an `end` that reaches into the target day (e.g. tomorrow) as well. See `merge_build_manual` for details.	`False`
timeout	Optional[float]	Per-socket-operation read timeout in seconds passed to the ENTSO-E client. Kills stalled connections (raises `requests.exceptions.Timeout`, caught by the existing retry loop, then `RuntimeError` after retries) without bounding long live transfers. `None` disables the timeout. Defaults to `60.0`.	`60.0`

Raises

Name	Type	Description
	ImportError	If the Python package ‘entsoe-py’ is not installed.
	ValueError	If `start` or `end` cannot be parsed as a valid timestamp.
	RuntimeError	If data fetching fails after `_MAX_RETRIES` attempts.

Notes

Logging information can be selected by setting the log level for the spotforecast2_safe.downloader.entsoe logger. Common levels are DEBUG, INFO, WARNING, ERROR, and CRITICAL. The cell below shows the default (WARNING); change the level to INFO or DEBUG for more verbose output.

import logging
logging.getLogger("spotforecast2_safe.downloader.entsoe").setLevel(logging.WARNING)

Examples

Replace YOUR_API_KEY below with your ENTSO-E Web API Security Token (free registration at https://transparency.entsoe.eu, then “My Account Settings” → “Web API Security Token”). Prefer reading the token from an environment variable rather than hard-coding it in source — see the Information-Disclosure note in the module STRIDE table above.

from spotforecast2_safe.downloader.entsoe import download_new_data

# Basic download for Germany with explicit start/end dates
download_new_data(
    api_key="YOUR_API_KEY",
    country_code="DE",
    start="202301010000",
    end="202301020000",
    force=True,
)

# Incremental download (automatically resumes from last data point)
download_new_data(api_key="YOUR_API_KEY", country_code="FR")

# Forced download bypassing the 24-hour cooldown check
download_new_data(
    api_key="YOUR_API_KEY",
    country_code="DE",
    force=True,
)

# Retain tomorrow's day-ahead `Forecasted Load` (forecast baseline);
# `end` must reach into the target day for the rows to exist
download_new_data(
    api_key="YOUR_API_KEY",
    country_code="DE",
    start="202301010000",
    end="202301030000",
    force=True,
    keep_forecast_future=True,
)