downloader.entsoe.download_new_data

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

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., ‘DE’, ‘FR’). Defaults to “DE”.	`'DE'`
start	str \| pd.Timestamp \| None	Start of the query window (‘YYYYMMDDHH00’ or a timestamp). If None, resumes from the last observed timestamp in the interim file, extending back to heal still-missing actuals (bounded by `_MAX_BACKFILL_DAYS`) and falling back to seven days ago when no prior data exists.	`None`
end	str \| pd.Timestamp \| None	End of the query window (‘YYYYMMDDHH00’ or a timestamp). If None, the current UTC moment is used.	`None`
force	bool	If True, bypass the cooldown that skips a download when the last successful download is younger than `_COOLDOWN_HOURS` (24) hours. The cooldown is bypassed automatically when the requested window overlaps a known gap in the interim data, so gap backfills are never silently skipped.	`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`
on_unavailable	`OnUnavailable`	What to do when ENTSO-E stays unreachable after the retry budget is exhausted. `"raise"` (default) raises `RuntimeError`; `"use_existing"` logs how stale the interim data is and returns so the caller can continue on existing data (requires an existing interim file, else `RuntimeError`).	`'raise'`

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, if both are given explicitly but `end` is not after `start`, or if `on_unavailable` is not a recognized value.
	RuntimeError	If data fetching fails after `_MAX_RETRIES` attempts and `on_unavailable='raise'`.

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="DE")

# 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,
)