Glossar

Ein Nachschlagewerk für die Fachbegriffe und projektspezifischen Begriffe, die in nina-warnungen-cli verwendet werden. Die Fachdomäne von NINA ist der deutsche Bevölkerungsschutz; dieses Glossar nennt den in CLI und API verwendeten Begriff, wo vorhanden neben dem deutschen Originalbegriff.

NINA & Betreiber

NINA – Notfall-Informations- und Nachrichten-App. Die Warn-App des Bundes, mit der die Bevölkerung Notfallinformationen und Meldungen erhält. Dieselben Warndaten, die die App speisen, werden über die offene REST-API veröffentlicht, die dieses Tool kapselt.

warnung.bund.de. Das öffentliche Warnportal und der Host der offenen API (Basis-URL https://warnung.bund.de, Pfadpräfix /api31). Weder Authentifizierung noch API-Schlüssel sind nötig; jeder Endpoint ist ein rein lesender GET.

BBK – Bundesamt für Bevölkerungsschutz und Katastrophenhilfe. Die Bundesbehörde, die NINA und die Warninfrastruktur betreibt.

Warnquellen

NINA bündelt mehrere unabhängige Warn-„Anbieter“, von denen jeder als eigene mapData.json-Liste veröffentlicht wird. Die CLI zeigt die gültigen Werte über nina sources an, und nina map-data <source> ruft die aktuellen Warnungen einer Quelle ab.

Quelle (NinaSource). Einer der gebündelten Anbieter. Gültige Werte sind:

Quelle Bedeutung
mowas MoWaS – Modulares Warnsystem. Das modulare Warnsystem von Bund und Ländern für den Bevölkerungsschutz.
katwarn KATWARN. Kommunaler bzw. regionaler Warndienst.
biwapp BIWAPP – Bürger-Info- und Warn-App. Kommunaler Warndienst.
dwd DWD – Deutscher Wetterdienst. Unwetterwarnungen des nationalen Wetterdienstes.
lhp LHP – Länderübergreifendes Hochwasser Portal. Länderübergreifende Hochwasserwarnungen.
police Polizeiliche Lagemeldungen.

Ressourcen & Endpoints

Die CLI bildet die Ressourcen der API ab. Diese Endpoints stellt der Client bereit:

map-data (/{source}/mapData.json). Die aktuellen Warnungen einer Quelle als Liste von Warnungszusammenfassungen (MapWarning[]). CLI: nina map-data <source>.

warning get (/warnings/{identifier}.json). Die vollständigen, aus CAP abgeleiteten Daten einer Warnung zu einer einzelnen Kennung. Sie sind tief verschachtelt und standardspezifisch und werden daher als unverändertes rohes JSON-Objekt zurückgegeben. CLI: nina warning get <identifier>. Eine Kennung, die nicht mehr aktuell ist (abgelaufen, aktualisiert, aufgehoben, vertippt oder nie ausgegeben), bekommt kein 404: Die API leitet sie auf /archive/alerts/{identifier}?contentType=json weiter, wo eine Warnung, die es einmal gab, als Archivkopie liegt. Die CLI meldet das als „not a live warning“ (Exit-Code 4) und nennt die Archiv-URL; eine beendete Warnung kann sie von einer vertippten Kennung nicht unterscheiden und behauptet daher keins von beiden. Kennungen unterscheiden Groß- und Kleinschreibung. Was beim Kopieren um eine Kennung herum mitkommt – Leerraum (ein Leerzeichen am Ende, ein CR aus einer CRLF-Datei, ein geschütztes Leerzeichen), unsichtbare Zeichen, Anführungszeichen, eine Endung .json/.geojson aus einer API-URL – wird vor der Anfrage entfernt (normalizeIdentifier), bei warning get/geojson wie bei archive get/mapping; Leerraum oder ein unsichtbares Zeichen innerhalb einer Kennung wird abgelehnt (Exit-Code 1, keine Anfrage).

warning geojson (/warnings/{identifier}.geojson). Die Geometrie des betroffenen Gebiets als GeoJSON (application/geo+json), zurückgegeben als rohe Bytes. CLI: nina warning geojson <identifier> (mit -o in eine Datei speichern).

dashboard (/dashboard/{ARS}.json). Alle Warnungen, die aktuell einen Kreis betreffen, adressiert über seinen Regionalschlüssel auf Kreisebene (siehe ARS unten). CLI: nina dashboard <ars>.

archive – MoWaS-Archiv. Frühere MoWaS-Warnungen und ihr Revisionsverlauf:

reference – statische Referenzdaten, die zusammen mit den Warnungen veröffentlicht werden:

Kennungen & Regionalschlüssel

identifier. Die opake ID einer einzelnen Warnung (z. B. eine MoWaS-ID mow.… aus der id eines map-data-Eintrags). Wird als Pfadargument für warning get/geojson und archive mapping/get verwendet. Der Client URL-codiert sie vor der Anfrage. Eine leere Kennung oder eine mit Pfadtrenner (/ oder \) kann nie zu einer echten ID passen; der Client weist sie deshalb vor jeder Anfrage zurück (identifierProblem; für Bibliotheksnutzer ein NinaValidationError, in der CLI Exit-Code 1).

ARS – Amtlicher Regionalschlüssel. Der 12-stellige Schlüssel einer deutschen Verwaltungseinheit (Land → Kreis → Gemeinde), mit dem der dashboard-Endpoint angesprochen wird (z. B. 055150000000).

AGS – Amtlicher Gemeindeschlüssel. Der kürzere (8-stellige) Gemeindeschlüssel. Der Endpoint dashboard akzeptiert ihn nicht (HTTP 400) und auch keinen ARS auf Gemeindeebene (HTTP 404): Er erwartet den ARS auf Kreisebene, also die ersten fünf Stellen gefolgt von 0000000. Die CLI prüft den Schlüssel vor dem Senden – alles außer 12 Ziffern mit sieben Nullen am Ende wird zurückgewiesen, mit dem Kreisschlüssel, wo er eindeutig ist – und weist außerdem einen Schlüssel auf Landesebene (Stellen 3–5 000, z. B. 050000000000, oder 000000000000) vor jeder Anfrage zurück: Die API beantwortet ihn mit [] und HTTP 200, auch wenn in einem Kreis dieses Landes eine Warnung aktiv ist – eine falsche Entwarnung. Hamburg (020000000000) und Berlin (110000000000) sind selbst ihr Kreis. Ein wohlgeformter Schlüssel, der keinen Kreis bezeichnet (ein Schlüssel eines Regierungsbezirks wie 051000000000, eine nicht vergebene Nummer), bekommt HTTP 404; die CLI meldet das als no such district key mit Exit-Code 4.

Begriffe der Warnungsdaten (CAP)

NINA-Warnungen sind aus CAP – dem Common Alerting Protocol abgeleitet, dem OASIS-Standard für den Austausch von Warnmeldungen. Die folgenden Felder kommen in der typisierten Warnungszusammenfassung (MapWarning) oder in den vollständigen Daten vor.

id / version. Die Kennung der Warnung und ihre monoton steigende Revisionsnummer.

startDate / expiresDate. Wann die Warnung in Kraft tritt und (bei Quellen, die das angeben) wann sie abläuft.

type (msgType). Der CAP-Meldungstyp eines Eintrags – Alert (neu), Update (ersetzt eine frühere Meldung) oder Cancel (zieht sie zurück). Das Archiv-Mapping schreibt ihn groß (ALERT, UPDATE).

Severity. Die CAP-Schwerestufe einer Warnung. Der vom Client bereitgestellte Wertebereich ist Minor, Moderate, Severe, Extreme, Unknown (in aufsteigender Schwere, dazu der Auffangwert Unknown).

i18nTitle / I18nText. Eine lokalisierte Titel-Map mit Sprachcodes als Schlüssel, z. B. { "de": "Hochwasser" }.

transKeys / event. Übersetzungsschlüssel in einer Zusammenfassung; event verweist auf einen Eintrag im Katalog der Ereigniscodes (siehe reference event-codes).

headline / sent. In Einträgen des Archivverlaufs (ArchiveMappingEntry) und des Dashboards (DashboardEntry): die menschenlesbare Überschrift und der Zeitpunkt, zu dem die Meldung versendet wurde.

API-Verhalten

Keine Authentifizierung. Jeder Endpoint ist ein offener, rein lesender GET; der Client sendet nie Zugangsdaten.

GeoJSON-Downloads. warning geojson fordert application/geo+json an und liefert rohe Bytes (RawResponse), statt sie zu parsen, sodass die Geometrie Byte für Byte unverändert in einer Datei (-o) oder Pipe ankommt. Auf einem Terminal werden Steuerzeichen maskiert (\uXXXX), damit der Inhalt keine Escape-Sequenzen an das Terminal schicken kann. Der Inhalt wird vorher geprüft: Ist er kein GeoJSON (JSON mit einem GeoJSON-type) – etwa eine HTML-Fehlerseite oder ein Fehlerobjekt mit HTTP 200 –, ist das ein Fehler (Exit-Code 1), und es wird nichts geschrieben.

Rate-Limiting / vorübergehende Fehler. Die API kann 429 (zu viele Anfragen) oder 503 (vorübergehend nicht verfügbar) liefern; der Client behandelt beide als wiederholbar (--max-retries), ebenso eine zurückgesetzte Verbindung. Jeder neue Versuch wartet linear länger (200 ms, 400 ms, …) oder den Retry-After der Antwort (Sekunden oder ein HTTP-Datum), wenn der länger ist – nie kürzer, sodass Retry-After: 0 keine Anfragesalve auslöst. Ein Retry-After über 30 s wird nicht wiederholt; der Fehler nennt die verlangte Wartezeit und wird sofort gemeldet.

Keine Weiterleitungen. Der Transport sendet genau eine Anfrage und folgt keinen 3xx-Weiterleitungen – eine Weiterleitung wird wie jeder andere Nicht-2xx-Status als Fehler gemeldet (mit dem Ziel aus Location); so werden Header nicht erneut an ein Weiterleitungsziel gesendet. Die eine Weiterleitung, die die API im normalen Betrieb schickt – eine nicht mehr aktuelle Warnungskennung, die auf ihr Archiv zeigt –, wird als „nicht gefunden“ gemeldet (Exit-Code 4).

Log-Eintrag (log record). Jede Diagnosezeile, die die CLI nach stderr schreibt: ein Zeitstempel, eine Stufe (ERROR, WARN, INFO) und ein Thema nina.<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, eine nicht mehr aktuelle Warnungskennung, die Content-Type-Warnung eines Downloads und eine fehlerhafte Antwort – ungültiges JSON, die falsche Form, ein unbekannter Zeichensatz), http (die Verbindung, die Klartext-Warnung und je Wiederholung eine WARN-Zeile vor dem Warten) und output (die -o-Datei, Schreibfehler auf stdout). Ein Eintrag ist immer eine Zeile; Steuerzeichen darin werden maskiert.

Exit-Codes

Was nina an die Shell zurückgibt, für Skripte:

Code Bedeutung
0 Erfolg – auch --help, --version und ein nina ohne Argumente (zeigt die Hilfe). Eine leere Liste ([]) ist ebenfalls ein Erfolg: keine aktiven Warnungen.
1 Jeder Fehler außer „nicht gefunden“: ein Netzwerkfehler oder Timeout, eine Antwort, die kein gültiges JSON ist, nicht die dokumentierte Form hat (ein HTTP 200 mit null, {} oder einem Fehlerobjekt, wo eine Liste von Warnungen stehen müsste – nie als „keine Warnungen“ gelesen) oder zu tief verschachtelt zum Ausgeben, ein API-Fehler außer 404 (auch ein 3xx, dem nicht gefolgt wird, und 429/503 nach den Wiederholungen), ein fehlgeschlagenes Schreiben mit -o sowie eine falsche Bedienung – eine Befehlsgruppe oder globale Optionen ohne Befehl (ein ERROR-Eintrag, dann die Hilfe), help für einen unbekannten Befehl, ein unbekannter Befehl oder eine unbekannte Option, ein ungültiger Optionswert oder ein Argument, das die CLI vor dem Senden zurückweist (ein fehlerhafter Regionalschlüssel oder einer auf Landesebene, eine unbekannte Quelle, eine Kennung mit Pfadtrenner).
4 Nicht gefunden: ein 404 der API (z. B. eine unbekannte Archivkennung oder ein Regionalschlüssel, der keinen Kreis bezeichnet – gemeldet als no such district key "<Schlüssel>") oder eine Warnungskennung, die nicht mehr aktuell ist und die die API auf ihr Archiv weiterleitet, statt 404 zu antworten.

Bibliothek & Interna. Begriffe zum TypeScript-Client und seinen Interna – NinaClient, Ressourcengruppen, die Request-Engine, Transport, Retry/Backoff, Fehlertypen, Query-Builder – stehen jetzt in DEVELOPING.md.

Quelle auf GitHub ansehen →