# Glossary A reference for the domain concepts and project-specific terms used throughout `autobahn-cli`. The API is the **open Autobahn App API** (`verkehr.autobahn.de`), operated by **Autobahn GmbH des Bundes**, which carries the live data behind the official Autobahn app. The domain is German motorways; this glossary gives the English term used in the CLI/client alongside the original German where one applies. --- ## The API & operator **Autobahn App API.** The open, read-only REST API at `verkehr.autobahn.de` (documented community-side at `autobahn.api.bund.dev`). It exposes live traffic data along the German federal motorway network. All endpoints this tool uses live under the `/o/autobahn` API root and require **no authentication and no API key**. **Autobahn GmbH (des Bundes).** The federally owned company that operates and maintains Germany's *Bundesautobahnen* (federal motorways) and publishes this API. **API root (`/o/autobahn`).** The common path prefix under the base URL for every endpoint: the motorway list (`/o/autobahn/`), the per-motorway service listings (`/o/autobahn/{roadId}/services/{service}`) and the detail endpoints (`/o/autobahn/details/{service}/{identifier}`). --- ## Core resources **Autobahn / motorway (`roadId`).** A German federal motorway, identified by its designation such as `A1`, `A2`, `A99`. `GET /o/autobahn/` returns the full list of motorways the API knows about (the `roads` array). CLI: `roads`. The `roadId` is the required path segment for every service `list` command. **Roadworks (`roadworks`).** Active or planned construction/maintenance works along a motorway (German *Baustellen*). CLI: `roadworks`. **Webcam (`webcam`).** A traffic camera along a motorway; items carry an `imageurl` (the snapshot) and a `linkurl`. CLI: `webcams`. **Parking lorry / lorry parking (`parking_lorry`).** Truck/HGV parking areas along a motorway (German *Lkw-Parkplätze / Rastplätze*) and their occupancy information. CLI: `parking`. **Warning (`warning`).** A traffic warning along a motorway (German *Verkehrsmeldung* / *Verkehrswarnung*) — e.g. congestion, accidents, hazards. CLI: `warnings`. **Closure (`closure`).** A full or partial road closure along a motorway (German *Sperrung*). CLI: `closures`. **Electric charging station (`electric_charging_station`).** An EV charging point along a motorway (German *E-Ladestation*), with connector/operator metadata. CLI: `charging`. > The six service resources — roadworks, webcams, parking, warnings, closures, > charging — are **structurally identical**: each supports `list ` and > `get `. Internally one generic `ServiceResource` serves all six. --- ## Identifiers & request shape **`roadId`.** The motorway designation used as a path segment, e.g. `A1`. Taken from the `roads` command. The upstream API itself emits a few ids with a trailing space next to their trimmed twin (e.g. `"A60"` and `"A60 "`), so the client trims surrounding whitespace before use, and the `roads` command trims and de-duplicates the list it prints. **`identifier`.** The opaque id of a single service item, present as the `identifier` field on every listed item. It is the value you pass to a `get ` command (or `resource.get(...)`) to fetch that one item's full detail payload. Its format varies by service: roadworks, warnings and closures use plain strings (`2026-006680--vi-fbm.…`), parking uses ids like `DE-SL-000031`, and charging uses a numeric id for Deutschlandnetz sites (`30388`) and a base64 id for all others (`RUxFQ1RSSUNfQ0hBUkdJTkdfU1RBVElPTl9fMTkyMzE=`). **Service listing.** The two-step access pattern of the API: `list(roadId)` returns the array of items for a service along a motorway; `get(identifier)` then fetches one item's full details by its identifier. **Listing envelope.** A service-listing response is a JSON object that wraps its array under a single key named after the service — `{ "roadworks": [...] }`, `{ "webcam": [...] }`, `{ "parking_lorry": [...] }`, `{ "warning": [...] }`, `{ "closure": [...] }`, `{ "electric_charging_station": [...] }`. The client unwraps this key and returns the bare array (an empty array when the key is missing). --- ## Item fields Every listed item shares one loosely specified shape (`AutobahnServiceItem`); the API populates a different subset of fields per service type. **`identifier`.** Opaque id of the item (see above). **`title` / `subtitle`.** Short human-readable labels for the item. On lorry parking the upstream `title` is broken (`A8 | undefined`); the area name is in `subtitle`. **`description`.** An array of descriptive text lines. **`point`.** A single geographic position serialised as a string. The order varies by service: `"lat,long"` for roadworks, warnings and closures, `"long,lat"` for charging. Lorry parking has `point: null`. **`coordinate`.** A geographic point as a structured object. Its shape varies by service: `{ lat, long }` with JSON numbers for roadworks, warnings and closures; the same keys as stringified decimals for charging; and a GeoJSON Point `{ "type": "Point", "coordinates": [long, lat] }` with no `lat`/`long` keys for lorry parking. **`geometry`.** A GeoJSON `LineString` of the affected stretch, already in `[long, lat]` order, on roadworks, warnings and closures. **`extent`.** A bounding extent for the item (e.g. the span a roadworks covers). **`isBlocked`.** A string flag indicating whether the segment/item is blocked. **`future`.** Boolean — whether the item refers to a future (not yet active) event, e.g. planned roadworks. **`startTimestamp`.** When the event/item starts. **`display_type`.** A type/category hint the app uses to render the item. **`icon`, `footer`, `routeRecommendation`.** Display metadata: an icon key, footer text lines, and any recommended-route lines. **`imageurl` / `linkurl` (webcams).** The camera snapshot URL and a link URL. **`operator` (charging/webcams).** The operating organisation for the item. **Detail payload.** The single-item response from a `get` is returned as a faithful raw `JsonObject` (`RoadworkDetail`, `WebcamDetail`, … are all aliases of `JsonObject`) rather than a partially-guessed type, because the detail shape varies and is not fully specified. --- ## Behaviour, errors & limits **Empty-body 404.** The detail endpoint answers an **unknown identifier with HTTP 200 and an empty body** rather than a `404`. The client treats an empty (or whitespace-only) body as not-found and raises a synthetic `404` `AutobahnApiError` (CLI exit code `4`), instead of a misleading JSON parse error. **Empty list vs not-found.** A `list ` that matches no items is **not** an error: it returns `[]` (exit `0`). Only a `get ` with no matching item, or a real `404`, is treated as not-found (exit `4`). **Retryable status.** `429` (rate-limited) and `503` (service unavailable) are the statuses the API documents as transient. The engine retries them automatically up to `maxRetries` (default `2`), honouring a `Retry-After` header when present, otherwise using linear backoff. `AutobahnApiError.isRetryable` reflects this. **`Retry-After`.** A response header the engine parses for both the delta-seconds form (`Retry-After: 120`) and the HTTP-date form (`Retry-After: Wed, 21 Oct 2025 07:28:00 GMT`) to decide how long to wait before a retry. The resulting delay is clamped to a 30s ceiling so a pathological or hostile value cannot hang the CLI for hours. **Redirects not followed.** A `3xx` response surfaces as an error rather than being chased to another host (a deliberate safety choice, since `--base-url` is trusted input). **`maxResponseBytes`.** A hard cap on response body size (default 100 MiB; `0` disables) that defends against memory exhaustion from a hostile or buggy endpoint. **Exit codes.** `0` success (incl. `--help`/`--version`); `4` not-found (`404` or an unmatched `get`); `1` any other API/network/parse error and usage errors. --- > **Library & internals.** Terms for the TypeScript client and its internals — > `AutobahnClient`, the request engine, transport, retry/backoff, error types, > query builder, DI seams — now live in **[DEVELOPING.md](DEVELOPING.md)**.