API-Dokumentation – TKKG Metadaten

Endpunkt

GET /Serie.json

Vollständiger Datensatz aller Folgen. Keine Authentifizierung erforderlich. Content-Type: application/json, Encoding: UTF-8.

Toplevel-Struktur

Feld	Typ	Pflicht	Beschreibung
dbInfo	object	✓	Metadaten zur Datenbank (Version, Datum, Quelle)
serie	array	✓	Liste aller Folgen, aufsteigend nach Nummer sortiert

dbInfo

Feld	Typ	Pflicht	Beschreibung
version	string	✓	SemVer-Versionsnummer der Datenbank
lastModified	string	✓	ISO 8601 Zeitstempel der letzten Änderung (UTC)
source	string	✓	URL der primären Datenquelle

serie[]

Feld	Typ	Pflicht	Beschreibung
nummer	integer	✓	Folgenummer (1-basiert, eindeutig)
titel	string	✓	Titel der Folge
beschreibung	string	✓	Inhaltsangabe; `\n` als Absatztrenner möglich
kapitel	array	✓	Kapitel / Trackliste → kapitel[]
sprechrollen	array	✓	Besetzungsliste → sprechrollen[]
regie	string	✓	Name der Regisseurin / des Regisseurs
hörspielskriptautor	string	✓	Autor der Hörspielbearbeitung
veröffentlichungsjahr	integer	✓	Jahr der Erstveröffentlichung
produktion	object	✓	Key-Value-Paare aus dem Booklet → produktion
coverUrl	string	✓	Absolute URL zum Cover-Bild (JPEG, ~600×600 px)

serie[].kapitel[]

Feld	Typ	Pflicht	Beschreibung
nummer	integer	✓	Kapitelnummer (1-basiert, je Folge)
titel	string	✓	Titel des Kapitels

serie[].sprechrollen[]

Eine Sprecherin / ein Sprecher kann mehrere Rollen übernehmen und daher mehrfach erscheinen. Mehrere Rollen eines Eintrags werden mit / getrennt.

Feld	Typ	Pflicht	Beschreibung
rolle	string	✓	Figurenname(n), z. B. `"Tim / Tarzan / Peter Carsten"`
sprecher	string	✓	Name der Sprecherin / des Sprechers

serie[].produktion

Freies Key-Value-Objekt mit Produktionsangaben aus dem physischen Booklet. Die Schlüssel entsprechen den Originalbezeichnungen und können je Folge variieren.

{
  "Produktion und Regie":        "Heikedine Körting",
  "Hörspielbearbeitung":         "H.G. Francis",
  "TKKG - Die Profis in spe":    "Bonda/Büscher",
  "Künstlerische Gesamtleitung": "Prof. Dr. Beurmann",
  "Design":                      "Atelier Schoedsack",
  "Illustration":                "Reiner Stolte"
}

Beispiele

const { dbInfo, serie } = await fetch('/Serie.json')
  .then(r => r.json());

// Alle Folgen eines Jahres filtern
const folgen1982 = serie.filter(
  f => f.veröffentlichungsjahr === 1982
);

// Sprecher einer bestimmten Folge ausgeben
const folge = serie.find(f => f.nummer === 1);
folge.sprechrollen.forEach(s =>
  console.log(s.rolle, '→', s.sprecher)
);

import httpx

data = httpx.get("https://<host>/Serie.json").json()

# Alle Folgen nach Erscheinungsjahr auflisten
for f in data["serie"]:
    print(f"{f['nummer']:>4}. {f['titel']} ({f['veröffentlichungsjahr']})")

# Sprecher einer Folge ausgeben
folge = next(f for f in data["serie"] if f["nummer"] == 1)
for s in folge["sprechrollen"]:
    print(f"{s['rolle']:40} {s['sprecher']}")

# Alle Titel ausgeben
curl -s https://<host>/Serie.json \
  | jq '[.serie[] | {nummer, titel}]'

# Folgen eines bestimmten Jahres filtern
curl -s https://<host>/Serie.json \
  | jq '[.serie[] | select(.veröffentlichungsjahr==1982) | .titel]'

Versionierung

Die aktuelle Version steht in dbInfo.version (SemVer).

Änderungstyp	Version
Neue Folgen hinzugefügt	PATCH (x.y.Z)
Neue Felder hinzugefügt	MINOR (x.Y.z)
Felder umbenannt / entfernt	MAJOR (X.y.z)