Usage
=====
wetterdienst (-h | --help) Display this page
wetterdienst --version Display the version number
wetterdienst cache Display cache location
wetterdienst info Display project information
Overview
========
This section roughly outlines the different families of command line
options. More detailed information is available within subsequent sections
of this page.
Coverage information:
wetterdienst about coverage --provider=<provider> --network=<network> [--resolutions=<resolutions>] [--datasets=<datasets>]
wetterdienst about fields --provider=<provider> --network=<network> --dataset=<dataset> --period=<period>
[--language=<language>]
Data acquisition:
wetterdienst {stations,values}
# Selection options
--provider=<provider> --network=<network> --parameters=<resolution/parameter> [--periods=<periods>]
# Filtering options
--all
--date=<date>
--station=<station>
--name=<name>
--latitude=<latitude> --longitude=<longitude> --rank=<rank>
--latitude=<latitude> --longitude=<longitude> --distance=<distance>
--left=<left> --bottom=<bottom> --right=<right> --top=<top>
--sql=<sql>
# Output options
[--format=<format>] [--pretty]
[--shape=<shape>] [--humanize] [--si_units]
[--drop_nulls] [--skip_empty] [--skip_threshold=0.95]
# Export options
[--target=<target>]
Data computation:
wetterdienst {interpolate,summarize}
# Selection options
--provider=<provider> --network=<network> --parameters=<resolution/parameter> --date=<date> [--periods=<periods>]
# Filtering options
--station=<station>
--latitude=<latitude> --longitude=<longitude>
# Interpolation options
--interpolation_station_distance=<distance>
--use_nearby_station_distance=<distance>
# Output options
[--format=<format>] [--pretty]
[--shape=<shape>] [--humanize] [--si_units]
[--drop_nulls] [--skip_empty] [--skip_threshold=0.95]
# Export options
[--target=<target>]
Options
=======
This section explains all command line options in detail.
Selection options:
--provider The data provider / organisation.
Examples: dwd, eccc, noaa, wsv, ea, eaufrance, nws, geosphere
--network The network of the data provider
Examples: observation, mosmix, radar, ghcn, pegel, hydrology
--parameters The parameters to be requested concatenated by a slash.
Examples: daily/climate_summary, daily/climate_summary/precipitation_height
[--periods] Dataset periods
Examples: "historical", "recent", "now"
Filtering options:
--all Flag to process all data
--date Date for filtering data
A single date(time) or interval in RFC3339/ISO8601 format.
See also:
- https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations
- https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
--start-date Alternative to --date for specifying the start of a time range.
Mutually exclusive with --date.
--end-date End of time range. Requires --start-date.
If omitted, --start-date is used as both start and end.
If only --end-date is given without --start-date, it is treated as a single date.
--name Name of station
--station Comma-separated list of station identifiers
--latitude Latitude of geolocation point for filtering stations or values
--longitude Longitude of geolocation point for filtering stations or values
--rank Rank of nearby stations when filtering by geolocation point
To be used with `--latitude` and `--longitude`.
--distance Maximum distance in km when filtering by geolocation point
To be used with `--latitude` and `--longitude`.
--left Left longitude of bounding box
--bottom Bottom latitude of bounding box
--right Right longitude of bounding box
--top Top latitude of bounding box
--sql SQL filter statement
--sql_values SQL filter to apply to values
Transformation options:
--shape Shape of DataFrame, "wide" or "long"
--humanize Humanize parameters
--si_units Convert to SI units
--skip_empty Skip empty stations according to ts_skip_threshold
--skip_threshold Skip threshold for a station to be empty (0 < ts_skip_threshold <= 1) [Default: 0.95]
--drop_nulls Whether to drop nan values from the result
Output options:
--format Output format. [Default: json]
--language Output language. [Default: en]
--pretty Pretty-print JSON
Export options:
--target Output target for storing data into different data sinks.
Other options:
-h --help Show this screen
--debug Enable debug messages
--listen HTTP server listen address.
--reload Run service and dynamically reload changed files
Examples
========
This section includes example invocations to get you started quickly. Most
of them can be used verbatim in your terminal. For displaying JSON output
more conveniently, you may want to pipe the output of Wetterdienst into the
excellent ``jq`` program, which can also be used for subsequent filtering
and transforming.
Acquire observation stations:
# Get list of all stations for daily climate summary data in JSON format
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --all
# Get list of all stations in CSV format
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --all --format=csv
# Get list of specific stations
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --station=1,1048,4411
# Get list of specific stations in GeoJSON format
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --station=1,1048,4411 --format=geojson
Acquire MOSMIX stations:
wetterdienst stations --provider=dwd --network=mosmix --parameters=hourly/large --all
wetterdienst stations --provider=dwd --network=mosmix --parameters=hourly/large --all --format=csv
Acquire DWD Observation station history:
wetterdienst history --provider=dwd --network=observation --parameters=daily/kl --station=1048
# Get specific sections of station history
wetterdienst history --provider=dwd --network=observation --parameters=daily/kl --station=1048 --sections=name,geography
Acquire observation data:
# Get data for a station selected by name (no prior 'stations' lookup needed)
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--name=Dresden-Hosterwitz
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--station=1048,4411
# Get daily climate summary data for specific stations in CSV format
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--station=1048,4411
# Get daily climate summary data for specific stations in long format
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--station=1048,4411 --shape="long"
# Limit output to specific date
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --date=2020-05-01 \
--station=1048,4411
# Limit output to a date range using --start-date/--end-date (alternative to --date interval syntax)
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl \
--start-date=2020-05-01 --end-date=2020-05-05 --station=1048
# Limit output to specified date range in ISO-8601 time interval format
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --date=2020-05-01/2020-05-05
--station=1048
# The real power horse: Acquire data across historical+recent data sets
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --date=1969-01-01/2020-06-11
--station=1048
# Acquire single data point for month 2020-05
wetterdienst values --provider=dwd --network=observation --parameters=monthly/kl --tidy --date=2020-05
--station=1048
# Acquire monthly data from 2017 to 2019
wetterdienst values --provider=dwd --network=observation --parameters=monthly/kl --tidy \
--date=2017/2019 --station=1048,4411
# Acquire annual data for 2019
wetterdienst values --provider=dwd --network=observation --parameters=annual/kl --tidy --date=2019
--station=1048,4411
# Acquire annual data from 2010 to 2020
wetterdienst values --provider=dwd --network=observation --parameters=annual/kl --tidy \
--date=2010/2020 --station=1048
# Acquire hourly data for a given time range
wetterdienst values --provider=dwd --network=observation --parameters=hourly/air_temperature \
--date=2020-06-15T12/2020-06-16T12 --station=1048,4411
# Acquire data for multiple given parameters
wetterdienst values --provider=dwd --network=observation \
--parameters=hourly/precipitation_more/precipitation_height,hourly/air_temperature/temperature_air_mean_2m \
--date=2020-06-15T12/2020-06-16T12 --station=1048,4411
Acquire MOSMIX data:
wetterdienst values --provider=dwd --network=mosmix --parameters=hourly/large/ttt,hourly/large/ff --station=65510
Acquire DMO data:
wetterdienst values --provider=dwd --network=dmo --parameters=hourly/icon_eu/ttt --station=65510
# short lead time
wetterdienst values --provider=dwd --network=dmo --parameters=hourly/icon/ttt --station=65510 --lead_time=short
# long lead time
wetterdienst values --provider=dwd --network=dmo --parameters=hourly/icon/ttt --station=65510 --lead_time=long
Compute data:
# Compute daily interpolation of precipitation for specific station selected by id
wetterdienst interpolate --provider=dwd --network=observation --parameters=daily/climate_summary/precipitation_height \
--date=2020-06-30 --station=01048
# Compute daily interpolation of precipitation for specific station selected by coordinates
wetterdienst interpolate --provider=dwd --network=observation --parameters=daily/kl/precipitation_height \
--date=2020-06-30 --latitude=49.9195 --longitude=8.9671
# Compute daily summary of precipitation for specific station selected by id
wetterdienst summarize --provider=dwd --network=observation --parameters=daily/kl/precipitation_height \
--date=2020-06-30 --station=01048
# Compute daily summary data of precipitation for specific station selected by coordinates
wetterdienst summarize --provider=dwd --network=observation --parameters=daily/kl/precipitation_height \
--date=2020-06-30 --latitude=49.9195 --longitude=8.9671
Geospatial filtering:
# Acquire stations and readings by geolocation, request specific number of nearby stations.
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--latitude=49.9195 --longitude=8.9671 --rank=5
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--latitude=49.9195 --longitude=8.9671 --rank=5 --date=2020-06-30
# Acquire stations and readings by geolocation, request stations within specific distance.
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--latitude=49.9195 --longitude=8.9671 --distance=25
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--latitude=49.9195 --longitude=8.9671 --distance=25 --date=2020-06-30
SQL filtering:
# Find stations by state.
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--sql="state='Sachsen'"
# Find stations by name (LIKE query).
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--sql="lower(name) LIKE lower('%dresden%')"
# Find stations by name (regexp query).
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--sql="regexp_matches(lower(name), lower('.*dresden.*'))"
# Filter values: Display daily climate observation readings where the maximum temperature is below two degrees celsius.
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--station=1048,4411 --sql_values="wind_gust_max > 20.0;"
# Filter measurements: Same as above, but use long format.
wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--station=1048,4411 --shape="long" \
--sql_values="parameter='wind_gust_max' AND value > 20.0"
Inquire metadata:
# Display coverage/correlation between parameters, resolutions and periods.
# This can answer questions like ...
wetterdienst about coverage --provider=dwd --network=observation
# Tell me all available datasets of resolution 1_minute
wetterdienst about coverage --provider=dwd --network=observation --resolutions=1_minute
# Tell me all available climate_summary datasets with their parameters
wetterdienst about coverage --provider=dwd --network=observation --datasets=climate_summary
Export data to files:
# Export list of stations into spreadsheet
wetterdienst stations --provider=dwd --network=observation --parameters=daily/kl --periods=recent \
--all --target=file://stations_result.xlsx
# Shortcut command for fetching readings.
# It will be used for the next invocations.
alias fetch="wetterdienst values --provider=dwd --network=observation --parameters=daily/kl --periods=recent --station=1048,4411"
# Export readings into spreadsheet (Excel-compatible)
fetch --target="file://observations.xlsx"
# Export readings into Parquet format and display head of Parquet file
fetch --target="file://observations.parquet"
# Check Parquet file
parquet-tools schema observations.parquet
parquet-tools head observations.parquet
# Export readings into Zarr format
fetch --target="file://observations.zarr"
Export data to databases:
# Shortcut command for fetching readings.
# It will be used for the next invocations.
alias fetch="wetterdienst values --provider=dwd --network=observation --parameters=kl --resolution=daily --period=recent --station=1048,4411"
# Store readings to DuckDB
fetch --target="duckdb:///observations.duckdb?table=weather"
# Store readings to InfluxDB
fetch --target="influxdb://localhost/?database=observations&table=weather"
# Store readings to CrateDB
fetch --target="crate://localhost/?database=observations&table=weather"
The HTTP REST API service:
# Start service on standard port, listening on http://localhost:7890.
wetterdienst restapi
# Start service on standard port and watch filesystem changes.
# This is suitable for development.
wetterdienst restapi --reload
# Start service on public interface and specific port.
wetterdienst restapi --listen=0.0.0.0:8890
Explore OPERA radar stations:
# Display all radar stations.
wetterdienst radar --all
# Display radar stations filtered by country.
wetterdienst radar --country-name=france
# Display OPERA radar stations operated by DWD.
wetterdienst radar --dwd
# Display radar station with specific ODIM- or WMO-code.
wetterdienst radar --odim-code=deasb
wetterdienst radar --wmo-code=10103
Create warming stripes (only DWD Observation data):
# Create warming stripes for a specific station
wetterdienst warming_stripes --station=1048 > warming_stripes.png
# Create warming stripes for a specific station with approximate name
wetterdienst warming_stripes --name=Dresden-Klotzsche --name_treshold=70 > warming_stripes.png
# Create warming stripes for a specific station for years 2000 to 2020
wetterdienst warming_stripes --station=1048 --start_year=2000 --end_year=2020 > warming_stripes.png
# Create warming stripes for a specific station and write to file
wetterdienst warming_stripes --station=1048 --target=warming_stripes.png