Glossary

A reference for the domain concepts and project-specific terms used throughout reisewarnungen-cli. The domain (German foreign-office travel advice) is German; this glossary gives the English term used in the CLI/client alongside the original German where one exists.

Translation table. The CLI/client follows these:

German	English / client term
Reisewarnung	(full) travel warning
Teilreisewarnung	partial / regional warning
Reise- und Sicherheitshinweise	travel and safety advice
Auswärtiges Amt	Federal Foreign Office
Land	country
Inhalt	content

The API and its publisher

Auswärtiges Amt (AA) — Federal Foreign Office. The German federal ministry for foreign affairs. It issues the official travel and safety advice this tool reads. Web home and data host: auswaertiges-amt.de.

Travel-warning open-data API. The open, no-authentication endpoint published by the AA at https://www.auswaertiges-amt.de/opendata/travelwarning. It returns the AA’s per-country travel and safety advice as JSON. Read-only (GET); no API key is required. This is the only API the tool wraps; DEFAULT_BASE_URL is https://www.auswaertiges-amt.de and the resource path is /opendata/travelwarning.

Reise- und Sicherheitshinweise (travel and safety advice). The AA’s country-by-country guidance for travellers: entry rules, security situation, health, and — where the situation warrants — an explicit warning. The advice text is delivered as HTML in the content field.

Endpoints / resources

List endpoint (GET /opendata/travelwarning). Returns all countries at once as a map of content id -> country summary, plus envelope members. The per-country summaries here do not include the HTML content. CLI: list (raw) and countries (flattened).

Single-warning endpoint (GET /opendata/travelwarning/{contentId}). Returns one country’s full advice, with the HTML content populated. CLI: get.

Response shape

response envelope. Every API response is wrapped in a top-level response object. The client unwraps it: list() returns response; a 200 whose body lacks the response envelope is surfaced as a ReiseParseError rather than masked as an empty success.

lastModified. An envelope member (a Unix-epoch timestamp, in seconds) carried alongside the country entries — nominally when the dataset was last changed, but it lags far behind the entries’ own lastModified values (1757063288, 2025-09-05, when checked on 2026-09-15). It is not a country, so summaries() skips it when flattening.

contentList. An envelope member: an array of all content ids the upstream includes alongside the per-country summaries. Also not a country, so summaries() skips it.

TravelWarning. One country’s entry. Fields the client surfaces: title, countryCode, iso3CountryCode, countryName, the four boolean warning flags (below), lastModified, effective, lastChanges, content (HTML, single endpoint only), and disclaimer.

CountryEntry. A TravelWarning augmented with its id (the content id), produced by summaries() — the flattened, array-shaped view of the list.

Identifiers & codes

content id (contentId). The numeric-string key under which a country’s entry is stored in the response map (e.g. 226768). It is the id field on a CountryEntry and the required argument to get <contentId>. It is not an ISO country code. An empty content id is rejected as a usage error rather than sent upstream.

countryCode. The ISO 3166-1 alpha-2 (two-letter) country code, e.g. TH, JO. Kosovo, which has no official ISO code, uses XK.

iso3CountryCode. The ISO 3166-1 alpha-3 (three-letter) country code, e.g. DEU, FRA.

countryName. The human-readable country name (German).

Warning flags

The four boolean fields the client surfaces, in increasing specificity. A country counts as “warned” (the countries --warned-only filter) if any of them is true.

warning. A full travel warning (Reisewarnung) is in force for the whole country — the AA’s strongest advice against travel.

partialWarning. A partial/regional warning (Teilreisewarnung) is in force — the warning applies to specific regions rather than the whole country.

situationWarning. A situation-specific warning is in force (tied to a particular event or circumstance).

situationPartWarning. A situation-specific partial warning — situational and limited to part of the country.

Other entry fields

title. The advice document’s title.

effective. A Unix-epoch timestamp (seconds): when the current advice took effect. Each entry’s own lastModified uses the same unit.

lastChanges. A short, human-readable note describing what changed in the latest revision of the advice.

content. The full advice text as HTML. Present only on the single-warning endpoint, so it appears on get results, not on list / countries.

disclaimer. The AA’s standard legal disclaimer text accompanying the advice.

API & transport concepts

Read-only, no auth. The endpoint serves data over GET with no key, token or login. The client only reads; it issues no writes.

Retry / backoff. Transient 429 (rate limited) and 503 responses are retried automatically with linear backoff (--max-retries, default 2; base delay grows with each attempt).

Redirects. The engine follows up to maxRedirects (default 5) HTTP redirects (301/302/303/307/308), resolving Location relative to the current URL. On a cross-origin redirect it strips sensitive headers (Authorization, Cookie, X-API-Key, Proxy-Authorization, WWW-Authenticate) so credentials are never leaked to another host.

maxResponseBytes. A hard cap on the response body size (default 100 MiB; 0 disables it) that aborts the request if exceeded, defending against memory exhaustion from a hostile or buggy endpoint.

Sole-entry tolerance. On get, the single-warning endpoint normally keys its one entry under the requested content id. As a tolerance for that key ever differing, a sole non-lastModified object entry is accepted as the result; but an ambiguous (multi-entry) or empty response is treated as not found rather than risk returning a different country than requested.

Library & internals. Terms for the TypeScript client and its internals — ReisewarnungenClient, the request engine, transport, retry/backoff, error types, sole-entry tolerance — now live in DEVELOPING.md.