Glossar

Ein Nachschlagewerk für die Fachbegriffe und projektspezifischen Begriffe, die in tagesschau-cli verwendet werden. Die Fachsprache der Tagesschau ist deutsch; dieses Glossar nennt die Begriffe so, wie sie in API und CLI vorkommen, zusammen mit dem gebräuchlichen deutschen Wort, wo es eines gibt.

Kurzüberblick. Dieses Tool kapselt die offene Tagesschau-API ohne Authentifizierung (tagesschau.de), den strukturierten deutschen Nachrichten-Feed von ARD-aktuell. Alles ist ein lesendes GET; es gibt keinen Schlüssel, keinen Upload und keine Schreibzugriffe.

Die Tagesschau-API

Tagesschau. Die wichtigste Fernsehnachrichtensendung Deutschlands, produziert von ARD-aktuell und ausgestrahlt von der öffentlich-rechtlichen ARD. Ihre Website tagesschau.de veröffentlicht dieselben redaktionellen Inhalte als strukturierte Daten.

ARD – Arbeitsgemeinschaft der öffentlich-rechtlichen Rundfunkanstalten. Der Verbund der öffentlich-rechtlichen Landesrundfunkanstalten in Deutschland, der die Tagesschau produziert und sendet. ARD-aktuell ist die gemeinsame Redaktion, die für die Inhalte dieser API verantwortlich ist.

Tagesschau-API. Die nicht dokumentierte, aber offene REST-Schnittstelle hinter tagesschau.de, bereitgestellt unter dem Pfadpräfix /api2u (z. B. https://www.tagesschau.de/api2u/homepage/). Sie braucht keine Authentifizierung und ist nur lesbar. Eine Dokumentation der Community gibt es unter tagesschau.api.bund.dev.

/api2u. Der Basispfad der API auf dem Host. Jeder Endpoint, den dieser Client aufruft, lautet ${baseUrl}/api2u/<resource>/ – die Standard-baseUrl ist https://www.tagesschau.de.

Ressourcen & Endpoints

Die CLI bildet die Ressourcen der API ab; jede ist ein eigener Befehl auf oberster Ebene.

Startseite (/api2u/homepage/). Der redaktionell zusammengestellte Feed der Startseite: die ausgewählten Top-Meldungen plus ein Regionalblock. CLI: homepage. Liefert ein HomepageResult (news, regional).

Nachrichten (/api2u/news/). Der allgemeine Nachrichten-Feed, optional eingeschränkt nach Region(en) oder nach einem Ressort – nicht beidem: Die API wendet dann das Ressort an und ignoriert die Regionen stillschweigend, deshalb lehnen CLI und Client die Kombination vor jeder Anfrage ab. CLI: news. Liefert ein NewsResult (news, regional, optional den Cursor nextPage).

Kanäle (/api2u/channels/). Die Live- und Sendekanäle (der Programm-Feed für lineares Fernsehen und Streaming). CLI: channels. Liefert ein ChannelsResult (channels).

Suche (/api2u/search/). Volltextsuche über Artikel. CLI: search <text>. Liefert ein SearchResult (searchResults, totalItemCount, die zurückgegebenen searchText/pageSize/resultPage sowie type/details).

Filter, Parameter & Kennungen

Ressort. Das Thema bzw. die Redaktionsabteilung einer Meldung – der Begriff aus der Nachrichtenredaktion für eine Nachrichtenkategorie. Der News-Endpoint akzeptiert ein Ressort über --ressort. Die Werte, die der Client bereitstellt (RessortValues), sind: inland, ausland, wirtschaft, sport, video, investigativ, wissen. Jeden anderen Wert (auch falsch geschrieben, mit Leerraum oder leer) lehnt der Client vor jeder Anfrage ab (ressortProblem) und damit auch die CLI.

Region (Bundesland-ID). Ein Bundesland, bezeichnet durch eine numerische ID 1–16 in der Reihenfolge, in der die API die Bundesländer dokumentiert. Wird dem News-Endpoint über die wiederholbare Option --region übergeben; der Client fügt mehrere IDs zu einem einzigen kommagetrennten Query-Wert regions zusammen (z. B. ?regions=5,9). Die zulässigen IDs sind als RegionValues bereitgestellt; jeden anderen Wert (17, 09, ` 9, 9,10, leer) lehnt der Client vor jeder Anfrage ab (regionProblem`) und damit auch die CLI.

searchText. Der Freitext-Suchbegriff für den Such-Endpoint (das Positionsargument <text> von search). Wird wie eingegeben an die API gesendet, nur vorher auf Unicode-NFKC normalisiert (ein zerlegter Umlaut, etwa aus macOS-Dateinamen oder PDFs kopiert, fände sonst nichts). Die API ignoriert Groß- und Kleinschreibung, vergleicht Schreibweisen aber wörtlich (Strasse findet weit weniger Treffer als Straße); bei einem Text, der so eine ASCII-Umschrift sein kann, gibt die CLI einen Hinweis auf stderr aus (searchSpellingHint). Einen leeren, nur aus Leerraum bestehenden oder fehlenden Wert lehnt der Client vor jeder Anfrage ab (searchTextProblem, ein TagesschauValidationError) und damit auch die CLI.

pageSize / resultPage. Die Paginierungsparameter des Such-Endpoints, bereitgestellt als --page-size / --result-page. pageSize ist die Zahl der Treffer pro Seite und muss >= 1 sein. resultPage ist ein ab 0 gezählter Seitenindex: 0 (der Standard) ist die erste Seite, ein Index hinter der letzten Seite liefert keine Treffer. Beide sind höchstens 2147483647 (MAX_SEARCH_INT, upstream eine 32-Bit-Ganzzahl). Einen Wert außerhalb des Bereichs oder eine Nicht-Ganzzahl lehnt der Client vor jeder Anfrage ab (pageSizeProblem / resultPageProblem) und damit auch die CLI.

nextPage. Eine URL, die der News-Endpoint liefert und die auf die nächste, ältere Ergebnisseite zeigt, sofern vorhanden: dieselben Filter plus ein Cursor date im Format YYMMDD (…/api2u/news?date=260924&regions=9). Mit news --date 260924 und denselben Filtern folgt man ihr (Bibliothek: news({ date: "260924" })); ein fehlerhaftes oder unmögliches Datum wird vor jeder Anfrage abgelehnt.

news / regional. Die beiden Listen, die die Feeds von Startseite und Nachrichten liefern: der Haupt-Feed und der Regionalblock. Jeder Eintrag ist eine Meldung.

Meldung. Ein einzelner Beitrag oder Artikel. Ihre Struktur hängt vom Typ ab (Inhaltsblöcke, Bildvarianten, Tracking-Metadaten), deshalb stellt der Client jede Meldung als unverändertes Roh-JsonObject (NewsItem) bereit statt als teilweise geratenen Typ.

Such- & API-Verhalten

Keine Authentifizierung. Die Tagesschau-API ist vollständig offen; dieser Client sendet weder Schlüssel noch Token noch Cookie. Er stellt nur lesende GET-Anfragen.

Rate-Limiting / vorübergehende Fehler. Die API erlaubt etwa 60 Anfragen pro Stunde. Antwortet sie mit einem vorübergehenden Status (429 Too Many Requests, 503 Service Unavailable), wiederholt der Client die Anfrage automatisch, bis zu --max-retries-mal (Standard 2, höchstens 10). Jede Wiederholung wartet 200 ms × Versuch, oder das Retry-After der Antwort (Sekunden oder HTTP-Datum), wenn es länger ist und höchstens 30 s beträgt (MAX_RETRY_AFTER_MS): Retry-After: 0 lässt den Client nie sofort wiederholen. Ein längeres wird nicht wiederholt; der Fehler kommt sofort und nennt die Wartezeit, die der Server verlangt hat.

Weiterleitungen. Der Client folgt bis zu --max-redirects Weiterleitungen (Standard 5). Zugangsdaten in --base-url (https://user:pw@host) gehen als Authorization-Header nur an den Origin der Basis-URL (Schema, Host und Port): Eine Weiterleitung innerhalb desselben Origins behält sie, ob relativ oder absolut; bei einem Sprung auf einen anderen Origin entfernt der Client Header mit Zugangsdaten (Authorization, X-API-Key, Cookie) vor der nächsten Anfrage, damit sie nie an einen unbeabsichtigten Host gelangen. Antwortet das Ziel dann mit 401 oder 403, sagt die Fehlermeldung, dass die Weiterleitung sie entfernt hat (bei http: → https:: eine https:-Basis-URL verwenden). Benutzername oder Passwort im Location einer Weiterleitung werden nie verwendet.

Obergrenze der Antwortgröße. Antworten, die größer als --max-response-bytes sind (Standard 100 MiB; 0 = unbegrenzt), werden abgebrochen – zum Schutz vor Speichererschöpfung durch einen feindseligen oder fehlerhaften Endpoint.

Exit-Codes

Exit-Codes. Die CLI bildet Ergebnisse auf Exit-Codes des Prozesses ab: 0 bei Erfolg; 4 bei einem 404 der API; 1 bei jedem anderen Fehler (API-Fehler, Netzwerkausfall, Unerwartetes); bei Aufruf- bzw. Argumentfehlern ein von null verschiedener Code von commander. --help/--version liefern 0.

Log-Eintrag. Jede Diagnosezeile, die die CLI auf stderr schreibt: ein Zeitstempel, eine Stufe (ERROR, WARN, INFO) und ein Thema tagesschau.<Bereich>, als Text (im Stil von log4j) oder mit --log-format jsonl als ein JSON-Objekt pro Zeile. Die Bereiche: cli (Bedienfehler, Meldungen von commander, unerwartete Fehler), api (die Antworten der API: ein Fehlerstatus, eine fehlerhafte Antwort – kein JSON, die falsche Form, ein unbekannter Zeichensatz – und der Hinweis zur Schreibweise bei der Suche), http (die Verbindung, die Warnung vor unverschlüsseltem http: und je Wiederholung eine WARN-Zeile vor dem Warten) und output (ein fehlgeschlagenes Schreiben auf stdout). Ein Eintrag ist immer eine Zeile; Steuerzeichen darin werden maskiert.

Bibliothek & Interna. Begriffe zum TypeScript-Client und seinen Interna – TagesschauClient, die Request-Engine, Transport, Retry/Backoff, Fehlertypen, Query-Builder – finden Sie in DEVELOPING.md (englisch).