destatis-genesis-cli

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

A TypeScript API client and CLI for the DESTATIS GENESIS-Online REST API (version 2020) — the German Federal Statistical Office's official-statistics database at www-genesis.destatis.de.

Search the catalogue, read object metadata, and pull statistical tables, cubes and time series from the command line or as a library. Read-only, zero runtime HTTP dependencies (built on node:http/https), strict TypeScript, ESM.

npm install -g @maschinenlesbar.org/destatis-genesis-cli

Credentials

GENESIS needs a free registered account — register at www-genesis.destatis.de. Authenticate with either a personal API token or your username + password. No credential is bundled with this tool.

| How | Flag | Env var | |-----|------|---------| | Token (recommended) | --token <t> | DESTATIS_API_TOKEN | | Username + password | --username <u> / --password <p> | DESTATIS_USERNAME / DESTATIS_PASSWORD |

Precedence per field is flag > env var > unset; a token takes precedence over username/password — except that a --username/--password flag beats a token from DESTATIS_API_TOKEN, so the account you name on the command line is the one used. destatis hello and destatis find work without credentials (GENESIS serves anonymous searches as its guest user GAST); catalogue, metadata, data and logincheck need an account. Credentials are sent exactly as given: a blank credential flag, or one with leading or trailing whitespace (which an HTTP header cannot carry), is refused with exit 2; a blank env var counts as unset.

Prefer the environment variables. A credential passed as a --token / --username / --password flag is visible in the process table (ps, /proc) to other local users and is persisted in your shell history — the account password is especially sensitive. The CLI prints a one-line stderr warning when it detects a flag-supplied credential. Set the env var instead; it takes effect whenever the corresponding flag is absent.

export DESTATIS_API_TOKEN="your-32-char-token"

Quickstart

destatis hello                                  # connectivity check (no auth)
destatis logincheck                             # validate your credentials
destatis find "Bevölkerung" --category tables   # search for tables
destatis catalogue tables "124*"                # browse tables by code
destatis metadata table 12411-0001              # describe a table
destatis data table 12411-0001 --start-year 2020 --compact
destatis data tablefile 12411-0001 --format ffcsv -o pop.zip

Every command prints the API's JSON envelope (including the Copyright attribution and a Status object). See Usage.md for the full command reference and GLOSSARY.md for GENESIS concepts (EVAS codes, cubes, selection wildcards, Status.Code values).

Library use

import { DestatisClient } from "@maschinenlesbar.org/destatis-genesis-cli";

const genesis = new DestatisClient({ token: process.env.DESTATIS_API_TOKEN });
const hits = await genesis.find({ term: "Bevölkerung", category: "tables" });
const table = await genesis.data.table("12411-0001", { startyear: "2020" });
// table.Object.Content is the table as a ";"-delimited CSV string.

The client is usable independently of the CLI. Errors are typed (DestatisApiError, DestatisNetworkError, DestatisParseError, DestatisUsageError).

Notes

• HTTP 200 ≠ success. GENESIS reports logical outcomes in a Status object in the body; this client inspects Status.Code and raises DestatisApiError for real errors (see DEVELOPING.md).
• The data is Destatis's, not ours — governed by DL-DE-BY-2.0. See DATA_LICENSE.md.
• Code license: AGPL-3.0-or-later OR commercial — see LICENSING.md. External code contributions are not accepted (CONTRIBUTING.md); bug reports and forks are welcome.

Claude Code skills

Three Agent Skills teach Claude Code to use this CLI for real questions: turn a topic into a GENESIS object code (destatis-statistics-finder), fetch and decode its numbers (destatis-data-fetch), and export tables to CSV or Excel (destatis-table-download). Install them from the maschinenlesbar.org marketplace:

/plugin marketplace add maschinenlesbar-org/plugins
/plugin install destatis-genesis@maschinenlesbar

See SKILLS.md for details.

Development

npm install
npm run build      # tsc -> dist/
npm test           # builds, then runs node --test on dist/test
npm run typecheck

See DEVELOPING.md for architecture and API specifics.