fragdenstaat-cli

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

A command-line client and TypeScript library for the public, read-only API of FragDenStaat.de — Germany's central Freedom-of-Information (Informationsfreiheit) portal, run by the Open Knowledge Foundation Deutschland.

Query ~285,000 FOI requests, ~42,000 public bodies, the ~189 German FOI laws, and the published documents behind them — from your shell or from Node. No API key, no account, no config: the data is public and read-only.

• Zero-key. Every wrapped endpoint is anonymously readable.
• Zero runtime HTTP deps. Built on node:http/https; the only runtime dependency is commander.
• JSON or CSV. Pretty/compact JSON by default; --csv streams the server's flattened CSV export for spreadsheets/pandas.
• Library + CLI. Import the typed FragDenStaatClient, or run fragdenstaat.

This is a client, not the data. It only accesses data served live by FragDenStaat. See DATA_LICENSE.md — the corpus is a mix of public-domain authority responses, CC0 user contributions, and personal data.

Install

npm install -g @maschinenlesbar.org/fragdenstaat-cli
# or run once, without installing:
npx @maschinenlesbar.org/fragdenstaat-cli --help
Copy

Requires Node ≥ 20.

Quick start

# Find FOI requests about a topic (full-text search)
fragdenstaat request search --q "Videoüberwachung" --limit 5

# Filter requests: resolved & successful, federal jurisdiction
fragdenstaat request list --status resolved --resolution successful --jurisdiction 1 --limit 10

# One request in full, including its message thread
fragdenstaat request get 374948

# Which authority handles a topic? (name -> id, then profile)
fragdenstaat publicbody autocomplete "Umweltbundesamt"
fragdenstaat publicbody get 1

# Which FOI law applies in a jurisdiction?
fragdenstaat jurisdiction list
fragdenstaat law list --jurisdiction 1 --q umwelt

# Export a dataset to CSV
fragdenstaat request list --status resolved --jurisdiction 1 --csv -o requests.csv
Copy

Output is the Tastypie envelope:

{
  "meta": { "limit": 5, "offset": 0, "total_count": 199646, "next": "…", "previous": null },
  "objects": [ { "id": 1, "title": "…", "status": "resolved", "resolution": "successful", … } ]
}
Copy

Commands

Group	Sub-commands	Notes
request	list · get <id> · search · tags <query>	FOI requests — the core resource
publicbody	list · get <id> · search · autocomplete <query>	Authorities (Behörden)
law	list · get <id> · autocomplete <query>	FOI laws (IFG/UIG/VIG + state/local)
jurisdiction	list · get <id>	Bund + 16 Länder + EU
category	list · get <id> · autocomplete <query>	Topic taxonomy (tree)
classification	list · get <id>	Public-body types (tree)
campaign	list · get <id>	Coordinated mass-request projects
georegion	list · get <id> · autocomplete <query>	Regions (state/district/zip…)
message	list · get <id>	Correspondence within requests
document	list · get <id>	Published documents from responses

list/search take --offset/--limit and (where the server supports it) --csv. Run fragdenstaat <group> <sub> --help for the full filter set, or see Usage.md.

Global options

Flag	Purpose
--base-url <url>	override the API base (default https://fragdenstaat.de)
--timeout <ms>	per-request timeout (at most 2147483647)
--user-agent <ua>	override the User-Agent
--max-retries <n>	retries for transient 429/503
--max-response-bytes <n>	cap the response body size (0 = unlimited)
--compact	single-line JSON
-o, --output <file>	write JSON (or CSV with --csv) to a file instead of stdout

Good to know

• Page size is capped at 50 by the server. --limit accepts 1..50; page with --offset. meta.total_count is the real total (search endpoints cap it at 10000).
• IDs are numeric. Resolve a name to its id first via autocomplete or list --q, then filter by id. category autocomplete returns names, not ids; use category list --q for categories.
• Anonymous = public only. resolution is empty until a request is resolved.
• Exit codes: 0 success; 4 for a 404 (not found); 1 for any other API or runtime error. Errors print to stderr; stdout stays clean for piping.

Library usage

import { FragDenStaatClient } from "@maschinenlesbar.org/fragdenstaat-cli";

const fds = new FragDenStaatClient();

const { meta, objects } = await fds.requests.list({
  status: "resolved",
  resolution: "successful",
  jurisdiction: 1,
  limit: 50,
});
console.log(meta.total_count, objects[0]?.title);

const law = await fds.laws.get(124);
Copy

Every resource group exposes .list(params) and .get(id); request/publicbody add .search(), and request/publicbody/law/category/georegion add autocomplete. Errors are typed (FdsApiError with .status/.detail, FdsNetworkError, FdsParseError). The full API docs build with npm run docs.

Skills

This repo ships four Claude Code Agent Skills (packaged as a Claude Code plugin) that drive the CLI for common tasks: finding & analysing requests, looking up authorities, exploring the FOI legal landscape, and digging out / exporting documents.

Licensing

Code is dual-licensed AGPL-3.0-or-later OR commercial — see LICENSING.md. No external code contributions are accepted (CONTRIBUTING.md); bug reports and AGPL forks are welcome. The data is governed separately by the provider — see DATA_LICENSE.md.