Glossary

A reference for the domain concepts and project-specific terms used throughout tagesschau-cli. The Tagesschau domain is German; this glossary gives the term as it appears in the API/CLI alongside the German word where one is in common use.

Quick orientation. This tool wraps the open, no-auth Tagesschau API (tagesschau.de), ARD-aktuell’s structured German news feed. Everything is a read-only GET; there is no key, no upload and no write.

The Tagesschau API

Tagesschau. Germany’s flagship television news programme, produced by ARD-aktuell and broadcast by the public-service broadcaster ARD. Its website tagesschau.de publishes the same editorial output as structured data.

ARD — Arbeitsgemeinschaft der öffentlich-rechtlichen Rundfunkanstalten. The consortium of regional public-service broadcasters in Germany that produces and carries the Tagesschau. ARD-aktuell is the joint newsroom responsible for the content this API serves.

Tagesschau API. The undocumented-but-open REST interface behind tagesschau.de, served under the path prefix /api2u (e.g. https://www.tagesschau.de/api2u/homepage/). It needs no authentication and is read-only. Community documentation lives at tagesschau.api.bund.dev.

/api2u. The base path of the API on the host. Every endpoint this client calls is ${baseUrl}/api2u/<resource>/ — the default baseUrl is https://www.tagesschau.de.

Resources & endpoints

The CLI mirrors the API resources; each is one top-level command.

Homepage (/api2u/homepage/). The curated front-page feed: the editorially selected top stories plus a regional block. CLI: homepage. Returns a HomepageResult (news, regional).

News (/api2u/news/). The general news feed, optionally narrowed by region(s) and/or a Ressort. CLI: news. Returns a NewsResult (news, regional, optional nextPage cursor).

Channels (/api2u/channels/). The live and broadcast channels (the linear/streaming programme feed). CLI: channels. Returns a ChannelsResult (channels).

Search (/api2u/search/). Full-text search across articles. CLI: search <text>. Returns a SearchResult (searchResults, optional totalItemCount).

Filters, parameters & identifiers

Ressort. The topic/department of a news item — the German newsroom term for a news category. The news endpoint accepts one Ressort via --ressort. The values the client surfaces (RessortValues) are: inland, ausland, wirtschaft, sport, video, investigativ, wissen.

Region (Bundesland id). A German federal state, identified by a numeric id 1–16 in the order the API documents the Bundesländer. Passed to the news endpoint via the repeatable --region flag; the client joins multiple ids into a single comma-separated regions query value (e.g. ?regions=5,9). The accepted ids are exposed as RegionValues.

searchText. The free-text query for the search endpoint (the positional <text> argument of search). Sent verbatim to the API; an empty value is rejected client-side by the CLI.

pageSize / resultPage. The search endpoint’s paging parameters, exposed as --page-size / --result-page. pageSize is the number of hits per page and must be >= 1. resultPage is a 0-based page index: 0 (the default) is the first page, and an index past the last page returns no hits.

nextPage. A cursor URL returned by the news endpoint pointing at the next page of results, when present.

news / regional. The two item lists returned by the homepage and news feeds: the main feed and the regional block. Each entry is a news item.

News item. A single story or article. Its shape varies by item type (content blocks, image variants, tracking metadata), so the client exposes each item as a faithful raw JsonObject (NewsItem) rather than a partially-guessed type.

Search & API behaviour

No authentication. The Tagesschau API is fully open; this client sends no key, token or cookie. It only issues read-only GET requests.

Rate limiting / transient errors. When the API answers with a transient status (429 Too Many Requests, 503 Service Unavailable), the client retries automatically with linear backoff (--max-retries, default 2).

Redirects. The client follows up to --max-redirects redirects (default 5). On a cross-origin hop it strips credential-bearing headers (Authorization, X-API-Key, Cookie) before the next request so they can never leak to an unintended host; same-origin redirects keep all headers.

Response size cap. Responses larger than --max-response-bytes (default 100 MiB; 0 = unlimited) are aborted to defend against memory exhaustion from a hostile or buggy endpoint.

Exit codes

Exit codes. The CLI maps outcomes to process exit codes: 0 success; 4 on a 404 from the API; 1 for any other error (API error, network failure, unexpected); and a non-zero commander code for usage / argument-validation errors. --help/--version return 0.

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