# Glossary A reference for the domain concepts and project-specific terms used throughout `dwd-cli`. The data comes from the **Deutscher Wetterdienst (DWD)** Warnwetter app backend (`warnwetter.de`); the domain is German, so this glossary gives the English term used in the CLI/API alongside the original German where one exists. > **Translation table.** The CLI follows these: > > | German | English / API term | > | --- | --- | > | Warnung | warning | > | Gemeinde | municipality | > | Küste / Binnensee | coast / inland lake | > | Vorhersage | forecast | > | Meldung | (crowd-sourced) report | > | Wetterstation | weather station | --- ## The DWD Warnwetter source **DWD — Deutscher Wetterdienst.** Germany's national meteorological service. It operates the public weather-warning system and the *Warnwetter* app, whose backend this tool wraps. **Warnwetter app.** DWD's official weather-warning app for the public. Its backend serves both live station forecasts and the periodically-published warning feeds; both are open (no authentication) and read-only. **warnwetter.de.** The host domain of the Warnwetter backend. The data is split across two hosts (see *Live web service* and *Static S3 bucket*). **Open / no-auth endpoints.** The endpoints this client uses require no API key. They are all `GET` and read-only; `dwd-cli` never writes. --- ## The two hosts **Live web service.** `https://app-prod-ws.warnwetter.de/v30` — the live backend that answers station-overview requests, queried with parameters. CLI override: `--base-url`; the path version segment is **`/v30`**. **Static S3 bucket.** `https://s3.eu-central-1.amazonaws.com/app-prod-static.warnwetter.de/v16` — an Amazon S3 bucket holding the periodically-published warning and crowd feeds as static JSON files. CLI override: `--static-base-url`; the path version segment is **`/v16`**. **gzip-encoded feeds.** The static warning files are stored on S3 with `Content-Encoding: gzip` and are served compressed regardless of the request's `Accept-Encoding`. The client's transport transparently decompresses gzip/deflate/brotli bodies. --- ## Resources & endpoints **Station overview (`stationOverviewExtended`).** Forecasts/observations for one or more DWD weather stations, returned by the live web service. The response is an object keyed by station id; each value carries `forecast1`, `forecast2`, `days`, `warnings` and `threeHourSummaries`. Client: `client.weather.stationOverview(ids)`. CLI: `station-overview --id `. **Nowcast warnings (`warnings_nowcast.json`).** Short-term ("nowcast") weather warnings — imminent severe weather. Static-bucket feed. Client: `client.warnings.nowcast(lang)`. CLI: `warnings nowcast`. **Gemeinde warnings (`gemeinde_warnings_v2.json`).** Municipality-level weather warnings, i.e. warnings resolved to the German *Gemeinde* (municipality). Static feed. Client: `client.warnings.gemeinde(lang)`. CLI: `warnings gemeinde`. **Coast warnings (`warnings_coast.json`).** Coastal weather warnings, with `warnings` keyed by coastal zone (and inland-lake / *Binnensee* areas). Unlike the nowcast and Gemeinde items, coast items carry no `regions` geometry and no `start`/`end`. Static feed. Client: `client.warnings.coast(lang)`. CLI: `warnings coast`. **Crowd overview (`crowd_meldungen_overview_v2.json`).** An overview of crowd-sourced weather reports (*Meldungen*) submitted by app users. Static feed. Client: `client.crowd()`. CLI: `crowd`. --- ## Identifiers, units & response fields **Station id.** The identifier of a DWD weather station, used by the Warnwetter app — typically a 5-digit numeric id (e.g. München-Stadt = `10865`). Repeatable on the CLI (`--id 10865 --id 01766`); a single value may also be a comma-separated list (`--id 10865,01766`), and the two forms are equivalent — both are sent to the web service joined by commas as `stationIds=10865,01766`. **`forecast1` / `forecast2`.** Two forecast series carried per station in a station overview. `forecast1` is hourly (`timeStep` 3600000) from midnight of the current day: `temperature` runs ten days from `start`, while the shorter arrays (`precipitationTotal`, `sunshine`, `humidity`, …) are end-aligned at `start` + 72 h rather than anchored at `start`. `forecast2` continues from there in three-hour steps (`timeStep` 10800000); it is not an hourly copy of `forecast1`. **`days`.** The multi-day forecast summary block of a station overview. **`threeHourSummaries`.** Three-hour aggregated forecast summaries within a station overview. **`warnings` (station).** The warnings block embedded in a station overview, i.e. warnings relevant to that station's location. **`time`.** The Unix-epoch timestamp (a `number`) stamped on every warning feed envelope, marking when that feed was generated. **`binnenSee`.** *Inland lake.* An optional block on the nowcast/gemeinde warning envelopes carrying inland-lake (large-lake) warnings. With none active it has come back as `null` (nowcast) and `{}` (gemeinde). **`meldungen`.** The array of crowd-sourced reports in the crowd overview. May be accompanied by `start`, `end` and `highestSeverities`. `start`/`end` bound the window the reports cover (12 hours when checked); the feed's `windowsSizeHours` field did not match that window, so each report's `timestamp` is the reliable time. **Coastal zone.** The key by which coastal warnings are grouped in the coast feed (each zone maps to its own warnings object). --- ## Enums & codes the client surfaces **Lang (`de` | `en`).** The language of a warning feed. German (`de`, the default) feeds have no filename suffix; English (`en`) feeds use the `_en` filename suffix (e.g. `warnings_nowcast_en.json`). Exposed as `LangValues` (runtime array) and the `Lang` union type, and validated as the CLI `--lang` choice on every `warnings` subcommand. --- ## Feed envelopes (typed response shapes) **`StationOverview`.** `{ [stationId: string]: JsonObject }` — the station-overview response keyed by station id. The DWD-specific per-station payload is exposed as a faithful raw `JsonObject` rather than a guessed type. **`WarningsFeed`.** The common envelope of the nowcast and gemeinde feeds: `{ time: number; warnings: JsonObject[]; binnenSee?: JsonValue }`. **`CoastWarningsFeed`.** The coast feed envelope: `{ time: number; warnings: JsonObject }` — `warnings` is keyed by coastal zone (an object, not an array). **`CrowdOverview`.** The crowd feed envelope: `{ start?, end?, highestSeverities?, meldungen: JsonObject[] }`. **`JsonObject` / `JsonValue`.** The general JSON value types used where a payload is large and DWD-specific enough that a hand-written interface would be a guess. --- ## API & client behaviour **Rate limiting / transient errors.** The backend may answer with **429** (too many requests) or **503** (service unavailable). The client retries these automatically with linear backoff — the number of retries is tunable with `--max-retries` (default `2`); the base inter-attempt delay grows linearly and is an internal default, not a CLI flag. **Redirects.** The engine follows up to `maxRedirects` (default `5`) HTTP redirects (301/302/303/307/308). On a cross-origin redirect, sensitive headers (`Authorization`/`X-API-Key`/`Cookie`) are stripped so credentials issued for one host are never forwarded to another. **Decompression bomb cap.** `maxResponseBytes` (default 100 MiB; `0` = unlimited) bounds both the wire bytes and the *decompressed* output, so a small compressed feed cannot expand into an out-of-memory condition. Exceeding it raises a `DwdNetworkError`. **Content-Type guard.** A `200` response whose `Content-Type` is clearly not JSON (e.g. a captive-portal HTML page) is reported as a `DwdParseError` naming the type actually returned, rather than being fed to `JSON.parse`. --- > **Library & internals.** Terms for the TypeScript client and its internals — > `DwdClient`, the request engine, transport, retry/backoff, error types, query > builder, feed envelope types — now live in **[DEVELOPING.md](DEVELOPING.md)**.