Glossar
Ein Nachschlagewerk für die Fachbegriffe und projektspezifischen Begriffe, die in
strahlenschutz-cli vorkommen. Das Fachgebiet ist das deutsche Messnetz zur
Strahlenüberwachung; dieses Glossar nennt neben dem deutschen Originalbegriff den in CLI/API
verwendeten Begriff (sofern es einen gibt).
Übersetzungstabelle. Die CLI verwendet diese Entsprechungen:
Deutsch Englisch / API-Begriff Ortsdosisleistung (ODL) ambient gamma dose rate Messstelle / Sonde measurement station / probe Kennung (kenn) station id Bundesamt für Strahlenschutz (BfS) Federal Office for Radiation Protection Zeitreihe time series
Das Messprogramm
Strahlenschutz. Das Politikfeld, dem diese API dient – die Überwachung der Umweltradioaktivität zum Schutz der Bevölkerung.
BfS – Bundesamt für Strahlenschutz. Die Bundesbehörde, die das bundesweite Messnetz für die Gamma-Ortsdosisleistung betreibt und dessen Messwerte als Open Data veröffentlicht.
ODL-Info. Das öffentliche Angebot des BfS (odlinfo.bfs.de),
das die Daten zur Gamma-Ortsdosisleistung für die Öffentlichkeit aufbereitet; dahinter steht der
Open-Data-Endpoint, den dieses Tool einbindet.
IMIS – Integriertes Mess- und Informationssystem. Das System zur Überwachung der
Umweltradioaktivität in Deutschland. Der Open-Data-Dienst läuft unter imis.bfs.de.
Was gemessen wird
ODL – Ortsdosisleistung. Die Messgröße dieses Messnetzes: die Dosisleistung der Gammastrahlung an einem Ort, also wie viel ionisierende Gammastrahlung pro Zeiteinheit vorhanden ist. Angegeben je Messstelle.
µSv/h (Mikrosievert pro Stunde). Die Einheit, in der die Gamma-Ortsdosisleistung angegeben wird. Das Sievert (Sv) ist die SI-Einheit der Äquivalentdosis; bei normaler Untergrundstrahlung liegen die Messwerte bei einem Bruchteil eines Mikrosieverts pro Stunde.
Messwert. Ein einzelner ODL-Wert einer Messstelle zu einem Zeitpunkt, enthalten in den
properties eines GeoJSON-Features.
Messstellen & Geografie
Messstelle / Sonde. Ein fest installierter Sensor im Messnetz des BfS, der die Gamma-Ortsdosisleistung vor Ort misst. Rund 1.700 Sonden decken Deutschland ab.
kenn (Messstellen-ID). Die Kennung der Messstelle. Eine numerische Zeichenkette mit
festem Format (nur Ziffern), z. B. 091811461. Der Client entfernt umgebende Leerzeichen und
prüft dann das Format (nur Ziffern, nicht leer), bevor er sie in den WFS-CQL_FILTER einsetzt (kenn='<id>'), und prüft, dass jedes Feature
der Antwort diese kenn trägt (ein Server, der den Filter weglässt, ist ein Fehler, keine
Daten einer anderen Messstelle). CLI: station <kenn>, --station <kenn>,
timeseries <kenn>.
GeoJSON-Feature. Ein Element der Antwort: eine Messstelle mit ihrem Messwert, mit einer
geometry (meist ein Point mit [lon, lat]-Koordinaten) und einem properties-Objekt, das die
Metadaten der Messstelle und den ODL-Wert enthält. Die Koordinaten kommen ungeprüft so, wie das
BfS sie speichert: Am 5. Okt. 2026 hatte eine defekt-Messstelle (Trollenhagen, 130711451)
[589.28, 3007.11]. Echte Messstellen liegen etwa bei Länge 5,5–15,5 und Breite 47–55,5;
vor dem Kartieren prüfen.
FeatureCollection. Eine WFS-GetFeature-Antwort als GeoJSON: eine Hülle
type: "FeatureCollection" mit einem Array features, dazu optional die Felder
totalFeatures, numberReturned und timeStamp.
Feature-Arten (Ressourcen)
Der Dienst veröffentlicht drei WFS-Feature-Typen, die Client und CLI als verständliche
„Feature-Arten“ bereitstellen und ihrem WFS-typeName zuordnen:
latest. Der jeweils neueste ODL-Messwert je Messstelle.
WFS-typeName: opendata:odlinfo_odl_1h_latest. CLI: latest, station.
ts-1h (stündliche Zeitreihe). Die ODL-Zeitreihe einer Messstelle aus Stundenmittelwerten.
WFS-typeName: opendata:odlinfo_timeseries_odl_1h. CLI:
timeseries --resolution ts-1h (Standard).
ts-24h (tägliche Zeitreihe). Die ODL-Zeitreihe einer Messstelle aus Tagesmittelwerten.
WFS-typeName: opendata:odlinfo_timeseries_odl_24h. CLI:
timeseries --resolution ts-24h. Der Layer enthält derzeit nur eine Messstelle, Flensburg
(010010001, etwa ein Jahr Tageswerte; Stand 26.09.2026); für jede andere Messstelle kommt
eine leere Collection zurück.
Diese Werte bilden das const-Array FeatureKindValues; die Map TYPE_NAMES (beide exportiert)
übersetzt jede Feature-Art in ihren WFS-typeName. Die beiden Zeitreihen-Arten sind zusätzlich
als TimeseriesResolutionValues exportiert. Die Bibliothek prüft jede Art vor jeder Anfrage
gegen diese Listen: getFeature() lehnt alles außerhalb von FeatureKindValues ab,
timeseries() (CLI: --resolution) alles außerhalb von TimeseriesResolutionValues, auch
latest, jeweils mit einem StrahlValidationError.
Die WFS-Schnittstelle
WFS – Web Feature Service. Der OGC-Standard, den der Open-Data-Endpoint des BfS spricht (Version 2.0). Der Client setzt die immer gleichen Standardparameter selbst, sodass Aufrufer sie nie von Hand angeben müssen.
OGC – Open Geospatial Consortium. Das Standardisierungsgremium hinter WFS. (GeoJSON ist kein OGC-Standard, sondern von der IETF in RFC 7946 festgelegt.)
ows-Endpoint. Der einzige Dienstpfad, den der Client anspricht:
/ogc/opendata/ows auf https://www.imis.bfs.de.
GetFeature. Die WFS-Operation, die Features abruft. Der Client sendet bei jedem Aufruf die
festen Parameter service=WFS, request=GetFeature und
outputFormat=application/json.
typeName. Der WFS-Parameter, der den abzurufenden Feature-Typ benennt (z. B.
opendata:odlinfo_odl_1h_latest); er wird über TYPE_NAMES aus der gewählten Feature-Art
gesetzt.
CQL_FILTER. Der OGC-CQL-Filterausdruck, der serverseitig angewendet wird. Die Filterung nach
Messstelle wird als CQL_FILTER=kenn='<id>' ausgedrückt. (Die frühere Form viewparams=kenn:<id>
ignoriert dieser Server beim Typ latest stillschweigend, deshalb wird sie nicht verwendet.)
count. Der WFS-2.0-Parameter zur Begrenzung der Ergebnisanzahl (--max in der CLI). Das
maxFeatures aus WFS 1.x ignoriert dieser Server stillschweigend, deshalb sendet der Client
immer count.
startIndex. Der Paginierungs-Offset in WFS 2.0 (--start in der CLI). Die BfS-Layer
haben keinen Primärschlüssel, deshalb kann der Server nur ein sortiertes Ergebnis
blättern: Ein startIndex ohne sortBy wird mit HTTP 400 abgelehnt („Cannot do natural
order without a primary key“). Der Client sendet deshalb immer ein sortBy (siehe unten).
Ohne count (--max) liefert der Server alles ab dem Offset.
sortBy. Der WFS-Parameter, der die Eigenschaft bestimmt, nach der sortiert wird; für
absteigende Reihenfolge hängen Sie ` D an (mit Leerzeichen, z. B. end_measure D), mehrere
Schlüssel trennen Sie mit Kommas (end_measure D,kenn) (CLI: –sort
outputFormat. Fest auf application/json gesetzt, damit jede Antwort GeoJSON ist.
ExceptionReport. Das OGC-XML-Dokument, mit dem der WFS eine fehlerhafte Anfrage beantwortet
(meist HTTP 400, bei manchen Fehlern HTTP 200), z. B. bei einer unbekannten Eigenschaft in
--sort. Die CLI zeigt seinen ExceptionText hinter dem Status an:
ERROR [strahlenschutz.api] HTTP 400 for GET …: Illegal property name: bogus_prop for feature type …
(Exit-Code 1); ein Bericht mit 200 lautet WFS exception (HTTP 200) for GET ….
Log-Eintrag. Jede Diagnosezeile, die die CLI auf stderr schreibt: ein Zeitstempel,
eine Stufe (ERROR, WARN, INFO) und ein Thema strahlenschutz.<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 oder ein ExceptionReport, eine unbekannte Messstelle,
und eine fehlerhafte Antwort – kein JSON, keine FeatureCollection, ein unbekannter
Zeichensatz, Features einer anderen Messstelle als der angefragten), http (die
Verbindung, die Warnung vor unverschlüsseltem http: und je Wiederholung eine WARN-Zeile vor dem Warten) und output (ein
fehlgeschlagenes Schreiben auf stdout). Ein Eintrag ist immer eine Zeile; Steuerzeichen
darin werden maskiert.
Abfrageoptionen des Clients
FeatureQuery. Das Abfrageobjekt, das die Methoden des Clients entgegennehmen:
station (→ CQL_FILTER=kenn='<id>'), sortBy, maxFeatures (→ count) und
startIndex.
maxFeatures (--max). Höchstzahl der zurückzugebenden Features; wird als
WFS-2.0-Parameter count übertragen.
startIndex (--start). Offset für die Paginierung.
Such- & API-Konzepte
Leeres Ergebnis vs. nicht gefunden. Der WFS liefert für eine unbekannte kenn eine leere
FeatureCollection mit HTTP 200, nie einen 404. Bei der Abfrage einer einzelnen Messstelle
(station <kenn>) wertet station() im Client „keine Features“ als nicht gefunden und löst
den (exportierten) StrahlNotFoundError aus, den die CLI auf den Exit-Code 4 abbildet. timeseries <kenn> und
latest --station <kenn> geben die leere Collection dagegen mit Exit-Code 0 aus: Auch eine
echte Messstelle kann eine leere Zeitreihe haben (eine defekt-Messstelle oder ts-24h), ein
leeres Ergebnis beweist dort also nicht, dass die Kennung unbekannt ist.
Rate Limiting / vorübergehende Fehler. Die Status 429 und 503 gelten als
vorübergehend und werden automatisch wiederholt (--max-retries bzw. maxRetries der
Bibliothek: 0–10, das exportierte MAX_RETRIES, Standard 2; StrahlApiError.isRetryable). Jede Wiederholung wartet einen linear wachsenden
Abstand (200 ms, 400 ms, …) oder länger, wenn das Retry-After des Servers (Sekunden oder ein
HTTP-Datum) das verlangt; Retry-After: 0 oder ein Datum in der Vergangenheit verkürzt die
Wartezeit nie. Ein Retry-After über 30 s wird nicht wiederholt: Der Fehler wird sofort
gemeldet und nennt die verlangte Wartezeit. Eine
zurückgesetzte Verbindung wird genauso wiederholt (linear wachsender Abstand), eine
Zeitüberschreitung nicht.
Entfernen von Zugangsdaten beim Wechsel des Origins. Bei einer Weiterleitung auf einen anderen
Origin entfernt die Engine Header mit Zugangsdaten (Authorization/X-API-Key/Cookie);
eine Weiterleitung mit Downgrade von https→http wird grundsätzlich abgelehnt. Eine
Weiterleitung auf denselben Origin (relative oder absolute Location) behält sie. Das
user:pw@ einer Basis-URL geht als dieser Authorization-Header mit, nie in der URL, und
Zugangsdaten in einer Location werden ignoriert.
Nur lesend, keine Authentifizierung. Der Open-Data-WFS von ODL-Info braucht keinen
Schlüssel; dieser Client stellt ausschließlich lesende GET-Anfragen.
Bibliothek & Interna. Begriffe zum TypeScript-Client und seinen Interna –
StrahlenschutzClient, die Request-Engine, Transport, Retry/Backoff, Fehlertypen, Query-Builder,FeatureKindValues/TYPE_NAMES, die Validierung vonkenn– stehen jetzt in DEVELOPING.md.