REST API

REST API#

Wetterdienst has an integrated REST API which can be started by invoking:

wetterdienst restapi

There’s also a hosted version at wetterdienst.eobs.org.

Web App#

The REST API is complemented by a modern web app built with Nuxt.js, providing an interactive interface for exploring weather data.

Features#

  • Interactive Explorer: Browse and query weather data with an intuitive UI

    • Map-based station selection with search and filtering

    • Parameter selection across multiple providers and networks

    • Real-time data visualization with tables and charts

    • Date range selection for historical data

  • Comprehensive Settings: Full access to all backend API parameters

    • General: Humanize parameters, unit conversion, custom unit targets

    • Values mode: Data shape (long/wide), skip empty stations, drop nulls

    • Interpolation mode: Station distances, nearby station distance, gain thresholds

  • Climate Stripes: Visual representation of temperature trends

  • Customization: Primary color themes and dark mode support

  • Export: Download data in CSV, JSON, or GeoJSON formats

Access#

Visit wetterdienst.eobs.org to use the web interface.

By default the stations, values, interpolate, summarize and history endpoints return only the requested data. Add with_metadata=true to include the provider-metadata block, and (for the value endpoints) with_stations=true to include the queried stations’ metadata. With with_metadata=true, the JSON and GeoJSON of values, interpolate and summarize also carry a settings block next to metadata: the settings the result was got with, named as the endpoint’s query parameters are. interpolate and summarize also report the settings the server sets alone for them, which no query parameter of theirs changes: skip_empty, skip_threshold, skip_criteria, drop_nulls and station_distance_resolution_factors.

The following examples use httpie to demonstrate the usage of the REST API.

Examples#

Coverage#

http localhost:7890/api/coverage

Glossary#

Coverage says which parameters a provider offers; the glossary says what any of them means and which unit it comes back in.

# Look up every canonical parameter.
http localhost:7890/api/glossary

# Match names containing some text.
http localhost:7890/api/glossary parameter==radiation

# List every parameter of one quantity.
http localhost:7890/api/glossary unit_type==temperature

Settings#

A setting a request to values, interpolate or summarize leaves out takes the server’s WD_TS_* variable, where it sets one, else wetterdienst’s default. The settings endpoint reports what each of them takes, keyed by endpoint, with unit_targets naming the unit of every quantity.

It takes the settings query parameters of the three endpoints, and answers what they resolve to over the server’s, for each endpoint that takes the parameter: humanize, convert_units and unit_targets apply to all three, min_gain_of_value_pairs and num_additional_stations to interpolate and summarize. A value an endpoint refuses is refused here the same way, and an unknown parameter too, so a set of settings can be checked before fetching. Nothing is stored on the server: the parameters apply to that one answer.

http localhost:7890/api/settings

# What a values request with shape=wide would get: the wide shape turns drop_nulls off.
http localhost:7890/api/settings shape==wide

# Check unit targets before fetching; an unknown unit is a 400 naming it.
http localhost:7890/api/settings unit_targets=='{"temperature": "degree_fahrenheit"}'

Stations#

# Acquire list of DWD OBS stations.
http localhost:7890/api/stations provider==dwd network==observation parameters==daily/kl periods==recent all==true

# Filter stations by name (fuzzy, case-insensitive).
http localhost:7890/api/stations provider==dwd network==observation parameters==daily/kl periods==recent name==Darmstadt

# Filter by name with custom threshold (0–1, default 0.8).
http localhost:7890/api/stations provider==dwd network==observation parameters==daily/kl periods==recent name==Darmstatt name_threshold==0.85

# Query list of stations with SQL, on a server running with WD_RESTAPI_SQL=true.
http localhost:7890/api/stations provider==dwd network==observation parameters==daily/kl periods==recent sql=="lower(name) LIKE lower('%dresden%');"

# Acquire list of DWD DMO stations.
http localhost:7890/api/stations provider==dwd network==dmo parameters==hourly/icon/temperature_air_2m periods==recent all==true

Issues (available model-run datetimes)#

# List available MOSMIX-L run datetimes for a station.
http localhost:7890/api/issues provider==dwd network==mosmix station==10147

# List available DMO ICON run datetimes for a station.
http localhost:7890/api/issues provider==dwd network==dmo station==10147

# List available SWSMOS run datetimes; one run holds every road station, so any station lists them.
http localhost:7890/api/issues provider==dwd network==swsmos station==A006

Values#

timestamp covers everything it names: 2020-08-01 is that whole day – all 24 readings of it for hourly data – 2020-08 the month and 2020 the year. An interval runs from the start of the span its first half names to the end of the span its second, so 2020-08/2020-09 ends with September. A date carrying a time, 2020-08-01T12, names that one instant.

# Acquire observations.
http localhost:7890/api/values provider==dwd network==observation parameters==daily/kl periods==recent station==1048,4411

# Observations for specific date.
http localhost:7890/api/values provider==dwd network==observation parameters==daily/kl periods==recent station==1048,4411 timestamp==2020-08-01

# Observations for a whole month, since a date covers everything it names.
http localhost:7890/api/values provider==dwd network==observation parameters==daily/kl periods==recent station==1048,4411 timestamp==2020-08

# Observations for date range.
http localhost:7890/api/values provider==dwd network==observation parameters==daily/kl periods==recent station==1048,4411 timestamp==2020-08-01/2020-08-05

# Observations with SQL, on a server running with WD_RESTAPI_SQL=true.
http localhost:7890/api/values provider==dwd network==observation parameters==daily/kl periods==recent station==1048,4411 shape=="wide" sql_values=="temperature_air_max_2m < 2.0;"

# Acquire ICON data.
http localhost:7890/api/values provider==dwd network==dmo parameters==hourly/icon/temperature_air_2m station==01001 timestamp==2024-05-27

SQL filters#

sql (stations and values: which stations) and sql_values (values, interpolate and summarize: which rows of the result) take a SQL WHERE clause, run by DuckDB on the server. A server refuses both with a 403 unless it runs with the setting restapi_sql enabled (WD_RESTAPI_SQL=true); the MCP tools follow the same setting, and the library and the CLI are not gated.

The clause is a single condition on the frame, called df: anything after it, a second statement, ORDER BY or LIMIT, is refused. It cannot read or list files, reach the network or load DuckDB extensions, and runs on one thread with DuckDB’s memory limit at 1 GiB plus the size of the frame. What it can still do once enabled: read DuckDB’s own settings, which name paths on the server; run for as long as it likes on that thread; and allocate memory DuckDB’s limit does not count, such as one very long string. The limits hold per request, not for the server as a whole. Enable it only for clients you trust with that.

MCP endpoint#

The REST API can optionally expose a Model Context Protocol (MCP) endpoint at /mcp, so LLM agents can call the data endpoints (coverage, stations, values, interpolate, summarize, stripes, alerts, …) as MCP tools. It is served over the streamable-HTTP transport by FastMCP, generated from the REST API’s own routes and running in the same process.

The generated tools are made agent-friendly so even small models use them correctly: a workflow instructions block (find a station, then query its values) is attached to the server, the tools get clean names (values rather than values_api_values_get), and the non-data endpoints (index, health, …) are hidden.

Install the optional extra to enable it:

pip install wetterdienst[mcp]
wetterdienst restapi

The endpoint then lives next to the HTTP API, on the backend:

http://localhost:7890/mcp

Point any MCP client (streamable HTTP) at that URL — for example:

{
  "mcpServers": {
    "wetterdienst": {
      "url": "http://localhost:7890/mcp"
    }
  }
}

Without the [mcp] extra installed, the REST API behaves exactly as before and the /mcp route is simply absent. GET /api/version says which of the two an instance is:

{"version": "0.132.0", "mcp_enabled": true}

The app reads that flag before offering an MCP client configuration, so an instance installed without the extra is never advertised as having an endpoint it does not serve.

Hosted instance#

The [mcp] extra is included in the backend Docker image, and the app proxies /mcp through to the backend (preserving the streamable-HTTP POST/SSE transport), so the hosted app serves the MCP endpoint on its own origin:

https://wetterdienst.eobs.org/mcp