Usage

mastr — a CLI for the Marktstammdatenregister (MaStR). No API key needed.

mastr [global options] <command> [command options]

Global options

Option	Description
`--base-url <url>`	API base URL (default `https://www.marktstammdatenregister.de/MaStR`)
`--timeout <ms>`	time limit per request in ms, whole response included (0 = no timeout; at most 2147483647)
`--user-agent <ua>`	User-Agent header value
`--max-retries <n>`	retries for transient 429/503 responses (0..10)
`--max-response-bytes <n>`	cap the response body size in bytes (0 = unlimited; default 100 MiB)
`--compact`	print JSON on a single line (for piping to `jq`)
`--iso-dates`	rewrite MaStR `/Date(ms)/` timestamps to ISO-8601
`-V, --version` / `-h, --help`	version / help

Commands

Command	Dataset
`mastr stromerzeugung`	electricity-generation units (~9.06M)
`mastr stromverbrauch`	electricity-consumption units
`mastr gaserzeugung`	gas-generation units
`mastr gasverbrauch`	gas-consumption units
`mastr filters <category>`	the filterable columns (names, types, dropdown codes) for a category

Search options (the four data commands)

Option	Description
`--page <n>`	1-based page (default 1)
`--page-size <n>`	rows per page (1..5000, default 25)
`--sort <spec>`	`FieldKey-asc` or `FieldKey-desc`, e.g. `Bruttoleistung-desc`. `FieldKey` is a record field name, not a `FilterName`
`--filter <spec>`	filter expression (see below)
`--total`	print only the total match count, not the rows

Each data command prints { total, data }: total is the full match count (respects the filter), data is the current page.

Filter syntax

FilterName~op~'value'~[and|or]~FilterName~op~'value'~…

operators: eq (=), neq (≠), sw (starts-with), ct (contains), nct (not-contains), ew (ends-with), null (empty), nn (not empty), and for number/date columns gt (>) and lt (<). gt/lt are strict; there is no gte/lte, and an unknown operator returns 0 rows
value: single-quoted; for a dropdown use its code (Value), not its label; decimals take a point ('4999.999'), dates work as '2025-01-01' or '01.01.2025'
discover the FilterNames and codes with mastr filters <category>

# Solar (Energieträger 2495) units in operation (Betriebs-Status 35)
mastr stromerzeugung --filter "Energieträger~eq~'2495'~and~Betriebs-Status~eq~'35'" --total

# Wind (2497) units above 5,000 kW gross
mastr stromerzeugung --filter "Energieträger~eq~'2497'~and~Bruttoleistung der Einheit~gt~'5000'" --total

A wrong/misspelled FilterName is silently ignored and you get the unfiltered result — always confirm the exact name via mastr filters and sanity-check with --total (the count should change).

Examples

mastr stromerzeugung --total                        # 9063887
mastr stromerzeugung --page-size 5 --iso-dates      # first 5 units, ISO dates
mastr filters stromerzeugung --compact | jq '.[] | {FilterName, Type}'
mastr gasverbrauch --sort "Bruttoleistung-desc" --page-size 10 --compact | jq '.data'

Exit codes

Code	Meaning
`0`	success (help/version included); an empty result also exits 0
`1`	API/logical error (e.g. the server’s `Errors` field), or a catch-all
`2`	usage error (bad flags, unknown command, bad `--filter`/`--page-size`, redirecting base URL)
`4`	HTTP 404
`6`	network / transport failure (DNS, connection, timeout, response size-cap)

Notes

A wrong --sort field returns 0 results, not an error. An unknown sort column key makes the server answer with zero rows (total: 0), which reads like “no matches”. If a query returns 0 only after you add --sort, check the column key — the CLI prints a note to stderr in this case. Sort keys are the record’s field names (Bruttoleistung, InbetriebnahmeDatum), not the FilterNames from mastr filters (Bruttoleistung der Einheit-desc returns 0 rows); list them with mastr stromerzeugung --page-size 1 --compact | jq '.data[0] | keys'. (Contrast --filter, where a wrong field is silently ignored and you get the unfiltered set, but a wrong operator also returns 0 rows, with a stderr note naming the known ones.)
Dates are Microsoft /Date(ms)/ strings; --iso-dates converts them, or use the library’s parseMsDate().
You cannot sum capacity server-side — there is no aggregate endpoint. Use --total for counts; sum Bruttoleistung client-side only for small result sets.