WetterdienstConnection

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

The WetterdienstConnection class is a connector to the Wetterdienst API for retrieving weather data.

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 | None = None, interval: TimeStep = 60, **kwargs: Any) → pd.DataFrame[source]

Asbtract base method for read_series(). Is fully implemented in subclasses.

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 | 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[AnyNode, Mapping[datetime, 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 | 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 | 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: Any) → pd.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.node.NodeWetterdienstObservation(name: str, url: str, protocol: str, *args: Any, **kwargs: Any)[source]

Node for the Wetterdienst API to get weather observations. For more information see: https://wetterdienst.readthedocs.io/en/latest/data/coverage/dwd/observation.html

static convert_interval_to_resolution(interval: int | str | timedelta) → str[source]

parameter: str: Parameter to read from wetterdienst (e.g HUMIDITY or TEMPERATURE_AIR_200)

station_id: str | None: The id of the weather station

latlon: str | None: latitude and longitude (not necessarily a weather station)

number_of_stations: int | None: Number of stations to be used for the query

name: str: Name for the node.

url: str: URL of the connection.

url_parsed: ParseResult: Parse result object of the URL (in case more post-processing is required).

usr: str | None: Username for login to the connection (default: None).

pwd: str | None: Password for login to the connection (default: None).

interval: str | None: Interval

dtype: Callable | None: Data type of the node (for value conversion). Note that strings will be interpreted as utf-8 encoded. If you do not want this behaviour, use ‘bytes’.

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

The WetterdienstObservationConnection class is a connector to the Wetterdienst API for retrieving weather observation data.

read_series(from_time: datetime, to_time: datetime, nodes: Nodes | 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.node.NodeWetterdienstPrediction(name: str, url: str, protocol: str, *args: Any, **kwargs: Any)[source]

Node for the Wetterdienst API to get weather predictions. For more information see: https://wetterdienst.readthedocs.io/en/latest/data/coverage/dwd/mosmix.html

mosmix_type: str: Type of the MOSMIX prediction. Either ‘SMALL’ or ‘LARGE’

parameter: str: Parameter to read from wetterdienst (e.g HUMIDITY or TEMPERATURE_AIR_200)

station_id: str | None: The id of the weather station

latlon: str | None: latitude and longitude (not necessarily a weather station)

number_of_stations: int | None: Number of stations to be used for the query

name: str: Name for the node.

url: str: URL of the connection.

url_parsed: ParseResult: Parse result object of the URL (in case more post-processing is required).

usr: str | None: Username for login to the connection (default: None).

pwd: str | None: Password for login to the connection (default: None).

interval: str | None: Interval

dtype: Callable | None: Data type of the node (for value conversion). Note that strings will be interpreted as utf-8 encoded. If you do not want this behaviour, use ‘bytes’.

class eta_utility.connectors.WetterdienstPredictionConnection(*, nodes: Nodes | 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).

read_series(from_time: datetime, to_time: datetime, nodes: Nodes | 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 Usage

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 = Connection.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):
    df = 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