Dieses Dokument gibt es nur auf Englisch.

Usage

destatis <command> [options]. Every command hits the GENESIS-Online 2020 REST API and prints its JSON envelope (Ident / Status / Parameter / Copyright plus List or Object). Object codes are EVAS-style (e.g. table 12411-0001, statistic 12411) — find them with find / catalogue.

Credentials & global options

Set credentials once (see README). Prefer the environment variables over the flags: a credential passed as a flag is visible in the process table and shell history, so the CLI warns to stderr when it detects one.

export DESTATIS_API_TOKEN="…"          # or DESTATIS_USERNAME + DESTATIS_PASSWORD

Global options (valid on any command):

Flag Meaning
--token <t> API token (env DESTATIS_API_TOKEN)
--username <u> · --password <p> account login (env DESTATIS_USERNAME / DESTATIS_PASSWORD)
--base-url <url> API base (default https://genesis.destatis.de)
--language <de\|en> response language (default de; English data labels are partial)
--pagelength <n> max list results, 1..25000 (server default 100)
--timeout <ms> · --max-retries <n> · --max-response-bytes <n> transport tuning (--timeout at most 2147483647)
--user-agent <ua> User-Agent header
--compact single-line JSON
-o, --output <file> write output (JSON, or a download) to a file instead of stdout
--force overwrite the --output file if it already exists (otherwise the write is refused)

hello / logincheck

destatis hello           # helloworld/whoami — needs NO credentials
destatis logincheck      # helloworld/logincheck — validates your credentials

find — full-text search

destatis find <term> [--category all|tables|statistics|cubes|variables|time-series]

--pagelength bounds the result count. Returns parallel arrays (Tables/Statistics/Cubes/Timeseries/Variables), each null when not searched.

destatis find "Bevölkerung" --category tables --pagelength 20

catalogue — browse objects by code

destatis catalogue <sub> [selection] [--area <a>] [--search-criterion Code|Content]
                                     [--sort-criterion Code|Content] [--type <t>]

<sub> ∈ tables · statistics · cubes · timeseries · variables · values · terms · jobs · modified · results · qualitysigns. [selection] filters by code and accepts a * wildcard (e.g. 124*). Alias: cat.

destatis catalogue statistics "12*"
destatis catalogue tables 12411 --sort-criterion Content

metadata — describe an object

destatis metadata <kind> <name> [--area <a>]

<kind> ∈ table · statistic · cube · timeseries · variable · value. Alias: meta.

destatis metadata table 12411-0001

data — fetch statistical data

destatis data <kind> <name> [selection filters]

<kind> ∈ table · cube · timeseries · result. The result carries the table as a ";"-delimited CSV string in Object.Content (German number format — comma decimals; . - x / … are value-status placeholders).

Selection filters (narrow large tables — see the too-large note below):

Flag GENESIS param
--start-year <YYYY> · --end-year <YYYY> startyear / endyear
--timeslices <n> timeslices (from the latest period back)
--region-var <code> · --region-key <key> regionalvariable / regionalkey
--class-var1..5 <code> · --class-key1..5 <key> classifyingvariable{n} / classifyingkey{n}
--contents <labels> contents (comma-separated)
--stand <DD.MM.YYYY> stand (only newer data)
--structure · --transpose · --compress structureinformation / transpose / compress 
destatis data table 12411-0001 --start-year 2015 --end-year 2023 --class-var1 DLAND

File downloads

destatis data <kind>file <name> -o <file> [--format datencsv|csv|ffcsv|xlsx|html|genml] [filters]

<kind>file ∈ tablefile · cubefile · timeseriesfile · resultfile. The server returns a ZIP wrapper; the bytes are written as-is to -o <file> (or stdout). ffcsv is a tidy/flat CSV with English headers; datencsv is the default.

destatis data tablefile 12411-0001 --format ffcsv -o population.zip

Exit codes

Code Meaning
0 success (help/version included); also an empty result — see note
1 API/logical error (including HTTP 401), network or parse error
2 usage error (missing/partial credentials, bad flags/arguments, unknown command)
4 object not found — only the rare Status.Code 90 / HTTP 404 (see note) — and wrong credentials (see the second note)

A missing object code does not exit 4. Looking up a code that does not exist on metadata/data returns Status.Code 104 (“Es gibt keine Objekte zum angegebenen Selektionskriterium”) — a valid empty result, so the CLI exits 0, the same as an empty catalogue/find search. The 90 → 4 mapping is a defensive path the server rarely takes. To detect “no such object” in a script, inspect Status.Code in the payload, not the exit code.

Wrong credentials exit 4. GENESIS answers a wrong username/password or token with HTTP 404 and a flat {"Code":2,"Content":"…Nutzernamen oder Ihren Token bzw. das Passwort…","Type":"ERROR"} body. The CLI maps that 404 to exit 4 and prints only Error: HTTP 404 for POST …, without the GENESIS text or a credentials hint. A bare HTTP 404 (no GENESIS status …) therefore means a login problem.

Gotchas

Quelle auf GitHub ansehen →