Python API#
Introduction#
The API offers access to different data products. They are outlined in more detail within the data 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:
1from wetterdienst import Wetterdienst
2
3coverage = Wetterdienst.discover()
4coverage
{'dwd': ['observation', 'mosmix', 'dmo', 'road', 'radar', 'derived'],
'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 factory:
1from wetterdienst import Wetterdienst
2
3Wetterdienst(provider="dwd", network="observation")
wetterdienst.provider.dwd.observation.api.DwdObservationRequest
Request arguments#
A request is typically defined by three arguments:
parametersstart_dateend_date
Parameters can be requested in different ways e.g.
using a tuple of resolution and dataset
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3DwdObservationRequest(
4 parameters=("daily", "climate_summary") # will resolve to all parameters of kl
5)
DwdObservationRequest(parameters=[ParameterModel(name='wind_gust_max', name_original='fx', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='wind_speed', name_original='fm', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='precipitation_height', name_original='rsk', unit_type='precipitation', unit='millimeter', description=None), ParameterModel(name='precipitation_form', name_original='rskf', unit_type='dimensionless', unit='dimensionless', description=None), ParameterModel(name='sunshine_duration', name_original='sdk', unit_type='time', unit='hour', description=None), ParameterModel(name='snow_depth', name_original='shk_tag', unit_type='length_short', unit='centimeter', description=None), ParameterModel(name='cloud_cover_total', name_original='nm', unit_type='fraction', unit='one_eighth', description=None), ParameterModel(name='pressure_vapor', name_original='vpm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='pressure_air_site', name_original='pm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='temperature_air_mean_2m', name_original='tmk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='humidity', name_original='upm', unit_type='fraction', unit='percent', description=None), ParameterModel(name='temperature_air_max_2m', name_original='txk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_2m', name_original='tnk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_0_05m', name_original='tgk', unit_type='temperature', unit='degree_celsius', description=None)], start_date=None, end_date=None, settings={"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.123.0 (Linux)"}, "timeout": 30}, "use_certifi": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_complete": false, "ts_drop_nulls": true, "ts_geo_station_distance": {"precipitation_height": 20.0, "precipitation_height_day": 20.0, "precipitation_height_night": 20.0, "precipitation_height_liquid": 20.0, "precipitation_height_droplet": 20.0, "precipitation_height_rocker": 20.0, "precipitation_height_last_1h": 20.0, "precipitation_height_last_3h": 20.0, "precipitation_height_last_6h": 20.0, "precipitation_height_last_9h": 20.0, "precipitation_height_last_12h": 20.0, "precipitation_height_last_15h": 20.0, "precipitation_height_last_18h": 20.0, "precipitation_height_last_21h": 20.0, "precipitation_height_last_24h": 20.0, "precipitation_height_multiday": 20.0, "precipitation_height_significant_weather_last_1h": 20.0, "precipitation_height_significant_weather_last_3h": 20.0, "precipitation_height_significant_weather_last_6h": 20.0, "precipitation_height_significant_weather_last_12h": 20.0, "precipitation_height_significant_weather_last_24h": 20.0, "precipitation_height_liquid_significant_weather_last_1h": 20.0, "precipitation_height_max": 20.0, "precipitation_height_liquid_max": 20.0, "precipitation_duration": 20.0, "snow_depth_new": 20.0, "snow_depth_new_multiday": 20.0, "snow_depth_new_max": 20.0, "water_equivalent_snow_depth_new": 20.0, "water_equivalent_snow_depth_new_last_1h": 20.0, "water_equivalent_snow_depth_new_last_3h": 20.0}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}, periods={<Period.NOW: 'now'>, <Period.HISTORICAL: 'historical'>, <Period.RECENT: 'recent'>})
using a tuple of resolution, dataset, parameter
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3DwdObservationRequest(
4 parameters=("daily", "climate_summary", "precipitation_height")
5)
DwdObservationRequest(parameters=[ParameterModel(name='precipitation_height', name_original='rsk', unit_type='precipitation', unit='millimeter', description=None)], start_date=None, end_date=None, settings={"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.123.0 (Linux)"}, "timeout": 30}, "use_certifi": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_complete": false, "ts_drop_nulls": true, "ts_geo_station_distance": {"precipitation_height": 20.0, "precipitation_height_day": 20.0, "precipitation_height_night": 20.0, "precipitation_height_liquid": 20.0, "precipitation_height_droplet": 20.0, "precipitation_height_rocker": 20.0, "precipitation_height_last_1h": 20.0, "precipitation_height_last_3h": 20.0, "precipitation_height_last_6h": 20.0, "precipitation_height_last_9h": 20.0, "precipitation_height_last_12h": 20.0, "precipitation_height_last_15h": 20.0, "precipitation_height_last_18h": 20.0, "precipitation_height_last_21h": 20.0, "precipitation_height_last_24h": 20.0, "precipitation_height_multiday": 20.0, "precipitation_height_significant_weather_last_1h": 20.0, "precipitation_height_significant_weather_last_3h": 20.0, "precipitation_height_significant_weather_last_6h": 20.0, "precipitation_height_significant_weather_last_12h": 20.0, "precipitation_height_significant_weather_last_24h": 20.0, "precipitation_height_liquid_significant_weather_last_1h": 20.0, "precipitation_height_max": 20.0, "precipitation_height_liquid_max": 20.0, "precipitation_duration": 20.0, "snow_depth_new": 20.0, "snow_depth_new_multiday": 20.0, "snow_depth_new_max": 20.0, "water_equivalent_snow_depth_new": 20.0, "water_equivalent_snow_depth_new_last_1h": 20.0, "water_equivalent_snow_depth_new_last_3h": 20.0}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}, periods={<Period.NOW: 'now'>, <Period.HISTORICAL: 'historical'>, <Period.RECENT: 'recent'>})
the same with the original names
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3DwdObservationRequest(
4 parameters=("daily", "kl", "rsk")
5)
DwdObservationRequest(parameters=[ParameterModel(name='precipitation_height', name_original='rsk', unit_type='precipitation', unit='millimeter', description=None)], start_date=None, end_date=None, settings={"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.123.0 (Linux)"}, "timeout": 30}, "use_certifi": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_complete": false, "ts_drop_nulls": true, "ts_geo_station_distance": {"precipitation_height": 20.0, "precipitation_height_day": 20.0, "precipitation_height_night": 20.0, "precipitation_height_liquid": 20.0, "precipitation_height_droplet": 20.0, "precipitation_height_rocker": 20.0, "precipitation_height_last_1h": 20.0, "precipitation_height_last_3h": 20.0, "precipitation_height_last_6h": 20.0, "precipitation_height_last_9h": 20.0, "precipitation_height_last_12h": 20.0, "precipitation_height_last_15h": 20.0, "precipitation_height_last_18h": 20.0, "precipitation_height_last_21h": 20.0, "precipitation_height_last_24h": 20.0, "precipitation_height_multiday": 20.0, "precipitation_height_significant_weather_last_1h": 20.0, "precipitation_height_significant_weather_last_3h": 20.0, "precipitation_height_significant_weather_last_6h": 20.0, "precipitation_height_significant_weather_last_12h": 20.0, "precipitation_height_significant_weather_last_24h": 20.0, "precipitation_height_liquid_significant_weather_last_1h": 20.0, "precipitation_height_max": 20.0, "precipitation_height_liquid_max": 20.0, "precipitation_duration": 20.0, "snow_depth_new": 20.0, "snow_depth_new_multiday": 20.0, "snow_depth_new_max": 20.0, "water_equivalent_snow_depth_new": 20.0, "water_equivalent_snow_depth_new_last_1h": 20.0, "water_equivalent_snow_depth_new_last_3h": 20.0}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}, periods={<Period.NOW: 'now'>, <Period.HISTORICAL: 'historical'>, <Period.RECENT: 'recent'>})
using the metadata model
1from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationMetadata
2
3DwdObservationRequest(
4 parameters=DwdObservationMetadata.daily.kl # will resolve to all parameters of kl
5)
DwdObservationRequest(parameters=[ParameterModel(name='wind_gust_max', name_original='fx', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='wind_speed', name_original='fm', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='precipitation_height', name_original='rsk', unit_type='precipitation', unit='millimeter', description=None), ParameterModel(name='precipitation_form', name_original='rskf', unit_type='dimensionless', unit='dimensionless', description=None), ParameterModel(name='sunshine_duration', name_original='sdk', unit_type='time', unit='hour', description=None), ParameterModel(name='snow_depth', name_original='shk_tag', unit_type='length_short', unit='centimeter', description=None), ParameterModel(name='cloud_cover_total', name_original='nm', unit_type='fraction', unit='one_eighth', description=None), ParameterModel(name='pressure_vapor', name_original='vpm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='pressure_air_site', name_original='pm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='temperature_air_mean_2m', name_original='tmk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='humidity', name_original='upm', unit_type='fraction', unit='percent', description=None), ParameterModel(name='temperature_air_max_2m', name_original='txk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_2m', name_original='tnk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_0_05m', name_original='tgk', unit_type='temperature', unit='degree_celsius', description=None)], start_date=None, end_date=None, settings={"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.123.0 (Linux)"}, "timeout": 30}, "use_certifi": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_complete": false, "ts_drop_nulls": true, "ts_geo_station_distance": {"precipitation_height": 20.0, "precipitation_height_day": 20.0, "precipitation_height_night": 20.0, "precipitation_height_liquid": 20.0, "precipitation_height_droplet": 20.0, "precipitation_height_rocker": 20.0, "precipitation_height_last_1h": 20.0, "precipitation_height_last_3h": 20.0, "precipitation_height_last_6h": 20.0, "precipitation_height_last_9h": 20.0, "precipitation_height_last_12h": 20.0, "precipitation_height_last_15h": 20.0, "precipitation_height_last_18h": 20.0, "precipitation_height_last_21h": 20.0, "precipitation_height_last_24h": 20.0, "precipitation_height_multiday": 20.0, "precipitation_height_significant_weather_last_1h": 20.0, "precipitation_height_significant_weather_last_3h": 20.0, "precipitation_height_significant_weather_last_6h": 20.0, "precipitation_height_significant_weather_last_12h": 20.0, "precipitation_height_significant_weather_last_24h": 20.0, "precipitation_height_liquid_significant_weather_last_1h": 20.0, "precipitation_height_max": 20.0, "precipitation_height_liquid_max": 20.0, "precipitation_duration": 20.0, "snow_depth_new": 20.0, "snow_depth_new_multiday": 20.0, "snow_depth_new_max": 20.0, "water_equivalent_snow_depth_new": 20.0, "water_equivalent_snow_depth_new_last_1h": 20.0, "water_equivalent_snow_depth_new_last_3h": 20.0}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}, periods={<Period.NOW: 'now'>, <Period.HISTORICAL: 'historical'>, <Period.RECENT: 'recent'>})
using a list of tuples
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3DwdObservationRequest(
4 parameters=[("daily", "climate_summary"), ("daily", "precipitation_more")]
5)
DwdObservationRequest(parameters=[ParameterModel(name='wind_gust_max', name_original='fx', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='wind_speed', name_original='fm', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='precipitation_height', name_original='rsk', unit_type='precipitation', unit='millimeter', description=None), ParameterModel(name='precipitation_form', name_original='rskf', unit_type='dimensionless', unit='dimensionless', description=None), ParameterModel(name='sunshine_duration', name_original='sdk', unit_type='time', unit='hour', description=None), ParameterModel(name='snow_depth', name_original='shk_tag', unit_type='length_short', unit='centimeter', description=None), ParameterModel(name='cloud_cover_total', name_original='nm', unit_type='fraction', unit='one_eighth', description=None), ParameterModel(name='pressure_vapor', name_original='vpm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='pressure_air_site', name_original='pm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='temperature_air_mean_2m', name_original='tmk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='humidity', name_original='upm', unit_type='fraction', unit='percent', description=None), ParameterModel(name='temperature_air_max_2m', name_original='txk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_2m', name_original='tnk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_0_05m', name_original='tgk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='precipitation_height', name_original='rs', unit_type='precipitation', unit='millimeter', description=None), ParameterModel(name='precipitation_form', name_original='rsf', unit_type='dimensionless', unit='dimensionless', description=None), ParameterModel(name='snow_depth', name_original='sh_tag', unit_type='length_short', unit='centimeter', description=None), ParameterModel(name='snow_depth_new', name_original='nsh_tag', unit_type='length_short', unit='centimeter', description=None)], start_date=None, end_date=None, settings={"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.123.0 (Linux)"}, "timeout": 30}, "use_certifi": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_complete": false, "ts_drop_nulls": true, "ts_geo_station_distance": {"precipitation_height": 20.0, "precipitation_height_day": 20.0, "precipitation_height_night": 20.0, "precipitation_height_liquid": 20.0, "precipitation_height_droplet": 20.0, "precipitation_height_rocker": 20.0, "precipitation_height_last_1h": 20.0, "precipitation_height_last_3h": 20.0, "precipitation_height_last_6h": 20.0, "precipitation_height_last_9h": 20.0, "precipitation_height_last_12h": 20.0, "precipitation_height_last_15h": 20.0, "precipitation_height_last_18h": 20.0, "precipitation_height_last_21h": 20.0, "precipitation_height_last_24h": 20.0, "precipitation_height_multiday": 20.0, "precipitation_height_significant_weather_last_1h": 20.0, "precipitation_height_significant_weather_last_3h": 20.0, "precipitation_height_significant_weather_last_6h": 20.0, "precipitation_height_significant_weather_last_12h": 20.0, "precipitation_height_significant_weather_last_24h": 20.0, "precipitation_height_liquid_significant_weather_last_1h": 20.0, "precipitation_height_max": 20.0, "precipitation_height_liquid_max": 20.0, "precipitation_duration": 20.0, "snow_depth_new": 20.0, "snow_depth_new_multiday": 20.0, "snow_depth_new_max": 20.0, "water_equivalent_snow_depth_new": 20.0, "water_equivalent_snow_depth_new_last_1h": 20.0, "water_equivalent_snow_depth_new_last_3h": 20.0}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}, periods={<Period.NOW: 'now'>, <Period.HISTORICAL: 'historical'>, <Period.RECENT: 'recent'>})
using a list of metadata
1from wetterdienst.provider.dwd.observation import DwdObservationRequest, DwdObservationMetadata
2
3DwdObservationRequest(
4 parameters=[DwdObservationMetadata.daily.kl, DwdObservationMetadata.daily.more_precip]
5)
DwdObservationRequest(parameters=[ParameterModel(name='wind_gust_max', name_original='fx', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='wind_speed', name_original='fm', unit_type='speed', unit='meter_per_second', description=None), ParameterModel(name='precipitation_height', name_original='rsk', unit_type='precipitation', unit='millimeter', description=None), ParameterModel(name='precipitation_form', name_original='rskf', unit_type='dimensionless', unit='dimensionless', description=None), ParameterModel(name='sunshine_duration', name_original='sdk', unit_type='time', unit='hour', description=None), ParameterModel(name='snow_depth', name_original='shk_tag', unit_type='length_short', unit='centimeter', description=None), ParameterModel(name='cloud_cover_total', name_original='nm', unit_type='fraction', unit='one_eighth', description=None), ParameterModel(name='pressure_vapor', name_original='vpm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='pressure_air_site', name_original='pm', unit_type='pressure', unit='hectopascal', description=None), ParameterModel(name='temperature_air_mean_2m', name_original='tmk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='humidity', name_original='upm', unit_type='fraction', unit='percent', description=None), ParameterModel(name='temperature_air_max_2m', name_original='txk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_2m', name_original='tnk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='temperature_air_min_0_05m', name_original='tgk', unit_type='temperature', unit='degree_celsius', description=None), ParameterModel(name='precipitation_height', name_original='rs', unit_type='precipitation', unit='millimeter', description=None), ParameterModel(name='precipitation_form', name_original='rsf', unit_type='dimensionless', unit='dimensionless', description=None), ParameterModel(name='snow_depth', name_original='sh_tag', unit_type='length_short', unit='centimeter', description=None), ParameterModel(name='snow_depth_new', name_original='nsh_tag', unit_type='length_short', unit='centimeter', description=None)], start_date=None, end_date=None, settings={"cache_disable": false, "cache_dir": "/home/docs/.cache/wetterdienst", "fsspec_client_kwargs": {"headers": {"User-Agent": "wetterdienst/0.123.0 (Linux)"}, "timeout": 30}, "use_certifi": false, "ts_humanize": true, "ts_shape": "long", "ts_convert_units": true, "ts_unit_targets": {}, "ts_skip_empty": false, "ts_skip_threshold": 0.95, "ts_skip_criteria": "min", "ts_complete": false, "ts_drop_nulls": true, "ts_geo_station_distance": {"precipitation_height": 20.0, "precipitation_height_day": 20.0, "precipitation_height_night": 20.0, "precipitation_height_liquid": 20.0, "precipitation_height_droplet": 20.0, "precipitation_height_rocker": 20.0, "precipitation_height_last_1h": 20.0, "precipitation_height_last_3h": 20.0, "precipitation_height_last_6h": 20.0, "precipitation_height_last_9h": 20.0, "precipitation_height_last_12h": 20.0, "precipitation_height_last_15h": 20.0, "precipitation_height_last_18h": 20.0, "precipitation_height_last_21h": 20.0, "precipitation_height_last_24h": 20.0, "precipitation_height_multiday": 20.0, "precipitation_height_significant_weather_last_1h": 20.0, "precipitation_height_significant_weather_last_3h": 20.0, "precipitation_height_significant_weather_last_6h": 20.0, "precipitation_height_significant_weather_last_12h": 20.0, "precipitation_height_significant_weather_last_24h": 20.0, "precipitation_height_liquid_significant_weather_last_1h": 20.0, "precipitation_height_max": 20.0, "precipitation_height_liquid_max": 20.0, "precipitation_duration": 20.0, "snow_depth_new": 20.0, "snow_depth_new_multiday": 20.0, "snow_depth_new_max": 20.0, "water_equivalent_snow_depth_new": 20.0, "water_equivalent_snow_depth_new_last_1h": 20.0, "water_equivalent_snow_depth_new_last_3h": 20.0}, "ts_geo_use_nearby_station_distance": 1.0, "ts_geo_min_gain_of_value_pairs": 0.1, "ts_geo_num_additional_stations": 3}, periods={<Period.NOW: 'now'>, <Period.HISTORICAL: 'historical'>, <Period.RECENT: 'recent'>})
For some weather service one can select which period of the data is request with periods.
Valid periods are historical, recent and now. periods can be given as a list or a single value.
The value can be a string, the enumeration value or the enumeration name e.g.
by using the exact enumeration e.g.
1from wetterdienst.metadata.period import Period
2
3Period.HISTORICAL
<Period.HISTORICAL: 'historical'>
by using the enumeration name or value as string e.g.
"historical" or "HISTORICAL"
If a weather service has periods, the period argument typically can be used as replacement for the start_date and end_date arguments. In case both arguments are given they are used as a filter for the data.
Regarding the definition of requested parameters:
Data#
In case of the DWD, requests can be defined by either of period or
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 dataset/parameter and period.
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("daily", "precipitation_more"),
6 start_date=dt.datetime(2020, 1, 1),
7 end_date=dt.datetime(2020, 1, 20)
8)
9stations = request.all()
10df = stations.df
11df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state |
|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str |
| "daily" | "precipitation_more" | "00001" | 1912-01-01 00:00:00 UTC | 1986-06-30 00:00:00 UTC | 47.8413 | 8.8493 | 478.0 | "Aach" | "Baden-Württemberg" |
| "daily" | "precipitation_more" | "00002" | 1951-01-01 00:00:00 UTC | 2006-12-31 00:00:00 UTC | 50.8066 | 6.0996 | 138.0 | "Aachen (Kläranlage)" | "Nordrhein-Westfalen" |
| "daily" | "precipitation_more" | "00003" | 1891-01-01 00:00:00 UTC | 2011-03-31 00:00:00 UTC | 50.7827 | 6.0941 | 202.0 | "Aachen" | "Nordrhein-Westfalen" |
| "daily" | "precipitation_more" | "00004" | 1951-01-01 00:00:00 UTC | 1979-10-31 00:00:00 UTC | 50.7683 | 6.1207 | 243.0 | "Aachen-Brand" | "Nordrhein-Westfalen" |
| "daily" | "precipitation_more" | "00006" | 1982-11-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 48.8361 | 10.0598 | 455.0 | "Aalen-Unterrombach" | "Baden-Württemberg" |
| … | … | … | … | … | … | … | … | … | … |
| "daily" | "precipitation_more" | "20107" | 2025-03-27 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 49.9687 | 6.8272 | 311.0 | "Wittlich-Bergweiler" | "Rheinland-Pfalz" |
| "daily" | "precipitation_more" | "20108" | 2025-05-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 51.1543 | 6.5049 | 56.0 | "Mönchengladbach-Schelsen" | "Nordrhein-Westfalen" |
| "daily" | "precipitation_more" | "20110" | 1969-01-01 00:00:00 UTC | 2005-07-31 00:00:00 UTC | 52.3183 | 11.5677 | 64.0 | "Colbitz" | "Sachsen-Anhalt" |
| "daily" | "precipitation_more" | "20189" | 2025-10-01 00:00:00 UTC | 2026-04-30 00:00:00 UTC | 47.6759 | 12.47 | 687.0 | "Reit im Winkl (Kaiserweg)" | "Bayern" |
| "daily" | "precipitation_more" | "20191" | 2025-09-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 50.9238 | 14.357 | 375.0 | "Sebnitz-Hinterhermsdorf" | "Sachsen" |
The function returns a Polars DataFrame with information about the available stations.
filter by station id#
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("daily", "precipitation_more"),
6 start_date=dt.datetime(2020, 1, 1),
7 end_date=dt.datetime(2020, 1, 20)
8)
9stations = request.filter_by_station_id(station_id=("01048", ))
10df = stations.df
11df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state |
|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str |
| "daily" | "precipitation_more" | "01048" | 1926-04-25 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 51.1278 | 13.7543 | 228.0 | "Dresden-Klotzsche" | "Sachsen" |
filter by name#
Station name filtering uses fuzzy matching (case-insensitive) so partial names, minor typos, and word-order variations are handled automatically.
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("daily", "precipitation_more"),
6 start_date=dt.datetime(2020, 1, 1),
7 end_date=dt.datetime(2020, 1, 20)
8)
9stations = request.filter_by_name(name="Dresden-Klotzsche")
10df = stations.df
11df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state |
|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str |
| "daily" | "precipitation_more" | "01048" | 1926-04-25 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 51.1278 | 13.7543 | 228.0 | "Dresden-Klotzsche" | "Sachsen" |
The threshold parameter (0–1, default 0.8) controls how strictly the name must
match. Lower values accept more typos; higher values require a closer match. The
rank parameter limits how many stations are returned (default 1).
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("daily", "precipitation_more"),
6 start_date=dt.datetime(2020, 1, 1),
7 end_date=dt.datetime(2020, 1, 20)
8)
9# case-insensitive, typo-tolerant, returns up to 3 matches
10stations = request.filter_by_name(name="dresden", rank=3, threshold=0.8)
11df = stations.df
12df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state |
|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str |
filter by distance#
Distance in kilometers (default)
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4hamburg = (53.551086, 9.993682)
5request = DwdObservationRequest(
6 parameters=("hourly", "temperature_air"),
7 start_date=dt.datetime(2020, 1, 1),
8 end_date=dt.datetime(2020, 1, 20)
9)
10stations = request.filter_by_distance(latlon=hamburg, distance=30, unit="km")
11df = stations.df
12df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state | distance |
|---|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str | f64 |
| "hourly" | "temperature_air" | "01975" | 1949-01-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.6332 | 9.9881 | 11.0 | "Hamburg-Fuhlsbüttel" | "Hamburg" | 9.1381 |
| "hourly" | "temperature_air" | "01981" | 2005-03-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.4776 | 9.8957 | 4.0 | "Hamburg-Neuwiedenthal" | "Hamburg" | 10.4279 |
| "hourly" | "temperature_air" | "00052" | 1976-01-01 00:00:00 UTC | 1988-01-01 00:00:00 UTC | 53.6623 | 10.199 | 46.0 | "Ahrensburg-Wulfsdorf" | "Schleswig-Holstein" | 18.3417 |
| "hourly" | "temperature_air" | "00760" | 2017-12-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.3629 | 9.9435 | 83.0 | "Rosengarten-Klecken" | "Niedersachsen" | 21.1875 |
| "hourly" | "temperature_air" | "04039" | 1988-01-11 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.7331 | 9.8776 | 11.0 | "Quickborn" | "Schleswig-Holstein" | 21.6373 |
| "hourly" | "temperature_air" | "04857" | 2004-09-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.5534 | 9.6097 | 2.0 | "Mittelnkirchen-Hohenfelde" | "Niedersachsen" | 25.367 |
Distance in miles
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4hamburg = (53.551086, 9.993682)
5request = DwdObservationRequest(
6 parameters=("hourly", "temperature_air"),
7 start_date=dt.datetime(2020, 1, 1),
8 end_date=dt.datetime(2020, 1, 20)
9)
10stations = request.filter_by_distance(latlon=hamburg, distance=30, unit="mi")
11df = stations.df
12df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state | distance |
|---|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str | f64 |
| "hourly" | "temperature_air" | "01975" | 1949-01-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.6332 | 9.9881 | 11.0 | "Hamburg-Fuhlsbüttel" | "Hamburg" | 9.1381 |
| "hourly" | "temperature_air" | "01981" | 2005-03-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.4776 | 9.8957 | 4.0 | "Hamburg-Neuwiedenthal" | "Hamburg" | 10.4279 |
| "hourly" | "temperature_air" | "00052" | 1976-01-01 00:00:00 UTC | 1988-01-01 00:00:00 UTC | 53.6623 | 10.199 | 46.0 | "Ahrensburg-Wulfsdorf" | "Schleswig-Holstein" | 18.3417 |
| "hourly" | "temperature_air" | "00760" | 2017-12-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.3629 | 9.9435 | 83.0 | "Rosengarten-Klecken" | "Niedersachsen" | 21.1875 |
| "hourly" | "temperature_air" | "04039" | 1988-01-11 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.7331 | 9.8776 | 11.0 | "Quickborn" | "Schleswig-Holstein" | 21.6373 |
| "hourly" | "temperature_air" | "04857" | 2004-09-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.5534 | 9.6097 | 2.0 | "Mittelnkirchen-Hohenfelde" | "Niedersachsen" | 25.367 |
| "hourly" | "temperature_air" | "05280" | 2007-03-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.9224 | 10.2267 | 33.0 | "Wittenborn" | "Schleswig-Holstein" | 44.0408 |
| "hourly" | "temperature_air" | "01736" | 2002-01-24 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.5731 | 10.6797 | 26.0 | "Grambek" | "Schleswig-Holstein" | 45.3735 |
filter by rank#
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4hamburg = (53.551086, 9.993682)
5request = DwdObservationRequest(
6 parameters=("hourly", "temperature_air"),
7 start_date=dt.datetime(2020, 1, 1),
8 end_date=dt.datetime(2020, 1, 20)
9)
10stations = request.filter_by_rank(latlon=hamburg, rank=5)
11df = stations.df
12df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state | distance |
|---|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str | f64 |
| "hourly" | "temperature_air" | "01975" | 1949-01-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.6332 | 9.9881 | 11.0 | "Hamburg-Fuhlsbüttel" | "Hamburg" | 9.1381 |
| "hourly" | "temperature_air" | "01981" | 2005-03-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.4776 | 9.8957 | 4.0 | "Hamburg-Neuwiedenthal" | "Hamburg" | 10.4279 |
| "hourly" | "temperature_air" | "00052" | 1976-01-01 00:00:00 UTC | 1988-01-01 00:00:00 UTC | 53.6623 | 10.199 | 46.0 | "Ahrensburg-Wulfsdorf" | "Schleswig-Holstein" | 18.3417 |
| "hourly" | "temperature_air" | "00760" | 2017-12-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.3629 | 9.9435 | 83.0 | "Rosengarten-Klecken" | "Niedersachsen" | 21.1875 |
| "hourly" | "temperature_air" | "04039" | 1988-01-11 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 53.7331 | 9.8776 | 11.0 | "Quickborn" | "Schleswig-Holstein" | 21.6373 |
| … | … | … | … | … | … | … | … | … | … | … |
| "hourly" | "temperature_air" | "03730" | 1948-01-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 47.3984 | 10.2759 | 806.0 | "Oberstdorf" | "Bayern" | 684.4374 |
| "hourly" | "temperature_air" | "05792" | 1950-01-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 47.421 | 10.9848 | 2956.0 | "Zugspitze" | "Bayern" | 685.2131 |
| "hourly" | "temperature_air" | "07325" | 2011-09-01 00:00:00 UTC | 2015-12-31 00:00:00 UTC | 47.4165 | 10.9795 | 2650.0 | "Schneefernerhaus" | "Bayern" | 685.6732 |
| "hourly" | "temperature_air" | "00361" | 1948-01-01 00:00:00 UTC | 1976-01-01 00:00:00 UTC | 47.6344 | 13.0109 | 550.0 | "Berchtesgaden (KKst)" | "Bayern" | 691.3582 |
| "hourly" | "temperature_air" | "19856" | 2024-08-01 00:00:00 UTC | 2026-06-19 00:00:00 UTC | 47.6134 | 12.9819 | 625.0 | "Schönau am Königssee" | "Bayern" | 692.9712 |
filter by bbox#
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4bbox = (8.9, 50.0, 8.91, 50.01)
5request = DwdObservationRequest(
6 parameters=("hourly", "temperature_air"),
7 start_date=dt.datetime(2020, 1, 1),
8 end_date=dt.datetime(2020, 1, 20)
9)
10stations = request.filter_by_bbox(*bbox)
11df = stations.df
12df
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state |
|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str |
Values#
Values are just an extension of requests. You can query data by using the
.query() method on the values object:
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2from wetterdienst import Settings
3
4# if no settings are provided, default settings are used which are
5# Settings(ts_shape="long", ts_humanize=True, ts_si_units=True)
6request = DwdObservationRequest(
7 parameters=[("daily", "kl"), ("daily", "solar")],
8 start_date="1990-01-01",
9 end_date="2020-01-01",
10)
11stations = request.filter_by_station_id(station_id=("00003", "01048"))
12
13# From here you can query data by station
14for result in stations.values.query():
15 # analyse the station here
16 break
17
18df = result.df.drop_nulls()
19df
| station_id | resolution | dataset | parameter | date | value | quality |
|---|---|---|---|---|---|---|
| str | str | str | str | datetime[μs, UTC] | f64 | f64 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-01 00:00:00 UTC | 1.0 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-02 00:00:00 UTC | 1.0 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-03 00:00:00 UTC | 0.5875 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-04 00:00:00 UTC | 0.75 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-05 00:00:00 UTC | 0.9625 | 10.0 |
| … | … | … | … | … | … | … |
| "00003" | "daily" | "climate_summary" | "wind_speed" | 2011-03-27 00:00:00 UTC | 1.7 | 10.0 |
| "00003" | "daily" | "climate_summary" | "wind_speed" | 2011-03-28 00:00:00 UTC | 1.7 | 10.0 |
| "00003" | "daily" | "climate_summary" | "wind_speed" | 2011-03-29 00:00:00 UTC | 1.6 | 10.0 |
| "00003" | "daily" | "climate_summary" | "wind_speed" | 2011-03-30 00:00:00 UTC | 3.8 | 10.0 |
| "00003" | "daily" | "climate_summary" | "wind_speed" | 2011-03-31 00:00:00 UTC | 7.0 | 10.0 |
Or you can query all data at once:
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2from wetterdienst import Settings
3
4# if no settings are provided, default settings are used which are
5# Settings(ts_shape="long", ts_humanize=True, ts_si_units=True)
6request = DwdObservationRequest(
7 parameters=[("daily", "kl"), ("daily", "solar")],
8 start_date="1990-01-01",
9 end_date="2020-01-01",
10)
11stations = request.filter_by_station_id(station_id=("00003", "01048"))
12df = stations.values.all().df.drop_nulls()
13df
| station_id | resolution | dataset | parameter | date | value | quality |
|---|---|---|---|---|---|---|
| str | str | str | str | datetime[μs, UTC] | f64 | f64 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-01 00:00:00 UTC | 1.0 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-02 00:00:00 UTC | 1.0 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-03 00:00:00 UTC | 0.5875 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-04 00:00:00 UTC | 0.75 | 10.0 |
| "00003" | "daily" | "climate_summary" | "cloud_cover_total" | 1990-01-05 00:00:00 UTC | 0.9625 | 10.0 |
| … | … | … | … | … | … | … |
| "01048" | "daily" | "solar" | "sunshine_duration" | 2019-12-28 00:00:00 UTC | 0.0 | 1.0 |
| "01048" | "daily" | "solar" | "sunshine_duration" | 2019-12-29 00:00:00 UTC | 22320.0 | 1.0 |
| "01048" | "daily" | "solar" | "sunshine_duration" | 2019-12-30 00:00:00 UTC | 5400.0 | 1.0 |
| "01048" | "daily" | "solar" | "sunshine_duration" | 2019-12-31 00:00:00 UTC | 3960.0 | 1.0 |
| "01048" | "daily" | "solar" | "sunshine_duration" | 2020-01-01 00:00:00 UTC | 14040.0 | 1.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:
1from wetterdienst import Settings
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4settings = Settings(ts_skip_empty=True, ts_skip_criteria="min", ts_skip_threshold=0.2)
5karlsruhe = (49.19780976647141, 8.135207205143768)
6request = DwdObservationRequest(
7 parameters=[("daily", "kl")],
8 start_date="2021-01-01",
9 end_date="2021-12-31",
10 settings=settings,
11)
12stations = request.filter_by_rank(latlon=karlsruhe, rank=2)
13values = stations.values.all()
14print(values.df.head())
15# df_stations has only stations that appear in the values
16values.df_stations
shape: (0, 7)
┌────────────┬────────────┬─────────┬───────────┬───────────────────┬───────┬─────────┐
│ station_id ┆ resolution ┆ dataset ┆ parameter ┆ date ┆ value ┆ quality │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ str ┆ str ┆ datetime[μs, UTC] ┆ f64 ┆ f64 │
╞════════════╪════════════╪═════════╪═══════════╪═══════════════════╪═══════╪═════════╡
└────────────┴────────────┴─────────┴───────────┴───────────────────┴───────┴─────────┘
| resolution | dataset | station_id | start_date | end_date | latitude | longitude | height | name | state | distance |
|---|---|---|---|---|---|---|---|---|---|---|
| str | str | str | datetime[μs, UTC] | datetime[μs, UTC] | f64 | f64 | f64 | str | str | f64 |
| "daily" | "climate_summary" | "01428" | 1948-01-01 00:00:00 UTC | 1957-12-31 00:00:00 UTC | 49.2275 | 8.0585 | 230.0 | "Frankweiler" | "Rheinland-Pfalz" | 6.4765 |
| "daily" | "climate_summary" | "00174" | 1984-03-01 00:00:00 UTC | 1987-12-31 00:00:00 UTC | 49.1886 | 7.9766 | 250.0 | "Annweiler-Bindersbach" | "Rheinland-Pfalz" | 11.5709 |
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 supports the following parameters:
Large spatial correlation (~40 km default search radius) — homogeneous fields that vary slowly across regions:
Temperature:
temperature_air_2m, temperature_air_mean_2m, temperature_air_mean_2m_last_24h,
temperature_air_max_2m, temperature_air_max_2m_last_24h, temperature_air_max_2m_mean, temperature_air_max_2m_multiday,
temperature_air_min_2m, temperature_air_min_2m_last_24h, temperature_air_min_2m_mean, temperature_air_min_2m_multiday,
temperature_air_mean_0_05m, temperature_air_max_0_05m, temperature_air_min_0_05m, temperature_air_min_0_05m_last_12h,
temperature_dew_point_mean_2m, temperature_wet_mean_2m, temperature_wind_chill, temperature_surface_mean,
temperature_soil_mean_0_02m, temperature_soil_mean_0_05m, temperature_soil_mean_0_1m, temperature_soil_mean_0_2m,
temperature_soil_mean_0_5m, temperature_soil_mean_1m, temperature_soil_mean_2m,
temperature_soil_min_0_1m, temperature_soil_min_0_2m, temperature_soil_min_0_5m, temperature_soil_min_1m, temperature_soil_min_2m,
temperature_soil_max_0_1m, temperature_soil_max_0_2m, temperature_soil_max_0_5m, temperature_soil_max_1m, temperature_soil_max_2m,
heating_degree_day, cooling_degree_hour
Humidity:
humidity, humidity_absolute, humidity_max, humidity_min, humidex
Wind:
wind_speed, wind_speed_arithmetic, wind_speed_min, wind_speed_rolling_mean_max, wind_force_beaufort,
wind_movement_24h, wind_movement_multiday,
wind_gust_max, wind_gust_max_last_1h, wind_gust_max_last_3h, wind_gust_max_last_6h, wind_gust_max_last_12h,
wind_gust_max_5sec, wind_gust_max_1min, wind_gust_max_2min, wind_gust_max_instant, wind_gust_max_1mile
Snow (accumulated depth):
snow_depth, snow_depth_excelled, snow_depth_manual, snow_depth_max,
water_equivalent_snow_depth, water_equivalent_snow_depth_excelled
Solar / Radiation:
sunshine_duration, sunshine_duration_last_3h, sunshine_duration_yesterday,
sunshine_duration_relative, sunshine_duration_relative_last_24h,
radiation_global, radiation_global_last_3h,
radiation_sky_short_wave_diffuse, radiation_sky_short_wave_direct,
radiation_sky_long_wave, radiation_sky_long_wave_last_3h
Pressure:
pressure_air_sea_level, pressure_air_site, pressure_air_site_reduced,
pressure_air_site_max, pressure_air_site_min, pressure_air_site_delta_last_3h, pressure_vapor
Cloud cover:
cloud_cover_total, cloud_cover_total_midnight_to_midnight, cloud_cover_total_sunrise_to_sunset, cloud_cover_effective
Evapotranspiration / Evaporation:
evapotranspiration_potential_last_24h, evapotranspiration_potential_gras_fao_last_24h,
evapotranspiration_potential_gras_haude_last_24h, evaporation_height, evaporation_height_multiday
Short spatial correlation (~20 km default search radius) — heterogeneous fields that vary more locally:
Precipitation:
precipitation_height, precipitation_height_day, precipitation_height_night,
precipitation_height_liquid, precipitation_height_droplet, precipitation_height_rocker,
precipitation_height_last_1h, precipitation_height_last_3h, precipitation_height_last_6h,
precipitation_height_last_9h, precipitation_height_last_12h, precipitation_height_last_15h,
precipitation_height_last_18h, precipitation_height_last_21h, precipitation_height_last_24h,
precipitation_height_multiday,
precipitation_height_significant_weather_last_1h, precipitation_height_significant_weather_last_3h,
precipitation_height_significant_weather_last_6h, precipitation_height_significant_weather_last_12h,
precipitation_height_significant_weather_last_24h,
precipitation_height_liquid_significant_weather_last_1h,
precipitation_height_max, precipitation_height_liquid_max, precipitation_duration
New snow per period:
snow_depth_new, snow_depth_new_multiday, snow_depth_new_max,
water_equivalent_snow_depth_new, water_equivalent_snow_depth_new_last_1h, water_equivalent_snow_depth_new_last_3h
There are several settings that can be used to control the interpolation behavior:
Name |
Type |
Default |
Description |
|---|---|---|---|
ts_geo_station_distance |
dict[str, float] |
20.0 (precipitation and new-snow variants) |
Max distance for stations used for interpolation (in km) |
ts_geo_use_nearby_station_distance |
float |
1.0 |
Distance (in km) until which the value of a nearby station is used instead of interpolation. |
ts_geo_min_gain_of_value_pairs |
float |
0.1 |
Minimum gain of value pairs [for an additional station] to be included in the list of stations used. This is to prevent taking all stations into account in case of a dense station network. |
ts_geo_num_additional_stations |
int |
3 |
Number of additional stations to be used for interpolation regardless of min_gain_of_value_pairs. This is to ensure that at least a certain number of stations are used for interpolation, even if the gain is not met. |
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.
Values represented as a table:
station_id |
resolution |
dataset |
parameter |
date |
value |
|---|---|---|---|---|---|
02480 |
daily |
climate_summary |
temperature_air_mean_2m |
2022-01-02 00:00:00+00:00 |
278.15 |
04411 |
daily |
climate_summary |
temperature_air_mean_2m |
2022-01-02 00:00:00+00:00 |
277.15 |
07341 |
daily |
climate_summary |
temperature_air_mean_2m |
2022-01-02 00:00:00+00:00 |
278.35 |
00917 |
daily |
climate_summary |
temperature_air_mean_2m |
2022-01-02 00:00:00+00:00 |
276.25 |
The interpolated value looks like this:
resolution |
dataset |
parameter |
date |
value |
|---|---|---|---|---|
daily |
climate_summary |
temperature_air_mean_2m |
2022-01-02 00:00:00+00:00 |
277.65 |
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("hourly", "temperature_air", "temperature_air_mean_2m"),
6 start_date=dt.datetime(2022, 1, 1),
7 end_date=dt.datetime(2022, 1, 20),
8)
9values = request.interpolate(latlon=(50.0, 8.9))
10df = values.df
11df
| station_id | resolution | dataset | parameter | date | value | distance_mean | taken_station_ids |
|---|---|---|---|---|---|---|---|
| str | str | str | str | datetime[μs, UTC] | f64 | f64 | list[str] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 00:00:00 UTC | 11.92 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 01:00:00 UTC | 11.89 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 02:00:00 UTC | 11.6 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 03:00:00 UTC | 11.54 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 04:00:00 UTC | 11.36 | 13.37 | ["02480", "04411", … "00917"] |
| … | … | … | … | … | … | … | … |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 20:00:00 UTC | 3.32 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 21:00:00 UTC | 3.34 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 22:00:00 UTC | 3.52 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 23:00:00 UTC | 3.37 | 13.37 | ["02480", "04411", … "00917"] |
| "f674568e" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-20 00:00:00 UTC | 3.48 | 13.37 | ["02480", "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:
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("hourly", "temperature_air", "temperature_air_mean_2m"),
6 start_date=dt.datetime(2022, 1, 1),
7 end_date=dt.datetime(2022, 1, 20),
8)
9values = request.interpolate_by_station_id(station_id="02480")
10df = values.df
11df
| station_id | resolution | dataset | parameter | date | value | distance_mean | taken_station_ids |
|---|---|---|---|---|---|---|---|
| str | str | str | str | datetime[μs, UTC] | f64 | f64 | list[str] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 00:00:00 UTC | 11.9 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 01:00:00 UTC | 11.8 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 02:00:00 UTC | 12.0 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 03:00:00 UTC | 11.6 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-01 04:00:00 UTC | 11.6 | 0.0 | ["02480"] |
| … | … | … | … | … | … | … | … |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 20:00:00 UTC | 3.2 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 21:00:00 UTC | 3.4 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 22:00:00 UTC | 3.6 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-19 23:00:00 UTC | 3.6 | 0.0 | ["02480"] |
| "7f2e709d" | "hourly" | "temperature_air" | "temperature_air_mean_2m" | 2022-01-20 00:00:00 UTC | 3.9 | 0.0 | ["02480"] |
Increase maximum distance for interpolation:
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3from wetterdienst import Settings
4
5settings = Settings(ts_interpolation_station_distance={"precipitation_height": 25.0})
6request = DwdObservationRequest(
7 parameters=("hourly", "precipitation", "precipitation_height"),
8 start_date=dt.datetime(2022, 1, 1),
9 end_date=dt.datetime(2022, 1, 20),
10 settings=settings
11)
12values = request.interpolate(latlon=(52.8, 12.9))
13df = values.df
14df
---------------------------------------------------------------------------
ValidationError Traceback (most recent call last)
Cell In[23], line 5
1 import datetime as dt
2 from wetterdienst.provider.dwd.observation import DwdObservationRequest
3 from wetterdienst import Settings
4
----> 5 settings = Settings(ts_interpolation_station_distance={"precipitation_height": 25.0})
6 request = DwdObservationRequest(
7 parameters=("hourly", "precipitation", "precipitation_height"),
8 start_date=dt.datetime(2022, 1, 1),
File ~/checkouts/readthedocs.org/user_builds/wetterdienst/envs/latest/lib/python3.12/site-packages/pydantic_settings/main.py:247, in BaseSettings.__init__(__pydantic_self__, _case_sensitive, _nested_model_default_partial_update, _env_prefix, _env_prefix_target, _env_file, _env_file_encoding, _env_ignore_empty, _env_nested_delimiter, _env_nested_max_split, _env_parse_none_str, _env_parse_enums, _cli_prog_name, _cli_parse_args, _cli_settings_source, _cli_parse_none_str, _cli_hide_none_type, _cli_avoid_json, _cli_enforce_required, _cli_use_class_docs_for_groups, _cli_exit_on_error, _cli_prefix, _cli_flag_prefix_char, _cli_implicit_flags, _cli_ignore_unknown_args, _cli_kebab_case, _cli_shortcuts, _secrets_dir, _build_sources, **values)
180 def __init__(
181 __pydantic_self__,
182 _case_sensitive: bool | None = None,
(...) 210 **values: Any,
211 ) -> None:
212 sources, init_kwargs = (
213 _build_sources
214 if _build_sources is not None
(...) 244 )
245 )
--> 247 super().__init__(**__pydantic_self__.__class__._settings_build_values(sources, init_kwargs))
File ~/checkouts/readthedocs.org/user_builds/wetterdienst/envs/latest/lib/python3.12/site-packages/pydantic/main.py:263, in BaseModel.__init__(self, **data)
261 # `__tracebackhide__` tells pytest and some other tools to omit this function from tracebacks
262 __tracebackhide__ = True
--> 263 validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
264 if self is not validated_self:
265 warnings.warn(
266 'A custom validator is returning a value other than `self`.\n'
267 "Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.\n"
268 'See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.',
269 stacklevel=2,
270 )
ValidationError: 1 validation error for Settings
ts_interpolation_station_distance
Extra inputs are not permitted [type=extra_forbidden, input_value={'precipitation_height': 25.0}, input_type=dict]
For further information visit https://errors.pydantic.dev/2.13/v/extra_forbidden
Interpolation is still in its early stages, we welcome feedback to enhance and refine its functionality.
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.
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.
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("hourly", "temperature_air", "temperature_air_mean_2m"),
6 start_date=dt.datetime(2022, 1, 1),
7 end_date=dt.datetime(2022, 1, 20),
8)
9values = request.summarize(latlon=(50.0, 8.9))
10df = values.df
11df
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:
1import datetime as dt
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4request = DwdObservationRequest(
5 parameters=("hourly", "temperature_air", "temperature_air_mean_2m"),
6 start_date=dt.datetime(2022, 1, 1),
7 end_date=dt.datetime(2022, 1, 20),
8)
9values = request.summarize_by_station_id(station_id="02480")
10df = values.df
11df
Summary is still in its early stages, we welcome feedback to enhance and refine its functionality.
Format#
To Dict#
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3request = DwdObservationRequest(
4 parameters=("daily", "kl", "temperature_air_mean_2m"),
5 start_date="2020-01-01",
6 end_date="2020-01-02"
7)
8stations = request.filter_by_station_id(station_id="01048")
9values = stations.values.all()
10values.to_dict(with_metadata=True, with_stations=True)
To Json#
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3request = DwdObservationRequest(
4 parameters=("daily", "kl", "temperature_air_mean_2m"),
5 start_date="2020-01-01",
6 end_date="2020-01-02"
7)
8stations = request.filter_by_station_id(station_id="01048")
9values = stations.values.all()
10print(values.to_json(with_metadata=True, with_stations=True))
To Ogc Feature Collection#
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3request = DwdObservationRequest(
4 parameters=("daily", "kl", "temperature_air_mean_2m"),
5 start_date="2020-01-01",
6 end_date="2020-01-02"
7)
8stations = request.filter_by_station_id(station_id="01048")
9values = stations.values.all()
10values.to_ogc_feature_collection(with_metadata=True)
To GeoJson#
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3request = DwdObservationRequest(
4 parameters=("daily", "kl", "temperature_air_mean_2m"),
5 start_date="2020-01-01",
6 end_date="2020-01-02"
7)
8stations = request.filter_by_station_id(station_id="01048")
9values = stations.values.all()
10print(values.to_geojson(with_metadata=True))
To CSV#
1from wetterdienst.provider.dwd.observation import DwdObservationRequest
2
3request = DwdObservationRequest(
4 parameters=("daily", "kl", "temperature_air_mean_2m"),
5 start_date="2020-01-01",
6 end_date="2020-01-02"
7)
8stations = request.filter_by_station_id(station_id="01048")
9values = stations.values.all()
10print(values.to_csv())
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.
1from wetterdienst import Settings
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4settings = Settings(ts_shape="long", ts_humanize=True, ts_convert_units=True) # defaults
5request = DwdObservationRequest(
6 parameters=("hourly", "temperature_air", "temperature_air_mean_2m"),
7 start_date="2019-01-01",
8 end_date="2020-01-01",
9 settings=settings
10)
11stations = request.filter_by_station_id(station_id=[1048])
12values = stations.values.all()
13df = values.filter_by_sql("parameter='temperature_air_mean_2m' AND value < -7.0;")
14df
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
parquet, feather, zarr#
file:///path/to/dwd.parquet
file:///path/to/dwd.feather
file:///path/to/dwd.zarr
from wetterdienst import Settings
from wetterdienst.provider.dwd.observation import DwdObservationRequest
request = DwdObservationRequest(
parameters=("hourly", "temperature_air"),
start_date="2019-01-01",
end_date="2020-01-01",
)
stations = request.filter_by_station_id(station_id=[1048, 1050])
stations.values.to_target("influxdb://localhost/?database=dwd&table=weather")
The previous example uses a batch approach meaning each station is written one by one. Also, it will automatically append data after the first batch.
You could also first collect all data and then write it at once:
from wetterdienst import Settings
from wetterdienst.provider.dwd.observation import DwdObservationRequest
request = DwdObservationRequest(
parameters=("hourly", "temperature_air"),
start_date="2019-01-01",
end_date="2020-01-01",
)
stations = request.filter_by_station_id(station_id=[1048, 1050])
stations.values.all().to_target("influxdb://localhost/?database=dwd&table=weather", if_exists="append")
You could also iterate over the stations and write them one by one:
from wetterdienst import Settings
from wetterdienst.provider.dwd.observation import DwdObservationRequest
request = DwdObservationRequest(
parameters=("hourly", "temperature_air"),
start_date="2019-01-01",
end_date="2020-01-01",
)
stations = request.filter_by_station_id(station_id=[1048, 1050])
for station in stations.values.query():
station.to_target("influxdb://localhost/?database=dwd&table=weather", if_exists="append")
The argument if_exists supports the following modes:
fail: Raise an error if the table/file already exists.replace: Drop the table/file before inserting new values.append: Insert new values to the existing table (not supported by files).skip: Do nothing if the table/file already exists.
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:
1from wetterdienst import Settings
2
3settings = Settings()
4settings.cache_dir
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.
1from wetterdienst import Settings
2from wetterdienst.provider.dwd.observation import DwdObservationRequest
3
4settings = Settings(fsspec_client_kwargs={"trust_env": True}) # use proxy from environment variables
5
6request = DwdObservationRequest(
7 parameters=("hourly", "temperature_air"),
8 settings=settings
9)
10stations = request.filter_by_station_id(station_id=[1048])
11stations