Glossary

Domain terms for hochwasserzentralen-cli and the LHP-PublicAPI. Library and technical terms (Transport, RequestEngine, …) live in DEVELOPING.md.

LHP (Länderübergreifendes Hochwasserportal)

The joint flood portal of the German states (Bundesländer), online at https://www.hochwasserzentralen.de. Each state runs its own flood warning service (Hochwasserzentrale); the LHP aggregates their warnings and gauge classifications into one national picture and publishes it via the LHP-PublicAPI that this CLI wraps. The data is CC BY 4.0 — see DATA_LICENSE.md.

AlertArea vs Station

The API’s two kinds of items:

• AlertArea (hochwasser alerts) — a regional warning area: a region or a whole state as a Polygon, or a river reach as a LineString (12 of the 40 test-system areas on 2026-09-26, e.g. HE_102 “Rhein: Worms bis Nahemündung”), with the state’s current official flood warning for it: headline, link to the state’s portal, warning class, optionally a full CAP block. Zero alert areas = no active warnings.
• Station (hochwasser stations) — a single gauge (Pegel) with its current flood classification. About 1600 stations nationwide (1573 on 2026-09-15; situation reports the current count as totalStations). No water levels — the LHP publishes only the class. For measured levels use pegel-online-cli (many stationLinks even point to pegelonline.wsv.de). A gauge on a state border can be listed twice, once per reporting state, with the same coordinates and different ids (e.g. HE_25700100 and RP_25700100, Kaub). stateClassName is the state’s own label for the class: it is not translated by --lang en, and Rheinland-Pfalz sends it with an HTML entity (< for <).

lhpClass — two different scales!

The single most important trap in this API: alerts and stations use different lhpClass scales, and different types.

Station scale (stations, numeric lhpClass, also used by --min-class and situation — in the library client.situation() and the exported stationClass / aggregateSituation):

null is not in the legend, but it occurs live (216 of 1573 gauges on 2026-09-15, most of them in MV). situation counts these gauges in its "-1" bucket, --min-class (library: stations({ minClass })) drops them whatever the value, and the GeoJSON export leaves out the lhpClass property for them. A state with no gauge at all in the data (Hamburg, today) is a different case: situation lists it with stations: 0 and worstClass: null. Any other value (off the scale, a fraction, a string) makes --min-class and situation stop with exit 1 instead of guessing, since a changed scale could otherwise hide a flood; the library’s situation(), stations({ minClass }) and stationClass throw a HochwasserzentralenParseError for it, the same check.

Alert scale (alerts, lhpClass is a string, e.g. "4"):

Never compare an alert’s class to a station’s class numerically, and remember an alert lhpClass: "1" is good news (Entwarnung) while a station lhpClass: 1 is a small flood. Every response carries its own legend mapping classes to names and colours — prefer it over hard-coding.

lhpClass vs Meldestufen

Each German state defines its own local warning levels (Meldestufen / Alarmstufen — e.g. Bavaria’s Meldestufe 1–4, Brandenburg’s Alarmstufe I–IV). The LHP class is the harmonised, nationwide scale the portal maps those onto so states are comparable. The state’s own portal (the alertLink / stationLink / stateLinks targets) speaks in local Meldestufen; this API speaks lhpClass. Don’t treat them as interchangeable numbers.

CAP (Common Alerting Protocol)

The international OASIS standard format for public warnings (also used by DWD and BBK/NINA). With --cap, each alert carries a cap block: identifier, sender, sent, status, msgType (Alert/Update/Cancel), references, and an info object with severity (Minor/Moderate/ Severe/Extreme), urgency, certainty, onset/expires, headline, description, instruction (what to do), web and contact. The instruction field is the actionable part for end users.

State codes (Bundesländer)

The --states filter takes a comma-separated subset of these 16 codes (case-insensitive; validated — a typo exits 2 rather than silently returning everything). The API filters by it, and the CLI applies it again to the answer: only the requested states’ gauges are returned and counted, so a server that ignored the filter can’t change the result:

Item ids are prefixed with the state code (BY_577, BE_5803500); the station stateId uses ISO 3166-2 form (DE-BE), and stateLinks maps those ids to each state’s own flood portal.

Envelope fields (attribution & freshness)

Every response wraps its data in an envelope with status ("success"; anything else is an error, exit 1, never read as data), source / sourceName (the LHP), licence / licenceName (CC BY 4.0), updated (the data timestamp — display it, the licence requires it), lastModified, a legend, and a bbox ([west, north, east, south] in the live API, a fixed box around Germany whatever the filter). updated and lastModified always carry a +01:00 offset, also in summer; the instant is right, so convert it to German local time before you display it. This CLI never strips these fields. Its GeoJSON export carries the attribution and updated as foreign members, and computes its own bbox from the exported features in the RFC 7946 order [west, south, east, north].

Pegel / water level (what this API does NOT have)

A Pegel is a gauge. The LHP tells you each gauge’s flood class, not its water level in centimetres. Levels, discharge and measurement histories for the federal waterways come from PEGELONLINE (WSV) — sibling CLI: pegel-online-cli (pegel current BONN etc.).

Test system

https://api.hochwasserzentralen.de/public/v1/test — same API, fixed canned data that always includes active alerts. Reach it with --base-url …/public/v1/test. Never treat its output as the real situation.

Log record

Every diagnostic line the CLI writes to stderr: a timestamp, a level (ERROR, WARN, INFO) and a topic hochwasser.<area>, as text (log4j style) or with --log-format jsonl as one JSON object per line. The areas: cli (usage errors, commander’s messages, unexpected errors), api (the API’s answers: an error status, an envelope whose status isn’t success, the redirect hint, and a malformed answer — bad JSON, a proxy’s HTML page, the wrong shape, the GeoJSON representation instead of plain JSON), http (the connection, the size-cap hint, the cleartext warning, one WARN per retry before it waits) and output (the -o file, what a GeoJSON export left off the map, a failed write to stdout). A record is always one line; control characters in it are escaped.