Glossary

Entgeltatlas concepts and the vocabulary this CLI exposes. The API answers one question: what does a given occupation earn? — as a median gross monthly salary, sliced by five dimensions.

Occupations

Term	Meaning
KldB 2010	Klassifikation der Berufe 2010 — the BA’s occupation code system. The `entgelte` command’s required argument. Codes are 3–5 digits (e.g. `84304` = “Berufe in der Hochschullehre und -forschung – hoch komplexe Tätigkeiten”). Kept as a string (leading zeros matter).
name → code	This API has no name search. Resolve an occupation name to its KldB code via the BERUFENET / DKZ sibling APIs, or the Klassifikationsserver.

The five dimensions

Pass each as a numeric code; run entgeltatlas codes for the full tables. Code 1 is the Gesamt aggregate only for -g, -a and -b: for -l it is Helfer (there is no Gesamt level) and for -r it is Deutschland. Omitting a flag sends no parameter, so the server picks the slice; that has not been verified against the live API. Pass the dimensions you mean and check the labels in each returned row.

Flag	Param	Dimension	Codes
`-l`	`l`	Anforderungsniveau (requirement/performance level)	1 Helfer · 2 Fachkraft · 3 Spezialist · 4 Experte
`-r`	`r`	Region	1 Deutschland · 2 Ost · 3 West · 4–19 the 16 Länder · 20–30 eleven cities (irregular — not 1..16)
`-g`	`g`	Geschlecht	1 Gesamt · 2 Männer · 3 Frauen
`-a`	`a`	Alter	1 Gesamt · 2 unter 25 · 3 25 bis unter 55 · 4 ab 55
`-b`	`b`	Branche (Wirtschaftszweig)	1 Gesamt … 11 (see `codes`)

Reading the figures

Field	Meaning
`entgelt`	Median gross monthly earnings, EUR, full-time. Not the arithmetic mean — the BA deliberately does not compute a mean (earnings above the ceiling are unknown).
`entgeltQ25` / `entgeltQ75`	Lower / upper quartile (25th / 75th percentile), EUR.
`besetzung`	The headcount the figures are based on — a count of people, not a salary.
`region.beitragsBemessungsGrenze`	The social-insurance contribution ceiling. Earnings above it are censored, so `entgelt`/`entgeltQ75` can look artificially flat at the top.

Suppression (Datenschutz / kleine Fallzahl)

When a slice is based on too few observations, the cell is suppressed for data protection: the response is an empty array or the numeric fields come back null. This means “not available / n too small” — never 0. The client and CLI preserve null faithfully; do not treat it as zero earnings.

Auth terms

X-API-Key — the static header this API authenticates with. Its value is the BA’s published community client_id UUID (an access identifier, not a per-user grant). Obtain it with entgeltatlas obtain-key; never commit it — not even the public community key. Tests use an obvious dummy UUID (00000000-0000-4000-8000-000000000000) so the repo holds zero real credentials.
WAF / 403 — rest.arbeitsagentur.de sits behind an Akamai WAF that blocks datacenter/VPN/cloud IPs with an empty-body HTTP 403, even with a valid key. A wrong or missing key gets the same empty-body 403, so the response alone can’t tell an IP block from an auth failure: re-check the key first, then try another network — see DEVELOPING.md.

See DATA_LICENSE.md for attribution and reuse terms.