Python API

Introduction

The API offers access to different data products. They are outlined in more detail within the Coverage chapter. Please also check out complete examples about how to use the API in the examples folder. In order to explore all features interactively, you might want to try the cli. For managing general settings, please refer to the Settings chapter.

Available APIs

The available APIs can be accessed by the top-level API Wetterdienst. This API also allows the user to discover the available APIs of each service included:

In [1]: from wetterdienst import Wetterdienst

In [2]: Wetterdienst.discover()
Out[2]: 
{'DWD': ['OBSERVATION', 'MOSMIX', 'DMO', 'ROAD', 'RADAR'],
 'ECCC': ['OBSERVATION'],
 'IMGW': ['HYDROLOGY', 'METEOROLOGY'],
 'NOAA': ['GHCN'],
 'WSV': ['PEGEL'],
 'EA': ['HYDROLOGY'],
 'NWS': ['OBSERVATION'],
 'EAUFRANCE': ['HUBEAU'],
 'GEOSPHERE': ['OBSERVATION']}

To load any of the available APIs pass the provider and the network of data to the Wetterdienst API:

In [3]: from wetterdienst import Wetterdienst

In [4]: API = Wetterdienst(provider="dwd", network="observation")

Request arguments

Some of the wetterdienst request arguments e.g. parameter, resolution, period are based on enumerations. This allows the user to define them in three different ways:

  • by using the exact enumeration e.g.
    Parameter.CLIMATE_SUMMARY
  • by using the enumeration name (our proposed name) e.g.
    "climate_summary" or "CLIMATE_SUMMARY"
  • by using the enumeration value (most probably the original name) e.g.
    "kl"

This leaves a lot of flexibility to the user defining the arguments either by what they know from the weather service or what they know from wetterdienst itself.

Typical requests are defined by five arguments:

  • parameter

  • resolution

  • period

  • start_date

  • end_date

Only the parameter, start_date and end_date argument may be needed for a request, as the resolution and period of the data may be fixed (per station or for all data) within individual services. However if the period is not defined, it is assumed that the user wants data for all available periods and the request then is handled that way.

Arguments start_date and end_date are possible replacements for the period argument if the period of a weather service is fixed. In case both arguments are given they are combined thus data is only taken from the given period and between the given time span.

Enumerations for resolution and period arguments are given at the main level e.g.

In [5]: from wetterdienst import Resolution, Period

or at the domain specific level e.g.

In [6]: from wetterdienst.provider.dwd.observation import DwdObservationResolution, DwdObservationPeriod

Both enumerations can be used interchangeably however the weather services enumeration is limited to what resolutions and periods are actually available while the main level enumeration is a summation of all kinds of resolutions and periods found at the different weather services.

Regarding the definition of requested parameters:

Parameters can be requested in three different ways:

  1. Requesting an entire dataset e.g. climate_summary

from wetterdienst.provider.dwd.observation import DwdObservationRequest

request = DwdObservationRequest(
    parameter="kl"
)

  1. Requesting one parameter of a specific resolution without defining the exact dataset.

For each offered resolution we have created a list of unique parameters which are drafted from the entire space of all datasets e.g. when two datasets contain the somewhat similar parameter we do a pre-selection of the dataset from which the parameter is taken.

from wetterdienst.provider.dwd.observation import DwdObservationRequest

request = DwdObservationRequest(
    parameter="precipitation_height"
)

  1. Request a parameter-dataset tuple

    This gives you entire freedom to request a unique parameter-dataset tuple just as you wish.

from wetterdienst.provider.dwd.observation import DwdObservationRequest

request = DwdObservationRequest(
    parameter=[("precipitation_height", "more_precip"), ("temperature_air_mean_2m", "kl")]
)

Data

In case of the DWD, requests have to be defined by resolution and period (respectively start_date and end_date). Use DwdObservationRequest.discover() to discover available parameters based on the given filter arguments.

Stations

all stations

Get station information for a given parameter/dataset, resolution and period.

In [7]: from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution

In [8]: request = DwdObservationRequest(
   ...:     parameter=DwdObservationDataset.PRECIPITATION_MORE,
   ...:     resolution=DwdObservationResolution.DAILY,
   ...:     period=DwdObservationPeriod.HISTORICAL
   ...: )
   ...: 

In [9]: stations = request.all()

In [10]: df = stations.df

In [11]: print(df.head())
shape: (5, 8)
┌────────────┬─────────────┬─────────────┬──────────┬───────────┬────────┬────────────┬────────────┐
│ station_id ┆ start_date  ┆ end_date    ┆ latitude ┆ longitude ┆ height ┆ name       ┆ state      │
│ ---        ┆ ---         ┆ ---         ┆ ---      ┆ ---       ┆ ---    ┆ ---        ┆ ---        │
│ str        ┆ datetime[μs ┆ datetime[μs ┆ f64      ┆ f64       ┆ f64    ┆ str        ┆ str        │
│            ┆ , UTC]      ┆ , UTC]      ┆          ┆           ┆        ┆            ┆            │
╞════════════╪═════════════╪═════════════╪══════════╪═══════════╪════════╪════════════╪════════════╡
│ 00001      ┆ 1912-01-01  ┆ 1986-06-30  ┆ 47.8413  ┆ 8.8493    ┆ 478.0  ┆ Aach       ┆ Baden-Würt │
│            ┆ 00:00:00    ┆ 00:00:00    ┆          ┆           ┆        ┆            ┆ temberg    │
│            ┆ UTC         ┆ UTC         ┆          ┆           ┆        ┆            ┆            │
│ 00002      ┆ 1951-01-01  ┆ 2006-12-31  ┆ 50.8066  ┆ 6.0996    ┆ 138.0  ┆ Aachen (Kl ┆ Nordrhein- │
│            ┆ 00:00:00    ┆ 00:00:00    ┆          ┆           ┆        ┆ äranlage)  ┆ Westfalen  │
│            ┆ UTC         ┆ UTC         ┆          ┆           ┆        ┆            ┆            │
│ 00003      ┆ 1891-01-01  ┆ 2011-03-31  ┆ 50.7827  ┆ 6.0941    ┆ 202.0  ┆ Aachen     ┆ Nordrhein- │
│            ┆ 00:00:00    ┆ 00:00:00    ┆          ┆           ┆        ┆            ┆ Westfalen  │
│            ┆ UTC         ┆ UTC         ┆          ┆           ┆        ┆            ┆            │
│ 00004      ┆ 1951-01-01  ┆ 1979-10-31  ┆ 50.7683  ┆ 6.1207    ┆ 243.0  ┆ Aachen-Bra ┆ Nordrhein- │
│            ┆ 00:00:00    ┆ 00:00:00    ┆          ┆           ┆        ┆ nd         ┆ Westfalen  │
│            ┆ UTC         ┆ UTC         ┆          ┆           ┆        ┆            ┆            │
│ 00006      ┆ 1982-11-01  ┆ 2024-10-05  ┆ 48.8361  ┆ 10.0598   ┆ 455.0  ┆ Aalen-Unte ┆ Baden-Würt │
│            ┆ 00:00:00    ┆ 00:00:00    ┆          ┆           ┆        ┆ rrombach   ┆ temberg    │
│            ┆ UTC         ┆ UTC         ┆          ┆           ┆        ┆            ┆            │
└────────────┴─────────────┴─────────────┴──────────┴───────────┴────────┴────────────┴────────────┘

The function returns a Polars DataFrame with information about the available stations.

filter by station id

In [12]: from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution

In [13]: request = DwdObservationRequest(
   ....:     parameter=DwdObservationDataset.PRECIPITATION_MORE,
   ....:     resolution=DwdObservationResolution.DAILY,
   ....:     period=DwdObservationPeriod.HISTORICAL
   ....: )
   ....: 

In [14]: stations = request.filter_by_station_id(station_id=("01048", ))

In [15]: df = stations.df

In [16]: print(df.head())
shape: (1, 8)
┌────────────┬──────────────┬──────────────┬──────────┬───────────┬────────┬─────────────┬─────────┐
│ station_id ┆ start_date   ┆ end_date     ┆ latitude ┆ longitude ┆ height ┆ name        ┆ state   │
│ ---        ┆ ---          ┆ ---          ┆ ---      ┆ ---       ┆ ---    ┆ ---         ┆ ---     │
│ str        ┆ datetime[μs, ┆ datetime[μs, ┆ f64      ┆ f64       ┆ f64    ┆ str         ┆ str     │
│            ┆ UTC]         ┆ UTC]         ┆          ┆           ┆        ┆             ┆         │
╞════════════╪══════════════╪══════════════╪══════════╪═══════════╪════════╪═════════════╪═════════╡
│ 01048      ┆ 1926-04-25   ┆ 2024-10-05   ┆ 51.1278  ┆ 13.7543   ┆ 228.0  ┆ Dresden-Klo ┆ Sachsen │
│            ┆ 00:00:00 UTC ┆ 00:00:00 UTC ┆          ┆           ┆        ┆ tzsche      ┆         │
└────────────┴──────────────┴──────────────┴──────────┴───────────┴────────┴─────────────┴─────────┘

filter by name

In [17]: from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution

In [18]: request = DwdObservationRequest(
   ....:     parameter=DwdObservationDataset.PRECIPITATION_MORE,
   ....:     resolution=DwdObservationResolution.DAILY,
   ....:     period=DwdObservationPeriod.HISTORICAL
   ....: )
   ....: 

In [19]: stations = request.filter_by_name(name="Dresden-Klotzsche")

In [20]: df = stations.df

In [21]: print(df.head())
shape: (1, 8)
┌────────────┬──────────────┬──────────────┬──────────┬───────────┬────────┬─────────────┬─────────┐
│ station_id ┆ start_date   ┆ end_date     ┆ latitude ┆ longitude ┆ height ┆ name        ┆ state   │
│ ---        ┆ ---          ┆ ---          ┆ ---      ┆ ---       ┆ ---    ┆ ---         ┆ ---     │
│ str        ┆ datetime[μs, ┆ datetime[μs, ┆ f64      ┆ f64       ┆ f64    ┆ str         ┆ str     │
│            ┆ UTC]         ┆ UTC]         ┆          ┆           ┆        ┆             ┆         │
╞════════════╪══════════════╪══════════════╪══════════╪═══════════╪════════╪═════════════╪═════════╡
│ 01048      ┆ 1926-04-25   ┆ 2024-10-05   ┆ 51.1278  ┆ 13.7543   ┆ 228.0  ┆ Dresden-Klo ┆ Sachsen │
│            ┆ 00:00:00 UTC ┆ 00:00:00 UTC ┆          ┆           ┆        ┆ tzsche      ┆         │
└────────────┴──────────────┴──────────────┴──────────┴───────────┴────────┴─────────────┴─────────┘

filter by distance

Distance in kilometers (default)

In [22]: import datetime as dt

In [23]: from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution

In [24]: hamburg = (53.551086, 9.993682)

In [25]: request = DwdObservationRequest(
   ....:     parameter=DwdObservationDataset.TEMPERATURE_AIR,
   ....:     resolution=DwdObservationResolution.HOURLY,
   ....:     start_date=dt.datetime(2020, 1, 1),
   ....:     end_date=dt.datetime(2020, 1, 20)
   ....: )
   ....: 

In [26]: stations = request.filter_by_distance(latlon=hamburg, distance=30, unit="km")

In [27]: df = stations.df

In [28]: print(df.head())
shape: (5, 9)
┌────────────┬────────────┬────────────┬──────────┬───┬────────┬───────────┬───────────┬───────────┐
│ station_id ┆ start_date ┆ end_date   ┆ latitude ┆ … ┆ height ┆ name      ┆ state     ┆ distance  │
│ ---        ┆ ---        ┆ ---        ┆ ---      ┆   ┆ ---    ┆ ---       ┆ ---       ┆ ---       │
│ str        ┆ datetime[μ ┆ datetime[μ ┆ f64      ┆   ┆ f64    ┆ str       ┆ str       ┆ f64       │
│            ┆ s, UTC]    ┆ s, UTC]    ┆          ┆   ┆        ┆           ┆           ┆           │
╞════════════╪════════════╪════════════╪══════════╪═══╪════════╪═══════════╪═══════════╪═══════════╡
│ 01975      ┆ 1949-01-01 ┆ 2024-10-05 ┆ 53.6332  ┆ … ┆ 11.0   ┆ Hamburg-F ┆ Hamburg   ┆ 9.138089  │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ uhlsbütte ┆           ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ l         ┆           ┆           │
│ 01981      ┆ 2005-03-01 ┆ 2024-10-05 ┆ 53.4776  ┆ … ┆ 4.0    ┆ Hamburg-N ┆ Hamburg   ┆ 10.427851 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ euwiedent ┆           ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ hal       ┆           ┆           │
│ 00052      ┆ 1976-01-01 ┆ 1988-01-01 ┆ 53.6623  ┆ … ┆ 46.0   ┆ Ahrensbur ┆ Schleswig ┆ 18.341667 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ g-Wulfsdo ┆ -Holstein ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ rf        ┆           ┆           │
│ 00760      ┆ 2017-12-01 ┆ 2024-10-05 ┆ 53.3629  ┆ … ┆ 83.0   ┆ Rosengart ┆ Niedersac ┆ 21.187451 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ en-Klecke ┆ hsen      ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ n         ┆           ┆           │
│ 04039      ┆ 1988-01-11 ┆ 2024-10-05 ┆ 53.7331  ┆ … ┆ 11.0   ┆ Quickborn ┆ Schleswig ┆ 21.637285 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆           ┆ -Holstein ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆           ┆           ┆           │
└────────────┴────────────┴────────────┴──────────┴───┴────────┴───────────┴───────────┴───────────┘

Distance in miles

In [29]: import datetime as dt

In [30]: from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution

In [31]: hamburg = (53.551086, 9.993682)

In [32]: request = DwdObservationRequest(
   ....:     parameter=DwdObservationDataset.TEMPERATURE_AIR,
   ....:     resolution=DwdObservationResolution.HOURLY,
   ....:     start_date=dt.datetime(2020, 1, 1),
   ....:     end_date=dt.datetime(2020, 1, 20)
   ....: )
   ....: 

In [33]: stations = request.filter_by_distance(latlon=hamburg, distance=30, unit="mi")

In [34]: df = stations.df

In [35]: print(df.head())
shape: (5, 9)
┌────────────┬────────────┬────────────┬──────────┬───┬────────┬───────────┬───────────┬───────────┐
│ station_id ┆ start_date ┆ end_date   ┆ latitude ┆ … ┆ height ┆ name      ┆ state     ┆ distance  │
│ ---        ┆ ---        ┆ ---        ┆ ---      ┆   ┆ ---    ┆ ---       ┆ ---       ┆ ---       │
│ str        ┆ datetime[μ ┆ datetime[μ ┆ f64      ┆   ┆ f64    ┆ str       ┆ str       ┆ f64       │
│            ┆ s, UTC]    ┆ s, UTC]    ┆          ┆   ┆        ┆           ┆           ┆           │
╞════════════╪════════════╪════════════╪══════════╪═══╪════════╪═══════════╪═══════════╪═══════════╡
│ 01975      ┆ 1949-01-01 ┆ 2024-10-05 ┆ 53.6332  ┆ … ┆ 11.0   ┆ Hamburg-F ┆ Hamburg   ┆ 9.138089  │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ uhlsbütte ┆           ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ l         ┆           ┆           │
│ 01981      ┆ 2005-03-01 ┆ 2024-10-05 ┆ 53.4776  ┆ … ┆ 4.0    ┆ Hamburg-N ┆ Hamburg   ┆ 10.427851 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ euwiedent ┆           ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ hal       ┆           ┆           │
│ 00052      ┆ 1976-01-01 ┆ 1988-01-01 ┆ 53.6623  ┆ … ┆ 46.0   ┆ Ahrensbur ┆ Schleswig ┆ 18.341667 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ g-Wulfsdo ┆ -Holstein ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ rf        ┆           ┆           │
│ 00760      ┆ 2017-12-01 ┆ 2024-10-05 ┆ 53.3629  ┆ … ┆ 83.0   ┆ Rosengart ┆ Niedersac ┆ 21.187451 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ en-Klecke ┆ hsen      ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ n         ┆           ┆           │
│ 04039      ┆ 1988-01-11 ┆ 2024-10-05 ┆ 53.7331  ┆ … ┆ 11.0   ┆ Quickborn ┆ Schleswig ┆ 21.637285 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆           ┆ -Holstein ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆           ┆           ┆           │
└────────────┴────────────┴────────────┴──────────┴───┴────────┴───────────┴───────────┴───────────┘

filter by rank

In [36]: import datetime as dt

In [37]: from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution

In [38]: hamburg = (53.551086, 9.993682)

In [39]: request = DwdObservationRequest(
   ....:     parameter=DwdObservationDataset.TEMPERATURE_AIR,
   ....:     resolution=DwdObservationResolution.HOURLY,
   ....:     start_date=dt.datetime(2020, 1, 1),
   ....:     end_date=dt.datetime(2020, 1, 20)
   ....: )
   ....: 

In [40]: stations = request.filter_by_rank(latlon=hamburg, rank=5)

In [41]: df = stations.df

In [42]: print(df.head())
shape: (5, 9)
┌────────────┬────────────┬────────────┬──────────┬───┬────────┬───────────┬───────────┬───────────┐
│ station_id ┆ start_date ┆ end_date   ┆ latitude ┆ … ┆ height ┆ name      ┆ state     ┆ distance  │
│ ---        ┆ ---        ┆ ---        ┆ ---      ┆   ┆ ---    ┆ ---       ┆ ---       ┆ ---       │
│ str        ┆ datetime[μ ┆ datetime[μ ┆ f64      ┆   ┆ f64    ┆ str       ┆ str       ┆ f64       │
│            ┆ s, UTC]    ┆ s, UTC]    ┆          ┆   ┆        ┆           ┆           ┆           │
╞════════════╪════════════╪════════════╪══════════╪═══╪════════╪═══════════╪═══════════╪═══════════╡
│ 01975      ┆ 1949-01-01 ┆ 2024-10-05 ┆ 53.6332  ┆ … ┆ 11.0   ┆ Hamburg-F ┆ Hamburg   ┆ 9.138089  │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ uhlsbütte ┆           ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ l         ┆           ┆           │
│ 01981      ┆ 2005-03-01 ┆ 2024-10-05 ┆ 53.4776  ┆ … ┆ 4.0    ┆ Hamburg-N ┆ Hamburg   ┆ 10.427851 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ euwiedent ┆           ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ hal       ┆           ┆           │
│ 00052      ┆ 1976-01-01 ┆ 1988-01-01 ┆ 53.6623  ┆ … ┆ 46.0   ┆ Ahrensbur ┆ Schleswig ┆ 18.341667 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ g-Wulfsdo ┆ -Holstein ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ rf        ┆           ┆           │
│ 00760      ┆ 2017-12-01 ┆ 2024-10-05 ┆ 53.3629  ┆ … ┆ 83.0   ┆ Rosengart ┆ Niedersac ┆ 21.187451 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆ en-Klecke ┆ hsen      ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆ n         ┆           ┆           │
│ 04039      ┆ 1988-01-11 ┆ 2024-10-05 ┆ 53.7331  ┆ … ┆ 11.0   ┆ Quickborn ┆ Schleswig ┆ 21.637285 │
│            ┆ 00:00:00   ┆ 00:00:00   ┆          ┆   ┆        ┆           ┆ -Holstein ┆           │
│            ┆ UTC        ┆ UTC        ┆          ┆   ┆        ┆           ┆           ┆           │
└────────────┴────────────┴────────────┴──────────┴───┴────────┴───────────┴───────────┴───────────┘

filter by bbox

In [43]: import datetime as dt

In [44]: from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution

In [45]: bbox = (8.9, 50.0, 8.91, 50.01)

In [46]: request = DwdObservationRequest(
   ....:     parameter=DwdObservationDataset.TEMPERATURE_AIR,
   ....:     resolution=DwdObservationResolution.HOURLY,
   ....:     start_date=dt.datetime(2020, 1, 1),
   ....:     end_date=dt.datetime(2020, 1, 20)
   ....: )
   ....: 

In [47]: stations = request.filter_by_bbox(*bbox)

In [48]: df = stations.df

In [49]: print(df.head())
shape: (0, 8)
┌────────────┬──────────────┬───────────────────┬──────────┬───────────┬────────┬──────┬───────┐
│ station_id ┆ start_date   ┆ end_date          ┆ latitude ┆ longitude ┆ height ┆ name ┆ state │
│ ---        ┆ ---          ┆ ---               ┆ ---      ┆ ---       ┆ ---    ┆ ---  ┆ ---   │
│ str        ┆ datetime[μs, ┆ datetime[μs, UTC] ┆ f64      ┆ f64       ┆ f64    ┆ str  ┆ str   │
│            ┆ UTC]         ┆                   ┆          ┆           ┆        ┆      ┆       │
╞════════════╪══════════════╪═══════════════════╪══════════╪═══════════╪════════╪══════╪═══════╡
└────────────┴──────────────┴───────────────────┴──────────┴───────────┴────────┴──────┴───────┘

Values

Values are just an extension of requests:

In [50]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [51]: from wetterdienst import Settings

# if no settings are provided, default settings are used which are
# Settings(ts_shape="long", ts_humanize=True, ts_si_units=True)
In [52]: request = DwdObservationRequest(
   ....:     parameter=["kl", "solar"],
   ....:     resolution="daily",
   ....:     start_date="1990-01-01",
   ....:     end_date="2020-01-01",
   ....: )
   ....: 

In [53]: stations = request.filter_by_station_id(station_id=("00003", "01048"))

From here you can query data by station:

In [54]: for result in stations.values.query():
   ....:     print(result.df.drop_nulls().head())
   ....: 
shape: (5, 6)
┌────────────┬─────────────────┬───────────────────┬─────────────────────────┬───────┬─────────┐
│ station_id ┆ dataset         ┆ parameter         ┆ date                    ┆ value ┆ quality │
│ ---        ┆ ---             ┆ ---               ┆ ---                     ┆ ---   ┆ ---     │
│ str        ┆ str             ┆ str               ┆ datetime[μs, UTC]       ┆ f64   ┆ f64     │
╞════════════╪═════════════════╪═══════════════════╪═════════════════════════╪═══════╪═════════╡
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-01 00:00:00 UTC ┆ 100.0 ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-02 00:00:00 UTC ┆ 100.0 ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-03 00:00:00 UTC ┆ 58.75 ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-04 00:00:00 UTC ┆ 75.0  ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-05 00:00:00 UTC ┆ 96.25 ┆ 10.0    │
└────────────┴─────────────────┴───────────────────┴─────────────────────────┴───────┴─────────┘
shape: (5, 6)
┌────────────┬─────────────────┬───────────────────┬─────────────────────────┬───────┬─────────┐
│ station_id ┆ dataset         ┆ parameter         ┆ date                    ┆ value ┆ quality │
│ ---        ┆ ---             ┆ ---               ┆ ---                     ┆ ---   ┆ ---     │
│ str        ┆ str             ┆ str               ┆ datetime[μs, UTC]       ┆ f64   ┆ f64     │
╞════════════╪═════════════════╪═══════════════════╪═════════════════════════╪═══════╪═════════╡
│ 01048      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-01 00:00:00 UTC ┆ 100.0 ┆ 10.0    │
│ 01048      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-02 00:00:00 UTC ┆ 100.0 ┆ 10.0    │
│ 01048      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-03 00:00:00 UTC ┆ 91.25 ┆ 10.0    │
│ 01048      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-04 00:00:00 UTC ┆ 28.75 ┆ 10.0    │
│ 01048      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-05 00:00:00 UTC ┆ 91.25 ┆ 10.0    │
└────────────┴─────────────────┴───────────────────┴─────────────────────────┴───────┴─────────┘

Query data all together:

In [55]: df = stations.values.all().df.drop_nulls()

In [56]: print(df.head())
shape: (5, 6)
┌────────────┬─────────────────┬───────────────────┬─────────────────────────┬───────┬─────────┐
│ station_id ┆ dataset         ┆ parameter         ┆ date                    ┆ value ┆ quality │
│ ---        ┆ ---             ┆ ---               ┆ ---                     ┆ ---   ┆ ---     │
│ str        ┆ str             ┆ str               ┆ datetime[μs, UTC]       ┆ f64   ┆ f64     │
╞════════════╪═════════════════╪═══════════════════╪═════════════════════════╪═══════╪═════════╡
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-01 00:00:00 UTC ┆ 100.0 ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-02 00:00:00 UTC ┆ 100.0 ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-03 00:00:00 UTC ┆ 58.75 ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-04 00:00:00 UTC ┆ 75.0  ┆ 10.0    │
│ 00003      ┆ climate_summary ┆ cloud_cover_total ┆ 1990-01-05 00:00:00 UTC ┆ 96.25 ┆ 10.0    │
└────────────┴─────────────────┴───────────────────┴─────────────────────────┴───────┴─────────┘

This gives us the most options to work with the data, getting multiple parameters at once, parsed nicely into column structure with improved parameter names. Instead of start_date and end_date you may as well want to use period to update your database once in a while with a fixed set of records.

In case you use filter_by_rank you may want to skip empty stations. We can use the Settings from Settings to achieve that:

In [57]: from wetterdienst import Settings

In [58]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [59]: settings = Settings(ts_skip_empty=True, ts_skip_criteria="min", ignore_env=True)

In [60]: karlsruhe = (49.19780976647141, 8.135207205143768)

In [61]: request = DwdObservationRequest(
   ....:     parameter=["kl", "solar"],
   ....:     resolution="daily",
   ....:     start_date="2021-01-01",
   ....:     end_date="2021-12-31",
   ....:     settings=settings,
   ....: )
   ....: 

In [62]: stations = request.filter_by_rank(latlon=karlsruhe, rank=2)

In [63]: values = stations.values.all()

In [64]: print(values.df.head())
shape: (0, 0)
┌┐
╞╡
└┘

# df_stations has only stations that appear in the values
In [65]: print(values.df_stations.head())
shape: (0, 9)
┌────────────┬──────────────┬────────────────────┬──────────┬───┬────────┬──────┬───────┬──────────┐
│ station_id ┆ start_date   ┆ end_date           ┆ latitude ┆ … ┆ height ┆ name ┆ state ┆ distance │
│ ---        ┆ ---          ┆ ---                ┆ ---      ┆   ┆ ---    ┆ ---  ┆ ---   ┆ ---      │
│ str        ┆ datetime[μs, ┆ datetime[μs, UTC]  ┆ f64      ┆   ┆ f64    ┆ str  ┆ str   ┆ f64      │
│            ┆ UTC]         ┆                    ┆          ┆   ┆        ┆      ┆       ┆          │
╞════════════╪══════════════╪════════════════════╪══════════╪═══╪════════╪══════╪═══════╪══════════╡
└────────────┴──────────────┴────────────────────┴──────────┴───┴────────┴──────┴───────┴──────────┘

Interpolation

Occasionally, you may require data specific to your precise location rather than relying on values measured at a station’s location. To address this need, we have introduced an interpolation feature, enabling you to interpolate data from nearby stations to your exact coordinates. The function leverages the four closest stations to your specified latitude and longitude and employs the bilinear interpolation method provided by the scipy package (interp2d) to interpolate the given parameter values. Currently, this interpolation feature is exclusive to DWDObservationRequest and parameters temperature_air_mean_2m, wind_speed, precipitation_height. As it is in its early stages, we welcome feedback to enhance and refine its functionality. Interpolation by nearby stations is limited to a distance of 40 km by default (20.0 km for precipitation). You can change this by setting the ts_interpolation_station_distance setting. An example is shown below.

The graphic below shows values of the parameter temperature_air_mean_2m from multiple stations measured at the same time. The blue points represent the position of a station and includes the measured value. The red point represents the position of the interpolation and includes the interpolated value.

../_images/interpolation.png

Values represented as a table:

Individual station values

station_id

parameter

date

value

02480

temperature_air_mean_2m

2022-01-02 00:00:00+00:00

278.15

04411

temperature_air_mean_2m

2022-01-02 00:00:00+00:00

277.15

07341

temperature_air_mean_2m

2022-01-02 00:00:00+00:00

278.35

00917

temperature_air_mean_2m

2022-01-02 00:00:00+00:00

276.25

The interpolated value looks like this:

Interpolated value

parameter

date

value

temperature_air_mean_2m

2022-01-02 00:00:00+00:00

277.65

 
In [66]: import datetime as dt

In [67]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [68]: from wetterdienst import Parameter, Resolution

In [69]: request = DwdObservationRequest(
   ....:     parameter=Parameter.TEMPERATURE_AIR_MEAN_2M,
   ....:     resolution=Resolution.HOURLY,
   ....:     start_date=dt.datetime(2022, 1, 1),
   ....:     end_date=dt.datetime(2022, 1, 20),
   ....: )
   ....: 

In [70]: values = request.interpolate(latlon=(50.0, 8.9))

In [71]: df = values.df

In [72]: print(df.head())
shape: (5, 6)
┌────────────┬────────────────────┬───────────────────┬────────┬───────────────┬───────────────────┐
│ station_id ┆ parameter          ┆ date              ┆ value  ┆ distance_mean ┆ taken_station_ids │
│ ---        ┆ ---                ┆ ---               ┆ ---    ┆ ---           ┆ ---               │
│ str        ┆ str                ┆ datetime[μs, UTC] ┆ f64    ┆ f64           ┆ list[str]         │
╞════════════╪════════════════════╪═══════════════════╪════════╪═══════════════╪═══════════════════╡
│ f674568e   ┆ temperature_air_me ┆ 2022-01-01        ┆ 285.07 ┆ 13.37         ┆ ["02480",         │
│            ┆ an_2m              ┆ 00:00:00 UTC      ┆        ┆               ┆ "04411", …        │
│            ┆                    ┆                   ┆        ┆               ┆ "00917"]          │
│ f674568e   ┆ temperature_air_me ┆ 2022-01-01        ┆ 285.04 ┆ 13.37         ┆ ["02480",         │
│            ┆ an_2m              ┆ 01:00:00 UTC      ┆        ┆               ┆ "04411", …        │
│            ┆                    ┆                   ┆        ┆               ┆ "00917"]          │
│ f674568e   ┆ temperature_air_me ┆ 2022-01-01        ┆ 284.75 ┆ 13.37         ┆ ["02480",         │
│            ┆ an_2m              ┆ 02:00:00 UTC      ┆        ┆               ┆ "04411", …        │
│            ┆                    ┆                   ┆        ┆               ┆ "00917"]          │
│ f674568e   ┆ temperature_air_me ┆ 2022-01-01        ┆ 284.69 ┆ 13.37         ┆ ["02480",         │
│            ┆ an_2m              ┆ 03:00:00 UTC      ┆        ┆               ┆ "04411", …        │
│            ┆                    ┆                   ┆        ┆               ┆ "00917"]          │
│ f674568e   ┆ temperature_air_me ┆ 2022-01-01        ┆ 284.51 ┆ 13.37         ┆ ["02480",         │
│            ┆ an_2m              ┆ 04:00:00 UTC      ┆        ┆               ┆ "04411", …        │
│            ┆                    ┆                   ┆        ┆               ┆ "00917"]          │
└────────────┴────────────────────┴───────────────────┴────────┴───────────────┴───────────────────┘

Instead of a latlon you may alternatively use an existing station id for which to interpolate values in a manner of getting a more complete dataset:

In [73]: import datetime as dt

In [74]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [75]: from wetterdienst import Parameter, Resolution

In [76]: request = DwdObservationRequest(
   ....:     parameter=Parameter.TEMPERATURE_AIR_MEAN_2M,
   ....:     resolution=Resolution.HOURLY,
   ....:     start_date=dt.datetime(2022, 1, 1),
   ....:     end_date=dt.datetime(2022, 1, 20),
   ....: )
   ....: 

In [77]: values = request.interpolate_by_station_id(station_id="02480")

In [78]: df = values.df

In [79]: print(df.head())
shape: (5, 6)
┌────────────┬────────────────────┬───────────────────┬────────┬───────────────┬───────────────────┐
│ station_id ┆ parameter          ┆ date              ┆ value  ┆ distance_mean ┆ taken_station_ids │
│ ---        ┆ ---                ┆ ---               ┆ ---    ┆ ---           ┆ ---               │
│ str        ┆ str                ┆ datetime[μs, UTC] ┆ f64    ┆ f64           ┆ list[str]         │
╞════════════╪════════════════════╪═══════════════════╪════════╪═══════════════╪═══════════════════╡
│ 7f2e709d   ┆ temperature_air_me ┆ 2022-01-01        ┆ 285.05 ┆ 0.0           ┆ ["02480"]         │
│            ┆ an_2m              ┆ 00:00:00 UTC      ┆        ┆               ┆                   │
│ 7f2e709d   ┆ temperature_air_me ┆ 2022-01-01        ┆ 284.95 ┆ 0.0           ┆ ["02480"]         │
│            ┆ an_2m              ┆ 01:00:00 UTC      ┆        ┆               ┆                   │
│ 7f2e709d   ┆ temperature_air_me ┆ 2022-01-01        ┆ 285.15 ┆ 0.0           ┆ ["02480"]         │
│            ┆ an_2m              ┆ 02:00:00 UTC      ┆        ┆               ┆                   │
│ 7f2e709d   ┆ temperature_air_me ┆ 2022-01-01        ┆ 284.75 ┆ 0.0           ┆ ["02480"]         │
│            ┆ an_2m              ┆ 03:00:00 UTC      ┆        ┆               ┆                   │
│ 7f2e709d   ┆ temperature_air_me ┆ 2022-01-01        ┆ 284.75 ┆ 0.0           ┆ ["02480"]         │
│            ┆ an_2m              ┆ 04:00:00 UTC      ┆        ┆               ┆                   │
└────────────┴────────────────────┴───────────────────┴────────┴───────────────┴───────────────────┘

Increase maximum distance for interpolation:

In [80]: import datetime as dt

In [81]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [82]: from wetterdienst import Parameter, Resolution, Settings

In [83]: settings = Settings(ts_interpolation_station_distance={"precipitation_height": 25.0})

In [84]: request = DwdObservationRequest(
   ....:     parameter=Parameter.PRECIPITATION_HEIGHT,
   ....:     resolution=Resolution.HOURLY,
   ....:     start_date=dt.datetime(2022, 1, 1),
   ....:     end_date=dt.datetime(2022, 1, 20),
   ....:     settings=settings
   ....: )
   ....: 

In [85]: values = request.interpolate(latlon=(52.8, 12.9))

In [86]: df = values.df

In [87]: print(df.head())
shape: (5, 6)
┌────────────┬────────────────────┬────────────────────┬───────┬───────────────┬───────────────────┐
│ station_id ┆ parameter          ┆ date               ┆ value ┆ distance_mean ┆ taken_station_ids │
│ ---        ┆ ---                ┆ ---                ┆ ---   ┆ ---           ┆ ---               │
│ str        ┆ str                ┆ datetime[μs, UTC]  ┆ f64   ┆ f64           ┆ list[str]         │
╞════════════╪════════════════════╪════════════════════╪═══════╪═══════════════╪═══════════════════╡
│ 084631fd   ┆ precipitation_heig ┆ 2022-01-01         ┆ 0.0   ┆ 18.33         ┆ ["02733",         │
│            ┆ ht                 ┆ 00:00:00 UTC       ┆       ┆               ┆ "00096", …        │
│            ┆                    ┆                    ┆       ┆               ┆ "03205"]          │
│ 084631fd   ┆ precipitation_heig ┆ 2022-01-01         ┆ 0.17  ┆ 18.33         ┆ ["02733",         │
│            ┆ ht                 ┆ 01:00:00 UTC       ┆       ┆               ┆ "00096", …        │
│            ┆                    ┆                    ┆       ┆               ┆ "03205"]          │
│ 084631fd   ┆ precipitation_heig ┆ 2022-01-01         ┆ 0.35  ┆ 18.33         ┆ ["02733",         │
│            ┆ ht                 ┆ 02:00:00 UTC       ┆       ┆               ┆ "00096", …        │
│            ┆                    ┆                    ┆       ┆               ┆ "03205"]          │
│ 084631fd   ┆ precipitation_heig ┆ 2022-01-01         ┆ 0.22  ┆ 18.33         ┆ ["02733",         │
│            ┆ ht                 ┆ 03:00:00 UTC       ┆       ┆               ┆ "00096", …        │
│            ┆                    ┆                    ┆       ┆               ┆ "03205"]          │
│ 084631fd   ┆ precipitation_heig ┆ 2022-01-01         ┆ 0.0   ┆ 18.33         ┆ ["02733",         │
│            ┆ ht                 ┆ 04:00:00 UTC       ┆       ┆               ┆ "00096", …        │
│            ┆                    ┆                    ┆       ┆               ┆ "03205"]          │
└────────────┴────────────────────┴────────────────────┴───────┴───────────────┴───────────────────┘

Summary

Similar to interpolation you may sometimes want to combine multiple stations to get a complete list of data. For that reason you can use .summary(latlon), which goes through nearest stations and combines data from them meaningful. The following figure visualizes how summary works. The first graph shows the summarized values of the parameter temperature_air_mean_2m from multiple stations.

../_images/summary.png

The code to execute the summary is given below. It currently only works for DwdObservationRequest and individual parameters. Currently the following parameters are supported (more will be added if useful): temperature_air_mean_2m, wind_speed, precipitation_height.

In [88]: import datetime as dt

In [89]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [90]: from wetterdienst import Parameter, Resolution

In [91]: request = DwdObservationRequest(
   ....:     parameter=Parameter.TEMPERATURE_AIR_MEAN_2M,
   ....:     resolution=Resolution.HOURLY,
   ....:     start_date=dt.datetime(2022, 1, 1),
   ....:     end_date=dt.datetime(2022, 1, 20),
   ....: )
   ....: 

In [92]: values = request.summarize(latlon=(50.0, 8.9))

In [93]: df = values.df

In [94]: print(df.head())
shape: (5, 6)
┌────────────┬───────────────────────┬──────────────────────┬────────┬──────────┬──────────────────┐
│ station_id ┆ parameter             ┆ date                 ┆ value  ┆ distance ┆ taken_station_id │
│ ---        ┆ ---                   ┆ ---                  ┆ ---    ┆ ---      ┆ ---              │
│ str        ┆ str                   ┆ datetime[μs, UTC]    ┆ f64    ┆ f64      ┆ str              │
╞════════════╪═══════════════════════╪══════════════════════╪════════╪══════════╪══════════════════╡
│ fc5aa952   ┆ temperature_air_mean_ ┆ 2022-01-01 00:00:00  ┆ 285.05 ┆ 9.76     ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ fc5aa952   ┆ temperature_air_mean_ ┆ 2022-01-01 01:00:00  ┆ 284.95 ┆ 9.76     ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ fc5aa952   ┆ temperature_air_mean_ ┆ 2022-01-01 02:00:00  ┆ 285.15 ┆ 9.76     ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ fc5aa952   ┆ temperature_air_mean_ ┆ 2022-01-01 03:00:00  ┆ 284.75 ┆ 9.76     ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ fc5aa952   ┆ temperature_air_mean_ ┆ 2022-01-01 04:00:00  ┆ 284.75 ┆ 9.76     ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
└────────────┴───────────────────────┴──────────────────────┴────────┴──────────┴──────────────────┘

Instead of a latlon you may alternatively use an existing station id for which to summarize values in a manner of getting a more complete dataset:

In [95]: import datetime as dt

In [96]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [97]: from wetterdienst import Parameter, Resolution

In [98]: request = DwdObservationRequest(
   ....:     parameter=Parameter.TEMPERATURE_AIR_MEAN_2M,
   ....:     resolution=Resolution.HOURLY,
   ....:     start_date=dt.datetime(2022, 1, 1),
   ....:     end_date=dt.datetime(2022, 1, 20),
   ....: )
   ....: 

In [99]: values = request.summarize_by_station_id(station_id="02480")

In [100]: df = values.df

In [101]: print(df.head())
shape: (5, 6)
┌────────────┬───────────────────────┬──────────────────────┬────────┬──────────┬──────────────────┐
│ station_id ┆ parameter             ┆ date                 ┆ value  ┆ distance ┆ taken_station_id │
│ ---        ┆ ---                   ┆ ---                  ┆ ---    ┆ ---      ┆ ---              │
│ str        ┆ str                   ┆ datetime[μs, UTC]    ┆ f64    ┆ f64      ┆ str              │
╞════════════╪═══════════════════════╪══════════════════════╪════════╪══════════╪══════════════════╡
│ 73becd44   ┆ temperature_air_mean_ ┆ 2022-01-01 00:00:00  ┆ 285.05 ┆ 0.0      ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ 73becd44   ┆ temperature_air_mean_ ┆ 2022-01-01 01:00:00  ┆ 284.95 ┆ 0.0      ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ 73becd44   ┆ temperature_air_mean_ ┆ 2022-01-01 02:00:00  ┆ 285.15 ┆ 0.0      ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ 73becd44   ┆ temperature_air_mean_ ┆ 2022-01-01 03:00:00  ┆ 284.75 ┆ 0.0      ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
│ 73becd44   ┆ temperature_air_mean_ ┆ 2022-01-01 04:00:00  ┆ 284.75 ┆ 0.0      ┆ 02480            │
│            ┆ 2m                    ┆ UTC                  ┆        ┆          ┆                  │
└────────────┴───────────────────────┴──────────────────────┴────────┴──────────┴──────────────────┘

Format

To Dict

In [102]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [103]: request = DwdObservationRequest(
   .....:     parameter="temperature_air_mean_2m",
   .....:     resolution="daily",
   .....:     start_date="2020-01-01",
   .....:     end_date="2020-01-02"
   .....: )
   .....: 

In [104]: stations = request.filter_by_station_id(station_id="01048")

In [105]: values = stations.values.all()

In [106]: print(values.to_dict(with_metadata=True, with_stations=True))
{'metadata': {'provider': {'name_local': 'Deutscher Wetterdienst', 'name_english': 'German Weather Service', 'country': 'Germany', 'copyright': '© Deutscher Wetterdienst (DWD), Climate Data Center (CDC)', 'url': 'https://opendata.dwd.de/climate_environment/CDC/'}, 'producer': {'name': 'wetterdienst', 'version': '0.97.0', 'repository': 'https://github.com/earthobservations/wetterdienst', 'documentation': 'https://wetterdienst.readthedocs.io', 'doi': '10.5281/zenodo.3960624'}}, 'stations': [{'station_id': '01048', 'start_date': '1934-01-01T00:00:00+00:00', 'end_date': '2024-10-05T00:00:00+00:00', 'latitude': 51.1278, 'longitude': 13.7543, 'height': 228.0, 'name': 'Dresden-Klotzsche', 'state': 'Sachsen'}], 'values': [{'station_id': '01048', 'dataset': 'climate_summary', 'parameter': 'temperature_air_mean_2m', 'date': '2020-01-01T00:00:00+00:00', 'value': 275.54999999999995, 'quality': 10.0}, {'station_id': '01048', 'dataset': 'climate_summary', 'parameter': 'temperature_air_mean_2m', 'date': '2020-01-02T00:00:00+00:00', 'value': 273.34999999999997, 'quality': 10.0}]}

To Json

In [107]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [108]: request = DwdObservationRequest(
   .....:     parameter="temperature_air_mean_2m",
   .....:     resolution="daily",
   .....:     start_date="2020-01-01",
   .....:     end_date="2020-01-02"
   .....: )
   .....: 

In [109]: stations = request.filter_by_station_id(station_id="01048")

In [110]: values = stations.values.all()

In [111]: print(values.to_json(with_metadata=True, with_stations=True))
{
    "metadata": {
        "provider": {
            "name_local": "Deutscher Wetterdienst",
            "name_english": "German Weather Service",
            "country": "Germany",
            "copyright": "\u00a9 Deutscher Wetterdienst (DWD), Climate Data Center (CDC)",
            "url": "https://opendata.dwd.de/climate_environment/CDC/"
        },
        "producer": {
            "name": "wetterdienst",
            "version": "0.97.0",
            "repository": "https://github.com/earthobservations/wetterdienst",
            "documentation": "https://wetterdienst.readthedocs.io",
            "doi": "10.5281/zenodo.3960624"
        }
    },
    "stations": [
        {
            "station_id": "01048",
            "start_date": "1934-01-01T00:00:00+00:00",
            "end_date": "2024-10-05T00:00:00+00:00",
            "latitude": 51.1278,
            "longitude": 13.7543,
            "height": 228.0,
            "name": "Dresden-Klotzsche",
            "state": "Sachsen"
        }
    ],
    "values": [
        {
            "station_id": "01048",
            "dataset": "climate_summary",
            "parameter": "temperature_air_mean_2m",
            "date": "2020-01-01T00:00:00+00:00",
            "value": 275.54999999999995,
            "quality": 10.0
        },
        {
            "station_id": "01048",
            "dataset": "climate_summary",
            "parameter": "temperature_air_mean_2m",
            "date": "2020-01-02T00:00:00+00:00",
            "value": 273.34999999999997,
            "quality": 10.0
        }
    ]
}

To Ogc Feature Collection

In [112]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [113]: request = DwdObservationRequest(
   .....:     parameter="temperature_air_mean_2m",
   .....:     resolution="daily",
   .....:     start_date="2020-01-01",
   .....:     end_date="2020-01-02"
   .....: )
   .....: 

In [114]: stations = request.filter_by_station_id(station_id="01048")

In [115]: values = stations.values.all()

In [116]: print(values.to_ogc_feature_collection(with_metadata=True))
{'metadata': {'provider': {'name_local': 'Deutscher Wetterdienst', 'name_english': 'German Weather Service', 'country': 'Germany', 'copyright': '© Deutscher Wetterdienst (DWD), Climate Data Center (CDC)', 'url': 'https://opendata.dwd.de/climate_environment/CDC/'}, 'producer': {'name': 'wetterdienst', 'version': '0.97.0', 'repository': 'https://github.com/earthobservations/wetterdienst', 'documentation': 'https://wetterdienst.readthedocs.io', 'doi': '10.5281/zenodo.3960624'}}, 'data': {'type': 'FeatureCollection', 'features': [{'type': 'Feature', 'properties': {'id': '01048', 'name': 'Dresden-Klotzsche', 'state': 'Sachsen', 'start_date': '1934-01-01T00:00:00+00:00', 'end_date': '2024-10-05T00:00:00+00:00'}, 'geometry': {'type': 'Point', 'coordinates': [13.7543, 51.1278, 228.0]}, 'values': [{'dataset': 'climate_summary', 'parameter': 'temperature_air_mean_2m', 'date': '2020-01-01T00:00:00+00:00', 'value': 275.54999999999995, 'quality': 10.0}, {'dataset': 'climate_summary', 'parameter': 'temperature_air_mean_2m', 'date': '2020-01-02T00:00:00+00:00', 'value': 273.34999999999997, 'quality': 10.0}]}]}}

To GeoJson

In [117]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [118]: request = DwdObservationRequest(
   .....:     parameter="temperature_air_mean_2m",
   .....:     resolution="daily",
   .....:     start_date="2020-01-01",
   .....:     end_date="2020-01-02"
   .....: )
   .....: 

In [119]: stations = request.filter_by_station_id(station_id="01048")

In [120]: values = stations.values.all()

In [121]: print(values.to_geojson(with_metadata=True))
{
    "metadata": {
        "provider": {
            "name_local": "Deutscher Wetterdienst",
            "name_english": "German Weather Service",
            "country": "Germany",
            "copyright": "© Deutscher Wetterdienst (DWD), Climate Data Center (CDC)",
            "url": "https://opendata.dwd.de/climate_environment/CDC/"
        },
        "producer": {
            "name": "wetterdienst",
            "version": "0.97.0",
            "repository": "https://github.com/earthobservations/wetterdienst",
            "documentation": "https://wetterdienst.readthedocs.io",
            "doi": "10.5281/zenodo.3960624"
        }
    },
    "data": {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "properties": {
                    "id": "01048",
                    "name": "Dresden-Klotzsche",
                    "state": "Sachsen",
                    "start_date": "1934-01-01T00:00:00+00:00",
                    "end_date": "2024-10-05T00:00:00+00:00"
                },
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        13.7543,
                        51.1278,
                        228.0
                    ]
                },
                "values": [
                    {
                        "dataset": "climate_summary",
                        "parameter": "temperature_air_mean_2m",
                        "date": "2020-01-01T00:00:00+00:00",
                        "value": 275.54999999999995,
                        "quality": 10.0
                    },
                    {
                        "dataset": "climate_summary",
                        "parameter": "temperature_air_mean_2m",
                        "date": "2020-01-02T00:00:00+00:00",
                        "value": 273.34999999999997,
                        "quality": 10.0
                    }
                ]
            }
        ]
    }
}

To CSV

In [122]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [123]: request = DwdObservationRequest(
   .....:     parameter="temperature_air_mean_2m",
   .....:     resolution="daily",
   .....:     start_date="2020-01-01",
   .....:     end_date="2020-01-02"
   .....: )
   .....: 

In [124]: stations = request.filter_by_station_id(station_id="01048")

In [125]: values = stations.values.all()

In [126]: print(values.to_csv())
station_id,dataset,parameter,date,value,quality
01048,climate_summary,temperature_air_mean_2m,2020-01-01T00:00:00+00:00,275.54999999999995,10.0
01048,climate_summary,temperature_air_mean_2m,2020-01-02T00:00:00+00:00,273.34999999999997,10.0

SQL

Querying data using SQL is provided by an in-memory DuckDB database. In order to explore what is possible, please have a look at the DuckDB SQL introduction.

The result data is provided through a virtual table called data.

from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset, DwdObservationPeriod, DwdObservationResolution
from wetterdienst import Settings

settings = Settings(ts_shape="long", ts_humanize=True, ts_si_units=True)  # defaults
request = DwdObservationRequest(
    parameter=[DwdObservationDataset.TEMPERATURE_AIR],
    resolution=DwdObservationResolution.HOURLY,
    start_date="2019-01-01",
    end_date="2020-01-01",
    settings=settings
)
stations = request.filter_by_station_id(station_id=[1048])
values = stations.values.all()
df = values.filter_by_sql("SELECT * FROM data WHERE parameter='temperature_air_2m' AND value < -7.0;")
print(df.head())

Export

Data can be exported to SQLite, DuckDB, InfluxDB, CrateDB and more targets. A target is identified by a connection string.

Examples:

  • sqlite:///dwd.sqlite?table=weather

  • duckdb:///dwd.duckdb?table=weather

  • influxdb://localhost/?database=dwd&table=weather

  • crate://localhost/?database=dwd&table=weather

from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationDataset,
    DwdObservationPeriod, DwdObservationResolution
from wetterdienst import Settings

settings = Settings(ts_shape="long", ts_humanize=True, ts_si_units=True)  # defaults
request = DwdObservationRequest(
    parameter=[DwdObservationDataset.TEMPERATURE_AIR],
    resolution=DwdObservationResolution.HOURLY,
    start_date="2019-01-01",
    end_date="2020-01-01",
    settings=settings
)
stations = request.filter_by_station_id(station_id=[1048])
values = stations.values.all()
values.to_target("influxdb://localhost/?database=dwd&table=weather")

Caching

The backbone of wetterdienst uses fsspec caching. It requires to create a directory under /home for the most cases. If you are not allowed to write into /home you will run into OSError. For this purpose you can set an environment variable WD_CACHE_DIR to define the place where the caching directory should be created.

To find out where your cache is located you can use the following code:

In [127]: from wetterdienst import Settings

In [128]: settings = Settings()

In [129]: print(settings.cache_dir)
/home/docs/.cache/wetterdienst

Or similarly with the cli:

wetterdienst cache

FSSPEC

FSSPEC is used for flexible file caching. It relies on the two libraries requests and aiohttp. Aiohttp is used for asynchronous requests and may swallow some errors related to proxies, ssl or similar. Use the defined variable FSSPEC_CLIENT_KWARGS to pass your very own client kwargs to fsspec e.g.

In [130]: from wetterdienst import Settings

In [131]: from wetterdienst.provider.dwd.observation import DwdObservationRequest

In [132]: settings = Settings(fsspec_client_kwargs={"trust_env": True})  # use proxy from environment variables

In [133]: stations = DwdObservationRequest(
   .....:     parameter=[DwdObservationDataset.TEMPERATURE_AIR],
   .....:     resolution=DwdObservationResolution.HOURLY,
   .....:     settings=settings
   .....: ).filter_by_station_id(station_id=[1048])
   .....: