data.fetch_data.load_school_holidays_de

data.fetch_data.load_school_holidays_de()

Load the bundled German school-holiday interval table.

Reads datasets/csv/school_holidays_de.csv (ODbL-1.0) from the package data directory and the companion validity-range metadata from school_holidays_de_meta.csv. No download is needed; both files ship with the package.

The CSV has four columns: state (ISO 3166-2 subdivision short code, e.g. "NW"), name (German name of the holiday period), start_date and end_date (both inclusive, parsed as datetime64 (resolution depends on the pandas version)). Coverage is 2022-01-01 to 2027-12-31 (all 16 German Bundesländer).

Data provenance: OpenHolidays API (https://openholidaysapi.org), database https://github.com/openpotato/openholidaysapi.data, ODC Open Database License (ODbL-1.0).

Regeneration command (requires network access):

for code in BW BY BE BB HB HH HE MV NI NW RP SL SN ST SH TH:
    GET https://openholidaysapi.org/SchoolHolidays?countryIsoCode=DE
        &subdivisionCode=DE-<code>&validFrom=2022-01-01&validTo=2024-12-31
        &languageIsoCode=DE  (split into two 3-year windows to respect the
        1095-day API limit; second window: validFrom=2025-01-01,
        validTo=2027-12-31).  Keep every record whose startDate falls within
        [valid_from, valid_to]; endDate may extend beyond valid_to and is
        kept verbatim (queries past valid_to raise).

Returns

Name	Type	Description
tuple	pd.DataFrame	A three-tuple `(df, valid_from, valid_to)` where:
	pd.Timestamp	- df — DataFrame with columns `state`, `name`, `start_date` (datetime64, resolution depends on the pandas version), `end_date` (datetime64, resolution depends on the pandas version), sorted by `(state, start_date)`.
	pd.Timestamp	- valid_from — `pd.Timestamp` for the first covered day (`2022-01-01`).
	tuple[pd.DataFrame, pd.Timestamp, pd.Timestamp]	- valid_to — `pd.Timestamp` for the last covered day (`2027-12-31`).

Examples

import pandas as pd

from spotforecast2_safe.data.fetch_data import load_school_holidays_de

df, valid_from, valid_to = load_school_holidays_de()
print("states:", sorted(df["state"].unique()))
print("valid_from:", valid_from.date())
print("valid_to:", valid_to.date())
print("shape:", df.shape)
assert len(df["state"].unique()) == 16
assert valid_from == pd.Timestamp("2022-01-01")
assert valid_to == pd.Timestamp("2027-12-31")

states: ['BB', 'BE', 'BW', 'BY', 'HB', 'HE', 'HH', 'MV', 'NI', 'NW', 'RP', 'SH', 'SL', 'SN', 'ST', 'TH']
valid_from: 2022-01-01
valid_to: 2027-12-31
shape: (626, 4)