Glossary

A reference for the domain concepts and project-specific terms used throughout nina-warnungen-cli. The NINA domain is German civil protection; this glossary gives the term used in the CLI/API alongside the original German where one exists.

NINA & the operator

NINA — Notfall-Informations- und Nachrichten-App. The German federal emergency information and news app for the public. The same warning data that powers the app is published through the open REST API this tool wraps.

warnung.bund.de. The public warning portal and the host of the open API (base URL https://warnung.bund.de, path prefix /api31). No authentication or API key is required; every endpoint is a read-only GET.

BBK — Bundesamt für Bevölkerungsschutz und Katastrophenhilfe. The Federal Office of Civil Protection and Disaster Assistance, which operates NINA and the warning infrastructure.

Warning sources

NINA aggregates several independent warning “providers”, each published as its own mapData.json listing. The CLI exposes the valid set via nina sources, and nina map-data <source> fetches the current warnings from one of them.

Source (NinaSource). One of the aggregated providers. The valid values are:

Source Meaning
mowas MoWaS — Modulares Warnsystem. The Bund/Länder modular civil-protection alerting system.
katwarn KATWARN. Municipal/regional alerting service.
biwapp BIWAPP — Bürger-Info- und Warn-App. Municipal alerting service.
dwd DWD — Deutscher Wetterdienst. Severe-weather warnings from the national meteorological service.
lhp LHP — Länderübergreifendes Hochwasser Portal. Cross-state flood warnings.
police Police incident reports.

Resources & endpoints

The CLI mirrors the API’s resources. The endpoints the client surfaces:

map-data (/{source}/mapData.json). The current warnings from one source, as a list of warning summaries (MapWarning[]). CLI: nina map-data <source>.

warning get (/warnings/{identifier}.json). The full, CAP-derived warning payload for a single identifier. Deeply nested and standard-specific, so it is returned as a faithful raw JSON object. CLI: nina warning get <identifier>. An identifier that is not live (expired, updated, cancelled, mistyped, or never issued) gets no 404: the API redirects it to /archive/alerts/{identifier}?contentType=json, where a warning that once existed has an archived copy. The CLI reports that as “not a live warning” (exit 4), naming the archive URL; it cannot tell an ended warning from a mistyped id, so it says neither. Identifiers are case-sensitive. What a copy-paste adds around an id — whitespace (a trailing space, a CR from a CRLF file, a non-breaking space), invisible characters, quotes, a .json/.geojson suffix from an API URL — is dropped before the request (normalizeIdentifier), for warning get/geojson and archive get/mapping alike; whitespace or an invisible character inside an id is refused (exit 1, no request).

warning geojson (/warnings/{identifier}.geojson). The warning’s affected-area geometry as GeoJSON (application/geo+json), returned as raw bytes. CLI: nina warning geojson <identifier> (use -o to save to a file).

dashboard (/dashboard/{ARS}.json). All warnings currently affecting a district, keyed by its district-level regional key (see ARS below). CLI: nina dashboard <ars>.

archive — MoWaS archive. Historical MoWaS warnings and their revision history:

reference — static reference data published alongside the warnings:

Identifiers & region keys

identifier. The opaque id of a single warning (e.g. a mow.… MoWaS id from a map-data entry’s id). Used as the path argument to warning get/geojson and archive mapping/get. It is URL-encoded by the client before the request. A blank identifier or one with a path separator (/ or \) can never match a real id, so the client refuses it before any request (identifierProblem; a NinaValidationError for library callers, exit 1 on the CLI).

ARS — Amtlicher Regionalschlüssel (“official regional key”). The 12-digit key identifying a German administrative region (state → district → municipality), used to address the dashboard endpoint (e.g. 055150000000).

AGS — Amtlicher Gemeindeschlüssel (“official municipality key”). The shorter (8-digit) municipality key. The dashboard endpoint does not accept it (HTTP 400), and it takes no municipality-level ARS either (HTTP 404): it wants the district-level ARS, i.e. the first five digits followed by 0000000. The CLI checks the key before sending — anything but 12 digits with the last seven 0 is refused, naming the district key where it is clear — and it also refuses a state-level key (digits 3–5 000, e.g. 050000000000, or 000000000000) before any request: the API answers those with [] and HTTP 200 even while a district in that state has warnings, a false all-clear. Hamburg (020000000000) and Berlin (110000000000) are their own district. A well-formed key that names no district (a Regierungsbezirk key such as 051000000000, an unassigned number) gets HTTP 404, reported as no such district key with exit code 4.

Warning payload concepts (CAP)

NINA warnings are derived from CAP — the Common Alerting Protocol, the OASIS standard for exchanging emergency alerts. The fields below appear on the typed warning summary (MapWarning) or in the full payload.

id / version. The warning’s identifier and its monotonically increasing revision number.

startDate / expiresDate. When the warning takes effect and (for sources that carry it) when it expires.

type (msgType). The CAP message type of an entry — Alert (new), Update (supersedes a prior message) or Cancel (withdraws it). The archive mapping spells it in upper case (ALERT, UPDATE).

Severity. The CAP severity level of a warning. The value set surfaced by the client is Minor, Moderate, Severe, Extreme, Unknown (in increasing order of severity, plus the catch-all Unknown).

i18nTitle / I18nText. A localised title map keyed by language code, e.g. { "de": "Hochwasser" }.

transKeys / event. Translation keys carried on a summary; event references an entry in the event-code catalogue (see reference event-codes).

headline / sent. On archive history (ArchiveMappingEntry) and dashboard (DashboardEntry) records: the human-readable headline and the time the message was sent.

API behaviour

No authentication. Every endpoint is an open, read-only GET; the client never sends credentials.

GeoJSON downloads. warning geojson requests application/geo+json and returns raw bytes (RawResponse) rather than parsing them, so the geometry is delivered byte-for-byte to a file (-o) or a pipe. Printed on a terminal, control characters are escaped (\uXXXX) so the body cannot send escape sequences to it. The body is checked first: one that isn’t GeoJSON (JSON with a GeoJSON type) — an HTML error page or an error object answered with HTTP 200 — is an error (exit 1), and nothing is written.

Rate limiting / transient errors. The API may return 429 (too many requests) or 503 (temporarily unavailable); the client treats both as retryable (--max-retries), as is a connection that was reset. Each retry backs off linearly (200 ms, 400 ms, …), or waits the response’s Retry-After (delay-seconds or an HTTP date) when that is longer — never less, so Retry-After: 0 does not cause a burst. A Retry-After above 30 s is not retried and the error, naming the requested wait, is reported at once.

No redirect following. The transport issues exactly one request and does not follow 3xx redirects — a redirect is surfaced as an error like any other non-2xx status (naming the Location target), avoiding header replay to a redirect target. The one redirect the API sends in normal use, a warning id that is no longer live pointing to its archive, is reported as not found (exit 4).

Log record. Every diagnostic line the CLI writes to stderr: a timestamp, a level (ERROR, WARN, INFO) and a topic nina.<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, a warning id that is no longer live, the content-type warning of a download, and a malformed answer — bad JSON, the wrong shape, an unknown charset), http (the connection, the cleartext warning, and one WARN per retry before it waits) and output (the -o file, stdout failures). A record is always one line; control characters in it are escaped.

Exit codes

What nina returns to the shell, for scripts:

Code Meaning
0 Success — also --help, --version, and a bare nina with no arguments (which prints its help). An empty list ([]) is a success too: no active warnings.
1 Any error other than “not found”: a network failure or timeout, a response that is not valid JSON, not the documented shape (an HTTP 200 with null, {} or an error object where a list of warnings belongs — never read as “no warnings”) or is nested too deeply to print, an API error other than 404 (including a 3xx, which is not followed, and 429/503 after the retries), a failed -o write, and bad usage — a command group or global options without a command (an ERROR record, then the help), help for an unknown command, an unknown command or option, an invalid option value, or an argument the CLI refuses before sending (a malformed or state-level region key, an unknown source, an identifier with a path separator).
4 Not found: an API 404 (e.g. an unknown archive identifier, or a region key that names no district — reported as no such district key "<key>"), or a warning identifier that is no longer live, which the API redirects to its archive instead of answering 404.

Library & internals. Terms for the TypeScript client and its internals — NinaClient, resource groups, the request engine, transport, retry/backoff, error types, query builder — now live in DEVELOPING.md.

View the source on GitHub →