Glossary

A reference for the domain concepts and project-specific terms used throughout luftqualitaet-cli. The underlying API is German (Umweltbundesamt); this glossary gives the term used in the CLI/client alongside the original German where one exists.

Translation table (from the API). The CLI follows these:

German English / API term

Luftqualität air quality

Komponente / Schadstoff component / pollutant

Messnetz network

Messumfang / Scope scope

Station / Messstation station

Stationstyp station type

Stationseinstellung station setting

Überschreitung transgression / exceedance

Jahresbilanz annual balance

Grenzwert / Schwellenwert threshold

Messwert measure / measurement

Stundenwert hourly value

German	English / API term
Luftqualität	air quality
Komponente / Schadstoff	component / pollutant
Messnetz	network
Messumfang / Scope	scope
Station / Messstation	station
Stationstyp	station type
Stationseinstellung	station setting
Überschreitung	transgression / exceedance
Jahresbilanz	annual balance
Grenzwert / Schwellenwert	threshold
Messwert	measure / measurement
Stundenwert	hourly value

The data source

Umweltbundesamt (UBA). The German Federal Environment Agency (umweltbundesamt.de). It collects and publishes the official German air-quality data this tool wraps.

Air Data API. The UBA’s open, key-free REST API for air-quality data. This client targets the live API path /api/air_data/v3 on https://www.umweltbundesamt.de (the default base URL). It supersedes the v2 OpenAPI spec published at luftqualitaet.api.bund.dev.

Index + data structure. The shape of most API responses: an indices array names the columns (the row layout), and the payload is a compact map keyed by id/code/timestamp rather than an array of labelled objects. The client returns these payloads faithfully as raw JSON (JsonObject / AirDataResult) rather than guessing a strict per-endpoint type, because the layout varies by endpoint and parameters.

Resources / endpoints

The client surfaces two kinds of endpoint: data endpoints (measurements and aggregations for a station/window or component/year) and reference endpoints (the lookup lists that give meaning to the numeric ids).

airquality (/airquality/json). Air-quality index data for one station over a time window. The index has five levels, 0 (very good) to 4 (very poor). CLI: airquality.

airquality-limits (/airquality/limits). The available date range per station for air-quality data — use it to discover what windows you can request. CLI: airquality-limits.

measures (/measures/json). Raw measurement data for a station over a window, optionally narrowed to one component and/or scope. CLI: measures.

measures-limits (/measures/limits). The available date range per scope/component/station for measurements. CLI: measures-limits.

annual-balances (/annualbalances/json). Annual tabulations (Jahresbilanzen) for a component and a given year (>= 2016). Each row is a station id followed by figures whose number and meaning depend on the component (for O₃ there is no annual mean); the response’s headers object names them by row position, and its indices array does not match the rows. CLI: annual-balances.

transgressions (/transgressions/json). Exceedance (Überschreitungen) data for a component and year — how often a limit value was exceeded. The response’s headers object says what the yearly count measures (hours or days above which value); day_recent shows how far the year’s data reaches. CLI: transgressions.

thresholds (/thresholds/json). The limit/threshold values for a given use (airquality or measure), optionally per component and scope. CLI: thresholds.

meta (/meta/json). Combined metadata for a use — bundles components, scopes, networks, stations, etc. needed to build other queries. CLI: meta.

Reference lists

components (/components/json). The measured components (pollutants): e.g. PM10, NO₂, O₃, SO₂, CO. CLI: components. Each row carries an id, a code and the unit of measurement.

networks (/networks/json). The measurement networks (Messnetze) — the federal-state and federal monitoring networks that operate the stations. CLI: networks.

scopes (/scopes/json). The measurement scopes (Messumfänge) — the aggregation/averaging definition of a measurement (e.g. hourly average, 24-hour average, the averaging time + the component it applies to). CLI: scopes.

station-types (/stationtypes/json). The station-type classification (e.g. background, traffic, industrial). CLI: station-types.

station-settings (/stationsettings/json). The station-setting classification describing a station’s surroundings (e.g. urban, suburban, rural). CLI: station-settings.

transgression-types (/transgressiontypes/json). The catalogue of exceedance types referenced by the transgressions data. CLI: transgression-types.

Key identifiers & query parameters

station. The numeric station id identifying a monitoring station. A required parameter of airquality and measures. Station ids are 1-based, so the CLI rejects 0 locally. Discover ids via meta / airquality-limits / measures-limits.

component. The numeric component id identifying a pollutant. Required by annual-balances / transgressions; optional on measures / thresholds. Resolve the id ↔ pollutant mapping via components.

scope. The numeric scope id identifying a measurement scope (averaging definition). Optional on measures / thresholds. Resolve via scopes.

year. A four-digit year for the annual aggregations; the API’s earliest year is 2016, so the CLI rejects anything below that.

Time window (date_from / time_from / date_to / time_to). The data endpoints address a window by a start date+hour and an end date+hour. Dates are YYYY-MM-DD. Hours are hour-ending values in the range 1..24 (not 0..23): hour 1 is the interval ending at 01:00, hour 24 ends at midnight. Times are CET (UTC+1) all year, as the airquality response labels them, so in summer they are one hour behind German local time. The CLI validates the calendar date, the hour range, and rejects a reversed window (start after end) before any request is sent.

Enums / codes surfaced by the client

These are the closed value sets the client validates against (defined in src/client/enums.ts):

lang (Lang). Response language for the labels in reference lists and metadata: de | en. CLI: --lang.

index (IndexKind). How a reference list is keyed in the response: id (the numeric id) | code (the short code). CLI: --index.

use (meta) (MetaUse). Which metadata bundle the meta endpoint returns: airquality | measure | transgression | annualbalance | map. When use=airquality, a time window (--date-from + --date-to) is required. CLI: meta --use.

use (thresholds) (ThresholdUse). Which threshold set the thresholds endpoint returns: airquality | measure. CLI: thresholds --use.

Search & API concepts

Retry / backoff. The API rate-limits and can return transient 429 / 503 responses; the engine retries those automatically with linear backoff (--max-retries, default 2).

Redirects. The engine follows up to 5 HTTP redirects by default (configurable with --max-redirects; 0 disables following). On a cross-origin redirect it strips request headers (re-adding only the benign Accept / User-Agent) so nothing sensitive leaks to a different origin.

Response size cap (maxResponseBytes). A hard cap on response body size (default 100 MiB; 0 = unlimited) that defends against memory exhaustion from a hostile or buggy endpoint. CLI: --max-response-bytes.

Read-only, no auth. The UBA Air Data API needs no API key; this client implements only the open, read-only GET endpoints.

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