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:
parameterresolutionperiodstart_dateend_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:
Requesting an entire dataset e.g. climate_summary
from wetterdienst.provider.dwd.observation import DwdObservationRequest
request = DwdObservationRequest(
parameter="kl"
)
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"
)
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_200", "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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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-04-06 ┆ 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_200, 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_200 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.
Values represented as a table:
station_id |
parameter |
date |
value |
|---|---|---|---|
02480 |
temperature_air_mean_200 |
2022-01-02 00:00:00+00:00 |
278.15 |
04411 |
temperature_air_mean_200 |
2022-01-02 00:00:00+00:00 |
277.15 |
07341 |
temperature_air_mean_200 |
2022-01-02 00:00:00+00:00 |
278.35 |
00917 |
temperature_air_mean_200 |
2022-01-02 00:00:00+00:00 |
276.25 |
The interpolated value looks like this:
parameter |
date |
value |
|---|---|---|
temperature_air_mean_200 |
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_200,
....: 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_200 ┆ 00:00:00 UTC ┆ ┆ ┆ "04411", … │
│ ┆ ┆ ┆ ┆ ┆ "00917"] │
│ f674568e ┆ temperature_air_me ┆ 2022-01-01 ┆ 285.04 ┆ 13.37 ┆ ["02480", │
│ ┆ an_200 ┆ 01:00:00 UTC ┆ ┆ ┆ "04411", … │
│ ┆ ┆ ┆ ┆ ┆ "00917"] │
│ f674568e ┆ temperature_air_me ┆ 2022-01-01 ┆ 284.75 ┆ 13.37 ┆ ["02480", │
│ ┆ an_200 ┆ 02:00:00 UTC ┆ ┆ ┆ "04411", … │
│ ┆ ┆ ┆ ┆ ┆ "00917"] │
│ f674568e ┆ temperature_air_me ┆ 2022-01-01 ┆ 284.69 ┆ 13.37 ┆ ["02480", │
│ ┆ an_200 ┆ 03:00:00 UTC ┆ ┆ ┆ "04411", … │
│ ┆ ┆ ┆ ┆ ┆ "00917"] │
│ f674568e ┆ temperature_air_me ┆ 2022-01-01 ┆ 284.51 ┆ 13.37 ┆ ["02480", │
│ ┆ an_200 ┆ 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_200,
....: 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_200 ┆ 00:00:00 UTC ┆ ┆ ┆ │
│ 7f2e709d ┆ temperature_air_me ┆ 2022-01-01 ┆ 284.95 ┆ 0.0 ┆ ["02480"] │
│ ┆ an_200 ┆ 01:00:00 UTC ┆ ┆ ┆ │
│ 7f2e709d ┆ temperature_air_me ┆ 2022-01-01 ┆ 285.15 ┆ 0.0 ┆ ["02480"] │
│ ┆ an_200 ┆ 02:00:00 UTC ┆ ┆ ┆ │
│ 7f2e709d ┆ temperature_air_me ┆ 2022-01-01 ┆ 284.75 ┆ 0.0 ┆ ["02480"] │
│ ┆ an_200 ┆ 03:00:00 UTC ┆ ┆ ┆ │
│ 7f2e709d ┆ temperature_air_me ┆ 2022-01-01 ┆ 284.75 ┆ 0.0 ┆ ["02480"] │
│ ┆ an_200 ┆ 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 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_200, 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_200,
....: 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 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ fc5aa952 ┆ temperature_air_mean_ ┆ 2022-01-01 01:00:00 ┆ 284.95 ┆ 9.76 ┆ 02480 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ fc5aa952 ┆ temperature_air_mean_ ┆ 2022-01-01 02:00:00 ┆ 285.15 ┆ 9.76 ┆ 02480 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ fc5aa952 ┆ temperature_air_mean_ ┆ 2022-01-01 03:00:00 ┆ 284.75 ┆ 9.76 ┆ 02480 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ fc5aa952 ┆ temperature_air_mean_ ┆ 2022-01-01 04:00:00 ┆ 284.75 ┆ 9.76 ┆ 02480 │
│ ┆ 200 ┆ 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_200,
....: 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 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ 73becd44 ┆ temperature_air_mean_ ┆ 2022-01-01 01:00:00 ┆ 284.95 ┆ 0.0 ┆ 02480 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ 73becd44 ┆ temperature_air_mean_ ┆ 2022-01-01 02:00:00 ┆ 285.15 ┆ 0.0 ┆ 02480 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ 73becd44 ┆ temperature_air_mean_ ┆ 2022-01-01 03:00:00 ┆ 284.75 ┆ 0.0 ┆ 02480 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
│ 73becd44 ┆ temperature_air_mean_ ┆ 2022-01-01 04:00:00 ┆ 284.75 ┆ 0.0 ┆ 02480 │
│ ┆ 200 ┆ UTC ┆ ┆ ┆ │
└────────────┴───────────────────────┴──────────────────────┴────────┴──────────┴──────────────────┘
Format#
To Dict#
In [102]: from wetterdienst.provider.dwd.observation import DwdObservationRequest
In [103]: request = DwdObservationRequest(
.....: parameter="temperature_air_mean_200",
.....: 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', 'url': 'https://github.com/earthobservations/wetterdienst', 'doi': '10.5281/zenodo.3960624'}}, 'stations': [{'station_id': '01048', 'start_date': '1934-01-01T00:00:00+00:00', 'end_date': '2024-04-06T00: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_200', 'date': '2020-01-01T00:00:00+00:00', 'value': 275.54999999999995, 'quality': 10.0}, {'station_id': '01048', 'dataset': 'climate_summary', 'parameter': 'temperature_air_mean_200', '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_200",
.....: 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",
"url": "https://github.com/earthobservations/wetterdienst",
"doi": "10.5281/zenodo.3960624"
}
},
"stations": [
{
"station_id": "01048",
"start_date": "1934-01-01T00:00:00+00:00",
"end_date": "2024-04-06T00: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_200",
"date": "2020-01-01T00:00:00+00:00",
"value": 275.54999999999995,
"quality": 10.0
},
{
"station_id": "01048",
"dataset": "climate_summary",
"parameter": "temperature_air_mean_200",
"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_200",
.....: 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', 'url': 'https://github.com/earthobservations/wetterdienst', '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-04-06T00:00:00+00:00'}, 'geometry': {'type': 'Point', 'coordinates': [13.7543, 51.1278, 228.0]}, 'values': [{'dataset': 'climate_summary', 'parameter': 'temperature_air_mean_200', 'date': '2020-01-01T00:00:00+00:00', 'value': 275.54999999999995, 'quality': 10.0}, {'dataset': 'climate_summary', 'parameter': 'temperature_air_mean_200', '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_200",
.....: 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",
"url": "https://github.com/earthobservations/wetterdienst",
"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-04-06T00:00:00+00:00"
},
"geometry": {
"type": "Point",
"coordinates": [
13.7543,
51.1278,
228.0
]
},
"values": [
{
"dataset": "climate_summary",
"parameter": "temperature_air_mean_200",
"date": "2020-01-01T00:00:00+00:00",
"value": 275.54999999999995,
"quality": 10.0
},
{
"dataset": "climate_summary",
"parameter": "temperature_air_mean_200",
"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_200",
.....: 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_200,2020-01-01T00:00:00+00:00,275.54999999999995,10.0
01048,climate_summary,temperature_air_mean_200,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_200' 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])
.....: