govdata-cli — Usage

Real, use-case-driven examples for the govdata CLI: a read-only client for the open GovData CKAN Action API (ckan.govdata.de) — the central German open-data catalogue. Search datasets, inspect packages, resources, organizations, groups, tags and facets.

CKAN wraps every response in { help, success, result }. This CLI prints the unwrapped result and exits non-zero when success is false, so the examples below pipe straight into jq.

Install

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

This installs the govdata binary. Without a global install you can run it straight from the build output: node apps/cli/dist/src/cli/index.js <command>. The examples use govdata.

Use cases

1. Full-text search the catalogue

Find datasets matching free text (Solr query syntax) — the everyday entry point.

govdata search Haushalt --rows 5

The unwrapped result is CKAN’s search object: { count, results, sort, ... }. --rows caps how many dataset objects come back. Get just the total and the titles:

govdata search Haushalt --rows 5 | jq '{count, titles: [.results[].title]}'

2. Get the newest datasets first

See what was just published or updated — useful for monitoring a topic.

govdata search Klima --rows 10 --sort "metadata_modified desc"

--sort takes any Solr sort expression (<field> asc|desc), e.g. metadata_created desc or title_string asc.

3. Filter by publishing organization and file format

Narrow a search to one publisher and only datasets that ship CSV — for example to harvest tabular data from the Federal Statistical Office (destatis).

govdata search --fq organization:statistisches-bundesamt \
  --fq 'res_format:("CSV" OR "http://publications.europa.eu/resource/authority/file-type/CSV")' --rows 20

--fq is a Solr filter query. Repeat it for filters that must all match, or combine conditions in one filter with Solr boolean operators (AND / OR), e.g. --fq 'organization:open-nrw OR groups:tran'. Each --fq is applied as a filter of its own, so a top-level OR works as written. The bare [query] argument is optional, so you can filter without a text query as shown here.

GovData records a file format both as a bare string (CSV) and as an EU file-type URI, and the URI is far more common, so --fq res_format:CSV alone misses most CSV datasets. Match both forms, as above.

4. Page through a large result set

Walk results in batches without re-fetching — page 2 of 20-per-page:

govdata search Verkehr --rows 20 --start 20

--start is the zero-based offset. Combine with count from the first call to know when to stop:

govdata search Verkehr --rows 0 | jq '.count'

5. Inspect one dataset and its resources (distributions)

Pull the full metadata of a single dataset by id or by its slug name, then list the downloadable distributions attached to it.

govdata package luftqualitat

# Just the resources: format + direct download URL
govdata package luftqualitat \
  | jq '.resources[] | {name, format, url}'

The first hit of a search is a handy way to discover a valid id/name:

govdata search Luftqualität --rows 1 | jq -r '.results[0].name'

6. Fetch a single resource (distribution) by id

When you already have a resource id (from a dataset’s resources[]), inspect just that distribution — its format, size and download URL.

govdata resource <resource-id>

govdata resource <resource-id> | jq '{format, url, size, last_modified}'

7. List data publishers (organizations)

Discover which organizations publish to GovData — names for quick scanning, or full objects with counts and metadata.

# Just the org slugs
govdata organizations

# Full objects (title, package_count, description, ...)
govdata organizations --all-fields | jq '.[] | {name, title, packages: .package_count}'

Then drill into one:

govdata organization statistisches-bundesamt | jq '{title, package_count}'

8. Browse themes/categories (groups) and tags

Explore the controlled vocabulary you can use in --fq filters.

# Groups (themes), e.g. transport, environment, health
govdata groups
govdata groups --all-fields | jq '.[] | {name, title}'
govdata group envi

# Tags, optionally filtered by substring
govdata tags --query energie

Use a discovered group in a search filter:

govdata search --fq groups:envi --rows 10 | jq '.count'

9. Get facet counts via the generic action escape hatch

Build a “datasets per format” or “per organization” breakdown. The search command does not expose facet flags, but action package_search can pass any CKAN parameter, including facet.field.

govdata action package_search \
  --param q=Klima \
  --param rows=0 \
  --param "facet.field=[\"res_format\",\"organization\"]" \
  | jq '.search_facets.res_format.items'

--param is repeatable key=value (duplicate keys, blank keys and blank values such as q= are rejected, by the library’s action() too: CKAN would read an empty value as “no filter”). With rows=0 you pay only for the facet aggregation, not the documents.

10. Call any read action not wrapped by a dedicated command

The escape hatch reaches every CKAN read action by name.

# Equivalent to the `tags` command, via the generic action
govdata action tag_list --param query=verkehr

# Total dataset count in the catalogue
govdata action package_search --param rows=0 | jq '.count'

The action name is validated against ^[a-z0-9_]+$, so only plain action names are accepted.

Global options

These apply to every command and may be given before or after the subcommand (e.g. govdata --compact search Haushalt or govdata search Haushalt --compact).

Only --fq and --param may be given more than once. Any other option that takes a value is a usage error when repeated (--rows 5 --rows 50), rather than silently keeping the last value.

Exit codes: 0 on success (and for --help/--version), 4 on a 404 from the API or CKAN’s Not Found Error sent with HTTP 200, 1 for any other error (including any other CKAN success: false) and for usage/parse errors.