WetterdienstConnection

class eta_utility.connectors.WetterdienstConnection(*, nodes: Nodes[NW] | None = None, settings: Settings | None = None, **kwargs: Any)[source]

The WetterdienstConnection class is a connector to the Wetterdienst API for retrieving weather data. This class is an abstract base class and should not be used directly. Instead, use the subclasses WetterdienstObservationConnection and WetterdienstPredictionConnection.

Parameters:

url – The base URL of the Wetterdienst API
nodes – Nodes to select in connection
settings – Wetterdienst settings object

abstract read_series(from_time: datetime, to_time: datetime, nodes: Nodes[NW] | None = None, interval: TimeStep = 60, **kwargs: Any) → pd.DataFrame[source]

Abstract base method for read_series(). Is fully implemented in read_series() and read_series().

Parameters:

nodes – List of nodes to read values from.
from_time – Starting time to begin reading (included in output).
to_time – Time to stop reading at (not included in output).
interval – interval between time steps. It is interpreted as seconds if given as integer.
kwargs – additional argument list, to be defined by subclasses.

Returns:

pandas.DataFrame containing the data read from the connection.

read(nodes: Nodes[NW] | None = None) → pd.DataFrame[source]

Warning

Cannot read single values from the Wetterdienst API. Use read_series instead

Parameters:: nodes – List of nodes to read values from
Returns:: Pandas DataFrame containing the data read from the connection

write(values: Mapping[NW, Any], time_interval: timedelta | None = None) → None[source]

Warning

Cannot write to the Wetterdienst API.

Parameters:

values – Dictionary of nodes and data to write. {node: value}
time_interval – Interval between datapoints, default 1s

subscribe(handler: SubscriptionHandler, nodes: Nodes[NW] | None = None, interval: TimeStep = 1) → None[source]

Subscribe to nodes and call handler when new data is available. This will return only the last available values.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs
interval – interval for receiving new data. It is interpreted as seconds when given as an integer.
nodes – identifiers for the nodes to subscribe to

subscribe_series(handler: SubscriptionHandler, req_interval: TimeStep, offset: TimeStep | None = None, nodes: Nodes[NW] | None = None, interval: TimeStep = 1, data_interval: TimeStep = 1, **kwargs: Any) → None[source]

Warning

Not implemented: Cannot subscribe to data from the Wetterdienst API.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs
req_interval – Duration covered by requested data (time interval). Interpreted as seconds if given as int
offset – Offset from datetime.now from which to start requesting data (time interval). Interpreted as seconds if given as int. Use negative values to go to past timestamps.
data_interval – Time interval between values in returned data. Interpreted as seconds if given as int.
interval – interval (between requests) for receiving new data. It it interpreted as seconds when given as an integer.
nodes – identifiers for the nodes to subscribe to

close_sub() → None[source]: Warning

Not implemented: Cannot subscribe to data from the the Wetterdienst API.

retrieve_stations(node: NodeWetterdienst, request: wetterdienst.provider.dwd.observation.api.DwdObservationRequest) → pandas.DataFrame[source]

Retrieve stations from the Wetterdienst API and return the values as a pandas DataFrame Stations are filtered by the node’s station_id or latlon and number_of_stations

Parameters:

node – Node to retrieve stations for
request – Wetterdienst request object, containing the station data

WetterdienstObservation

class eta_utility.connectors.WetterdienstObservationConnection(*, nodes: Nodes[NW] | None = None, settings: Settings | None = None, **kwargs: Any)[source]

The WetterdienstObservationConnection class is a connector to the Wetterdienst API for retrieving weather observation data. Data can only be read with read_series().

read_series(from_time: datetime, to_time: datetime, nodes: Nodes[NodeWetterdienstObservation] | None = None, interval: TimeStep = 60, **kwargs: Any) → pd.DataFrame[source]

Read weather observation data from the Wetterdienst API for the given nodes and time interval

Parameters:

from_time – Start time for the data retrieval
to_time – End time for the data retrieval
nodes – Nodes to read data from
interval – Time interval between data points in seconds

Returns:

Pandas DataFrame containing the data read from the connection

WetterdienstPrediction

class eta_utility.connectors.WetterdienstPredictionConnection(*, nodes: Nodes[NW] | None = None, settings: Settings | None = None, **kwargs: Any)[source]

The WetterdienstPredictionConnection class is a connector to the Wetterdienst API for retrieving weather prediction data (MOSMIX). Data can only be read with read_series().

read_series(from_time: datetime, to_time: datetime, nodes: Nodes[NodeWetterdienstPrediction] | None = None, interval: TimeStep = 0, **kwargs: Any) → pd.DataFrame[source]

Read weather prediction data from the Wetterdienst API for the given nodes. The interval parameter is not used for prediction data, as predictions are always given hourly.

Parameters:

from_time – Start time for the data retrieval
to_time – End time for the data retrieval
nodes – Nodes to read data from
interval –
- Not used for prediction data

Returns:

Pandas DataFrame containing the data read from the connection

Example

An example using the Wetterdienst connection:

# Construct a node with the necessary information to request data from the Wetterdienst API
node = (
    NodeWetterdienst(
        "Temperature_Darmstadt",
        "https://opendata.dwd.de",
        "wetterdienst_observation",
        parameter="TEMPERATURE_AIR_MEAN_200",
        station_id="00917",  # Darmstadt observation station ID
        interval=600,  # 10 minutes interval
    ),
)

# start connection from one or multiple nodes
# The 'Connection' class can be used for initializing the connection
connection = WetterdienstConnection.from_node(node)

# Define time interval as datetime values
from_datetime = datetime(2024, 1, 16, 12, 00)
to_datetime = datetime(2024, 1, 16, 18, 00)

# read_series will request data from specified connection and time interval
# The DataFrame will have index with time delta of the specified interval in seconds
# If a node  has a different interval than the requested interval, the data will be resampled.
if isinstance(connection, WetterdienstConnection):
    result = connection.read_series(from_time=from_datetime, to_time=to_datetime, interval=1200)
else:
    raise TypeError("The connection must be an WetterdienstConnection, to be able to call read_series.")
# Check out the WetterdienstConnection documentation for more information
# https://wetterdienst.readthedocs.io/en/latest/data/introduction.html