Glossar

Fachbegriffe für hochwasserzentralen-cli und die LHP-PublicAPI. Bibliotheks- und technische Begriffe (Transport, RequestEngine, …) stehen in DEVELOPING.md.

LHP (Länderübergreifendes Hochwasserportal)

Das gemeinsame Hochwasserportal der Bundesländer, online unter https://www.hochwasserzentralen.de. Jedes Land betreibt eine eigene Hochwasserzentrale; das LHP bündelt deren Warnungen und Pegeleinstufungen zu einem bundesweiten Gesamtbild und veröffentlicht es über die LHP-PublicAPI, die diese CLI einbindet. Die Daten stehen unter CC BY 4.0 – siehe DATA_LICENSE.md.

AlertArea vs. Station

Die zwei Arten von Einträgen der API:

• AlertArea (hochwasser alerts) – ein regionales Warngebiet: eine Region oder ein ganzes Land als Polygon oder ein Flussabschnitt als LineString (12 der 40 Gebiete im Testsystem am 26.09.2026, z. B. HE_102 „Rhein: Worms bis Nahemündung“), mit der aktuellen amtlichen Hochwasserwarnung des Landes dafür: Überschrift, Link zum Portal des Landes, Warnklasse, optional ein vollständiger CAP-Block. Null Warngebiete = keine aktiven Warnungen.
• Station (hochwasser stations) – ein einzelner Pegel mit seiner aktuellen Hochwasser-Einstufung. Rund 1.600 Pegel bundesweit (1.573 am 15.09.2026; situation nennt die aktuelle Zahl als totalStations). Keine Wasserstände – das LHP veröffentlicht nur die Klasse. Gemessene Wasserstände liefert pegel-online-cli (viele stationLinks verweisen sogar auf pegelonline.wsv.de). Ein Pegel an einer Landesgrenze kann doppelt aufgeführt sein, einmal je meldendem Land, mit denselben Koordinaten und unterschiedlichen IDs (z. B. HE_25700100 und RP_25700100, Kaub). stateClassName ist die eigene Bezeichnung des Landes für die Klasse: --lang en übersetzt sie nicht, und Rheinland-Pfalz liefert sie mit einer HTML-Entität (< für <).

lhpClass – zwei verschiedene Skalen!

Die wichtigste Falle dieser API: Warnungen und Pegel verwenden unterschiedliche lhpClass-Skalen und unterschiedliche Typen.

Pegelskala (stations, numerische lhpClass, auch von --min-class und situation verwendet – in der Bibliothek von client.situation() und den exportierten stationClass / aggregateSituation):

null steht nicht in der legend, kommt live aber vor (216 von 1.573 Pegeln am 15.09.2026, die meisten in MV). situation zählt diese Pegel im Bucket "-1", --min-class (Bibliothek: stations({ minClass })) filtert sie unabhängig vom Wert heraus, und der GeoJSON-Export lässt bei ihnen die Eigenschaft lhpClass weg. Ein Land ganz ohne Pegel in den Daten (derzeit Hamburg) ist ein anderer Fall: situation führt es mit stations: 0 und worstClass: null. Jeder andere Wert (außerhalb der Skala, eine Kommazahl, ein String) lässt --min-class und situation mit Exit-Code 1 abbrechen, statt zu raten – eine geänderte Skala könnte sonst ein Hochwasser verdecken. situation(), stations({ minClass }) und stationClass der Bibliothek werfen dafür einen HochwasserzentralenParseError, dieselbe Prüfung.

Warnskala (alerts, lhpClass ist ein String, z. B. "4"):

Vergleichen Sie die Klasse einer Warnung nie numerisch mit der Klasse eines Pegels, und denken Sie daran: lhpClass: "1" bei einer Warnung ist eine gute Nachricht (Entwarnung), während lhpClass: 1 bei einem Pegel ein kleines Hochwasser bedeutet. Jede Antwort enthält eine eigene legend, die den Klassen Namen und Farben zuordnet – nutzen Sie sie, statt Werte fest einzuprogrammieren.

lhpClass vs. Meldestufen

Jedes Bundesland legt eigene lokale Warnstufen fest (Meldestufen / Alarmstufen – z. B. Meldestufe 1–4 in Bayern, Alarmstufe I–IV in Brandenburg). Die LHP-Klasse ist die vereinheitlichte, bundesweite Skala, auf die das Portal diese abbildet, damit die Länder vergleichbar sind. Das Portal des jeweiligen Landes (die Ziele von alertLink / stationLink / stateLinks) spricht in lokalen Meldestufen, diese API in lhpClass. Behandeln Sie sie nicht als austauschbare Zahlen.

CAP (Common Alerting Protocol)

Das internationale OASIS-Standardformat für öffentliche Warnungen (auch von DWD und BBK/NINA verwendet). Mit --cap enthält jede Warnung einen cap-Block: identifier, sender, sent, status, msgType (Alert/Update/Cancel), references und ein info-Objekt mit severity (Minor/Moderate/Severe/Extreme), urgency, certainty, onset/expires, headline, description, instruction (Handlungsempfehlung), web und contact. Das Feld instruction ist für Endnutzer der Teil, nach dem sie handeln können.

Länderkürzel der Bundesländer

Der Filter --states akzeptiert eine kommagetrennte Teilmenge dieser 16 Kürzel (Groß-/Kleinschreibung egal; validiert – ein Tippfehler endet mit Exit-Code 2, statt stillschweigend alles zurückzugeben). Die API filtert danach, und die CLI wendet den Filter noch einmal auf die Antwort an: Nur die Pegel der angefragten Länder werden ausgegeben und gezählt, ein Server, der den Filter ignoriert, kann das Ergebnis also nicht verändern:

Die IDs der Einträge beginnen mit dem Länderkürzel (BY_577, BE_5803500); die stateId eines Pegels hat die Form nach ISO 3166-2 (DE-BE), und stateLinks ordnet diese IDs dem jeweiligen Hochwasserportal des Landes zu.

Envelope-Felder (Namensnennung & Aktualität)

Jede Antwort verpackt ihr data in einen Envelope mit status ("success"; alles andere ist ein Fehler, Exit-Code 1, und wird nie als Daten gelesen), source / sourceName (das LHP), licence / licenceName (CC BY 4.0), updated (der Zeitstempel der Daten – zeigen Sie ihn an, die Lizenz verlangt es), lastModified, einer legend und einer bbox (in der Live-API [west, north, east, south], ein fester Rahmen um Deutschland, unabhängig vom Filter). updated und lastModified tragen immer den Offset +01:00, auch im Sommer; der Zeitpunkt stimmt, rechnen Sie ihn also vor der Anzeige in deutsche Ortszeit um. Diese CLI entfernt diese Felder nie. Ihr GeoJSON-Export übernimmt die Namensnennung und updated als Foreign Members und berechnet eine eigene bbox aus den exportierten Features, in der Reihenfolge nach RFC 7946 [west, south, east, north].

Pegel / Wasserstand (was diese API NICHT hat)

Ein Pegel ist eine Messstelle für den Wasserstand. Das LHP nennt Ihnen die Hochwasser-Klasse jedes Pegels, nicht seinen Wasserstand in Zentimetern. Wasserstände, Abflüsse und Messverläufe für die Bundeswasserstraßen kommen von PEGELONLINE (WSV) – Schwester-CLI: pegel-online-cli (pegel current BONN usw.).

Testsystem

https://api.hochwasserzentralen.de/public/v1/test – dieselbe API mit festen, vorgefertigten Daten, die immer aktive Warnungen enthalten. Erreichbar mit --base-url …/public/v1/test. Behandeln Sie die Ausgabe nie als tatsächliche Lage.

Log-Eintrag (log record)

Jede Diagnosezeile, die die CLI nach stderr schreibt: ein Zeitstempel, eine Stufe (ERROR, WARN, INFO) und ein Thema hochwasser.<Bereich>, als Text (im Stil von log4j) oder mit --log-format jsonl als ein JSON-Objekt pro Zeile. Die Bereiche: cli (Bedienfehler, Meldungen von commander, unerwartete Fehler), api (die Antworten der API: ein Fehlerstatus, ein Envelope, dessen status nicht success ist, der Hinweis bei einer Umleitung und eine fehlerhafte Antwort — kein gültiges JSON, die HTML-Seite eines Proxys, die falsche Form, die GeoJSON-Darstellung statt reinem JSON), http (die Verbindung, der Hinweis zur Größengrenze, die Klartext-Warnung, je Wiederholung eine WARN-Zeile vor dem Warten) und output (die -o-Datei, was ein GeoJSON-Export nicht auf die Karte bringt, ein Schreibfehler auf stdout). Ein Eintrag ist immer eine Zeile; Steuerzeichen darin werden maskiert.