Glossary

Concepts of the Regionaldatenbank Deutschland and the vocabulary this CLI exposes. The database runs the GENESIS software: statistics are made of cubes, which are sliced into tables, described by variables and their values — and almost everything here additionally has a regional dimension reaching down to Kreis and Gemeinde level.

Objects

Term GENESIS Meaning
Statistic (Statistik) statistic A whole statistical product, keyed by a 5-digit EVAS code (e.g. 12411, “Fortschreibung des Bevölkerungsstandes”). Contains cubes.
Table (Tabelle) table A ready-made 2-D view, keyed like 12411-01-01-4. The main thing you fetch.
Cube (Datenquader) cube The raw multidimensional data behind tables.
Time series (Zeitreihe) timeseries A cube reduced to a single value over time.
Variable (Merkmal) variable A dimension/attribute (e.g. KREISE = Kreise und kreisfreie Städte, GES = Geschlecht).
Value (Ausprägung) value A concrete value of a variable (e.g. one specific Kreis).
Result (Ergebnistabelle) result A table produced by an async job, saved in your user area.

Codes & selection

Regional keys & levels

The response envelope

Every non-helloworld response is wrapped:

Field Meaning
Ident { Service, Method } — which endpoint answered.
Status { Code, Content, Type } — the logical outcome (see below).
Parameter echo of your request (credentials masked as ********).
Copyright the attribution string to cite — see DATA_LICENSE.md.
List catalogue results (a homogeneous array).
Object data/metadata payload (opaque; for data/table, a CSV string in Object.Content).

helloworld/whoami and helloworld/logincheck do not use this envelope — and neither do authentication failures, which arrive as a bare { Code, Content, Type } object (see below). logincheck answers HTTP 200 whether or not the credentials are right: its Status is a text — an error text (“Ein Fehler ist aufgetreten …”) means they were rejected, and the CLI exits 1 with the credentials hint — and Username names the account (a wrong token comes back echoed there).

Status.Code values

Most logical outcomes ride on HTTP 200; auth failures pair the same shape with 401/404:

Code Type Meaning This CLI
0 Information success returns data
22 Warnung success, a parameter was auto-corrected returns data (warning visible in Status.Content)
50 Information no newer data (for --stand) returns data
104 Information no object matched — a filter that excludes everything, or a code that does not exist (metadata/data) returns an empty result (exit 0); a data <kind>file download fails instead (exit 4, no file written)
90 Fehler requested object not found error, exit 4
98 Information result too large for a direct fetch error with narrowing guidance, exit 1
15 ERROR not authorized (no/unrecognized credentials; flat body on HTTP 401) error + credentials hint, exit 1
2 ERROR wrong username/password (flat body on HTTP 404 — not a missing object! — or on HTTP 200) error + credentials hint, exit 1
any Fehler / Error general error error, exit 1
any other Information / Warnung not a documented success code error, exit 1 (never returned as data)

The mapping is strict on purpose: a code this CLI doesn’t know fails loudly (exit 1) instead of passing as data with a warning. An HTTP 404 that carries no GENESIS code — the HTML error page of a wrong path, for instance — counts as “not found”, exit 4.

Value-status placeholders

In a data/table CSV, a cell may be a status symbol instead of a number: - (nothing to report / genuine zero context), . (unknown/secret — common at Gemeinde level due to statistical confidentiality), ... (not yet available), / (no figure: value not reliable enough), x (no meaningful statement possible), () (limited informative value), p (provisional), r (revised), s (estimated).

Auth terms

See DEVELOPING.md for how credentials are passed on the wire and why redirects are not followed.

Log records

Log record. Every diagnostic line the CLI writes to stderr: a timestamp, a level (ERROR, WARN, INFO) and a topic regstat.<area>, as text (log4j style) or with --log-format jsonl as one JSON object per line. The areas: cli (usage errors, commander’s messages, unexpected errors, the warning about a credential given as a flag), api (GENESIS’s answers: an error status, the credentials hint, and a malformed answer — bad JSON, the wrong shape, an empty body, an HTML page instead of a file, a login check that confirms nothing), http (the connection, the cleartext warning, and one WARN per retry before it waits), config (the credentials file) and output (the -o file, stdout failures). A record is always one line; control characters in it are escaped.

View the source on GitHub →