Glossary

A reference for the domain concepts and project-specific terms used throughout jobsuche-cli. The Jobsuche domain is German; this glossary gives the English term used in the CLI/library (where one exists) alongside the original German field/parameter name the API uses on the wire.

Translation table (the API’s German names → CLI flag / English term):

German (API)	CLI flag / English term
was	--was — job title / keyword
wo	--wo — location
berufsfeld	--berufsfeld — occupational field
arbeitgeber	--arbeitgeber — employer
umkreis	--umkreis — radius (km)
veroeffentlichtseit	--veroeffentlicht-seit — published since (days)
zeitarbeit	--zeitarbeit — temp-work agencies
angebotsart	--angebotsart — offer type code
Stellenangebot	job listing / offer
Arbeitsort	work location

The Jobsuche API

Bundesagentur für Arbeit (BA). Germany’s Federal Employment Agency. It runs the public job-search service this tool wraps.

Jobsuche API. The open REST API behind the BA’s job board — Germany’s largest job database. Base URL https://rest.arbeitsagentur.de, service path /jobboerse/jobsuche-service. Documented at jobsuche.api.bund.dev. This tool implements its two open, read-only endpoints (search + details).

X-API-Key. The API requires a static, publicly-documented API key (jobboerse-jobsuche) on every request. It is not a secret, but it is not bundled with the client — supply it via --api-key, the JOBSUCHE_API_KEY env var, or the apiKey client option, else the header is omitted and the API answers 401/403. For CI / live testing the public key can be fetched out-of-band with the CLI’s own obtain-key command (npm run obtain-key in a built checkout), which reads it from the upstream source at run time.

Endpoints

Search (/pc/v4/jobs). Returns a page of job-listing summaries matching the search parameters. CLI: search. Library: client.search(params).

Details (/pc/v4/jobdetails/{encryptedJobCode}). Returns the full payload for a single listing, addressed by its encryptedJobCode. CLI: details. Library: client.details(refnr).

Resources & identifiers

Stellenangebot (job listing / offer). One job posting. In a search result it is a summary carrying beruf, titel, refnr, arbeitgeber, arbeitsort, publication/entry dates and an optional externeUrl. Full detail is fetched separately via details. (Stellenangebot in src/client/types.ts.)

refnr (reference number). The stable identifier of a listing, returned in each search result’s refnr field — e.g. 10001-1002716922-S, the hex form 14225-dafcdd47aabe512d-S, or a purely numeric 1002716922. It is made of digits, letters and hyphens. This is the argument you pass to details.

encryptedJobCode. The form a refnr must take in the details URL: the base64 encoding of the refnr. The client base64-encodes the refnr for you; an already-base64-encoded code is detected (by an exact base64 round-trip, not charset sniffing) and passed through unchanged.

hashId. An additional listing identifier the API stamps on a Stellenangebot.

Arbeitsort (work location). The location of a listing as the API serialises it: plz (postal code), ort (city/town), strasse (street), region, land (country), koordinaten (lat/lon), and entfernung (distance in km from the searched location, present only on radius searches).

Arbeitgeber (employer). The hiring organisation named on a listing; also a search filter (--arbeitgeber).

beruf / berufsfeld. beruf is the occupation/job title on a listing; berufsfeld (occupational field) is a broader category usable as a search filter (--berufsfeld).

Search parameters

was. Free-text job title or keyword (--was). An empty/whitespace value is treated as “not provided” (the live API rejects an empty was= with HTTP 400).

wo. The location to search in or around (--wo). The API echoes the resolved location back as woOutput in the result.

umkreis. Search radius in kilometres around wo (--umkreis).

veroeffentlichtseit (published since). Restrict results to listings published within the last N days (--veroeffentlicht-seit).

zeitarbeit (temp work). Boolean flag to include temporary-work / staffing agencies (--zeitarbeit).

angebotsart (offer type). A numeric code selecting the kind of offer (--angebotsart): 1 job vacancy (Arbeit), 2 self-employment (Selbstständigkeit), 4 apprenticeship or dual study (Ausbildung / Duales Studium), 34 internship or trainee post (Praktikum / Trainee). These are the codes in the upstream bundesAPI OpenAPI spec. Passed through verbatim to the API.

page / size. Pagination: page is 1-based, size is the page size (--page, --size).

Result envelope

JobSearchResult. The search response: stellenangebote (the array of listings), maxErgebnisse (total number of matches), page, size, facetten (aggregation facets), and woOutput (the location the API actually searched). (JobSearchResult in src/client/types.ts.)

stellenangebote. The array of Stellenangebot summaries on a result page.

maxErgebnisse. The total count of matching listings across all pages.

facetten (facets). Aggregated counts the API returns alongside results (e.g. by location or employer), surfaced as a raw object.

JobDetails. The full single-job payload from the details endpoint, kept as a faithful raw JSON object rather than a narrowed type.

Search & API concepts

Public, no-auth (read-only). Only the open GET search and details endpoints are implemented. The static X-API-Key is not a credential a user must obtain.

Rate limiting / transient errors. The API may return 429 (too many requests) or 503; the client retries these automatically with linear backoff (--max-retries, default 2).

Credential stripping on redirect. Credential headers (X-API-Key, Authorization, Cookie) are dropped if the API redirects to a different origin, so the key cannot leak to a third-party host. Same-origin redirects keep them.

Library & internals. Terms for the TypeScript client and its internals — JobsucheClient, the request engine, transport, retry/backoff, error types, query builder — now live in DEVELOPING.md.