@maschinenlesbar.org/strahlenschutz-cli
    Preparing search index...

    @maschinenlesbar.org/strahlenschutz-cli

    strahlenschutz-cli

    CI Release npm

    Website: English · Deutsch — command reference, guides and API docs

    Query Germany's ambient gamma dose-rate (ODL) monitoring network from your terminal. strahlenschutz is a command-line tool over the open BfS ODL-Info WFS (imis.bfs.de): fetch the latest readings across all ~1 700 stations, look up a single station by its kenn id, or pull hourly/daily time series — all as clean GeoJSON you can pipe straight into jq.

    • Works out of the box — no account, no API key, no configuration. Install and query.
    • Clean GeoJSON output — pretty-printed by default, --compact for one-line/scripting.
    • Three commands — latest, station, and timeseries.
    • Real open data — backed by the Bundesamt für Strahlenschutz's public IMIS network.

    Want to use this as a TypeScript library or understand how it's built? See DEVELOPING.md.

    npm i -g @maschinenlesbar.org/strahlenschutz-cli

    This installs the strahlenschutz command. Requires Node.js 20+.

    Check it works:

    strahlenschutz --help

    No setup needed — the ODL-Info service is open data and requires no key. Your first command:

    strahlenschutz latest --max 5

    That prints a GeoJSON FeatureCollection with the five most recent station readings. Dose-rate values are in µSv/h and live in each feature's properties. Pull out a station's id and value with jq:

    strahlenschutz --compact latest --max 5 \
      | jq -r '.features[] | [.properties.kenn, .properties.value] | @tsv'

    Look up a single station you already know:

    strahlenschutz station 091811461

    latest                 latest ODL reading per station (GeoJSON FeatureCollection)
station <kenn>         latest reading for one station
timeseries <kenn>      hourly or daily time series for a station
    Flag Meaning
    --station <kenn> restrict to one station by its numeric kenn id
    --max <n> max features to return (WFS count)
    --start <n> paging offset (use together with --max)
    --sort <prop> sort by a feature property; append D for descending, e.g. "end_measure D"
    Argument Meaning
    <kenn> numeric station id — must be digits only, non-empty

    No per-command options. An unknown kenn exits with code 4. (Only station does this: timeseries <kenn> and latest --station <kenn> print an empty collection and exit 0, because a real station can have an empty series too.)

    Flag Meaning
    --resolution ts-1h|ts-24h hourly (default) or daily-averaged series
    --max <n> max features to return
    --start <n> paging offset
    --sort <prop> sort by a feature property

    A few recipes to get going — see Usage.md for the full, use-case-driven set.

    # Latest reading for every station (the full network)
    strahlenschutz latest

    # Sample 5 readings for a quick look
    strahlenschutz latest --max 5

    # One station you care about
    strahlenschutz station 091811461

    # Hourly time series — last 24 hours of readings
    strahlenschutz timeseries 091811461 --max 24

    # Daily time series for a longer-term view
    strahlenschutz timeseries 091811461 --resolution ts-24h

    # Page through the network (most-recent first, 10 at a time)
    strahlenschutz latest --sort "end_measure D" --max 10 --start 0
    strahlenschutz latest --sort "end_measure D" --max 10 --start 10

    Every command prints pretty GeoJSON to stdout. Errors and diagnostics go to stderr, so piping stdout into jq stays clean.

    # Extract dose rate and station id from a single-station lookup
    strahlenschutz --compact station 091811461 \
      | jq '.features[0].properties | {kenn, value}'

    # Flat TSV table of all stations — kenn and µSv/h value
    strahlenschutz --compact latest \
      | jq -r '.features[] | [.properties.kenn, .properties.value] | @tsv'

    # Plot-ready CSV: timestamp + value for the hourly series
    strahlenschutz --compact timeseries 091811461 --max 48 \
      | jq -r '.features[] | [.properties.end_measure, .properties.value] | @csv'

    Use --compact for single-line JSON in pipelines and logs:

    strahlenschutz --compact latest --max 5

    --compact (and every global option) works before or after the command — both strahlenschutz --compact latest … and strahlenschutz latest … --compact do the same thing.

    Exit codes make the CLI easy to use in scripts:

    Code Meaning
    0 success (also --help / --version)
    1 error — API error, network failure, parse error, or any other problem
    4 station not found — station <kenn> returned no features (WFS always returns 200 with an empty collection for unknown ids; timeseries and latest --station exit 0 with the empty collection)
    non-zero usage / argument-validation error (bad flag or argument)
    • command not found: strahlenschutz — the global npm bin directory isn't on your PATH. Run npm bin -g to find it and add it, or run via npx @maschinenlesbar.org/strahlenschutz-cli ….
    • Exit 4 / "No station found for kenn …" — the kenn doesn't exist in the network. Re-check the id from a fresh latest result; the WFS always returns HTTP 200 with an empty collection for an unknown station rather than a 404.
    • Empty timeseries (exit 0) — either the kenn doesn't exist or the station has no series (e.g. it is defekt, or you asked for ts-24h). timeseries can't tell these apart; run strahlenschutz station <kenn> — exit 4 means the id is unknown.
    • Non-numeric kenn rejected immediately — kenn must be digits only. The client validates this before making any request; no request is sent.
    • Exit 1 / network error — connectivity, DNS, or a timeout. Try again, or raise the limit with --timeout 60000.
    • Unexpectedly large response — raise or remove the cap with --max-response-bytes 0 (unlimited).

    These apply to every command and may be given before or after the command:

    Option Description
    -V, --version Print the version number
    -h, --help Show help for the program or a command
    --compact Print JSON on a single line instead of pretty-printed
    --base-url <url> API base URL (default https://www.imis.bfs.de)
    --timeout <ms> Time limit per request in milliseconds, reading the whole response included (default 30000; at most 2147483647)
    --user-agent <ua> User-Agent header value
    --max-retries <n> Retries for transient 429/503 responses (default 2)
    --max-response-bytes <n> Cap response body size in bytes (0 = unlimited; default 100 MiB)
    • Usage.md — full use-case-driven cookbook.
    • GLOSSARY.md — domain terms, station identifiers, WFS concepts, exit codes.
    • DEVELOPING.md — TypeScript library usage, architecture, testing, CI.
    • SKILLS.md — Claude Code Agent Skills bundled with this repo (dose-rate snapshot, station trend, GeoJSON export), installable as a plugin.

    This CLI is a client — it accesses data it does not own or redistribute. The upstream data is © its provider and licensed separately from this tool's code. See DATA_LICENSE.md.

    Bundesamt für Strahlenschutz — Datenlizenz Deutschland Namensnennung 2.0 (dl-de/by-2-0). Attribution required; commercial use and modification allowed.

    Dual-licensed — use it under either:

    • AGPL-3.0-or-later (default, free). Note the AGPL's §13 network clause: if you run a modified version as a network service, you must offer that modified source to the service's users.
    • Commercial license (paid), for closed-source / proprietary or SaaS use without the AGPL's obligations.

    See LICENSING.md for details, and CONTRIBUTING.md for the contribution policy (this project does not accept external code contributions). Commercial enquiries: sebs@2xs.org.

    Settings
    Member Visibility

    On This Page
    strahlenschutz-cli