{ "openapi": "3.0.3", "info": { "title": "RadioAPI v1 (JSON & XML)", "description": "Öffentliche, unauthentifizierte v1-Schnittstelle von radioapi.de. Alle Endpunkte liefern wahlweise JSON (`/v1/json/...`) oder XML (`/v1/xml/...`) und senden offene CORS-Header (`Access-Control-Allow-Origin: *`). Es gibt keine einheitliche Fehler-/Hüllenstruktur über alle Endpunkte hinweg - viele Endpunkte sind historisch gewachsen und verhalten sich bewusst leicht unterschiedlich (siehe jeweilige Beschreibung).\n\nNetzwerk-Shortcuts: Für `stationData`, `songHistory`, `showSchedule`, `newSongs`, `genres` und `events` gibt es neben dem generischen `?network=` Query-Parameter auch feste Pfad-Aliasse für die drei Haupt-Netzwerke, die serverseitig per nginx-Rewrite auf `?network=` gemappt werden: `lionfm` → network=1, `rbcs` → network=2, `linefm` → network=3 (z. B. `/v1/json/lionfm/stationData` ≡ `/v1/json/stationData?network=1`). Diese Aliasse existieren nur für die genannten Endpunkte und sind unten aus Übersichtlichkeit nicht als eigene Pfade modelliert - der Query-Parameter `network` ist der eigentliche, vollständige Vertrag.", "version": "1.2.0" }, "servers": [ { "url": "https://radioapi.de" } ], "tags": [ { "name": "JSON", "description": "Endpunkte unter /v1/json" }, { "name": "XML", "description": "Endpunkte unter /v1/xml" } ], "paths": { "/v1/json/stationData": { "get": { "tags": [ "JSON" ], "summary": "Stationsdaten inkl. aktuellem Titel", "description": "Ohne Parameter werden alle sichtbaren Stationen zurückgegeben. Die Antwort ist standardmäßig ein Objekt, dessen Schlüssel die Stations-ID ist (interne `id`, oder bei gesetztem `network` die netzwerk-lokale `ext_id`) - kein Array. Mit `array=1` wird stattdessen ein einfaches JSON-Array derselben Objekte geliefert (nur JSON; die XML-Variante kennt diesen Parameter zwar, er hat dort aber keine Wirkung).", "parameters": [ { "name": "network", "in": "query", "description": "Netzwerk-ID. Schaltet die Antwort-Schlüssel von der internen `id` auf die netzwerk-lokale `ext_id` um und aktiviert für network=1 (LionFM) das zusätzliche `cover`-Feld in `now_playing`.", "schema": { "type": "integer" } }, { "name": "station", "in": "query", "description": "Stations-ID (interne `id`, oder bei gesetztem `network` die `ext_id`). Alias für `stationID`.", "schema": { "type": "integer" } }, { "name": "stationID", "in": "query", "description": "Wie `station`; hat Vorrang, falls beide gesetzt sind.", "schema": { "type": "integer" } }, { "name": "genre", "in": "query", "description": "Netzwerk-lokale Genre-ID (siehe `/v1/json/genres`). Filtert Stationen eines Netzwerks nach Genre (benötigt zusätzlich `network`). Wird ignoriert, wenn `station`/`stationID` gesetzt ist.", "schema": { "type": "integer" } }, { "name": "topStations", "in": "query", "description": "1 = alle Stationen des Netzwerks, Top-Stationen zuerst sortiert. 2 = nur als Top-Station markierte Stationen. Benötigt `network`; wird ignoriert, wenn `station`/`stationID` oder `genre` gesetzt ist.", "schema": { "type": "integer", "enum": [ 1, 2 ] } }, { "name": "array", "in": "query", "description": "1 = Antwort als JSON-Array statt als nach Stations-ID geschlüsseltes Objekt. Nur in der JSON-Variante wirksam.", "schema": { "type": "integer", "enum": [ 1 ] } }, { "name": "textFormat", "in": "query", "description": "Formatierung von `artist`/`title` in `now_playing`. 0 oder nicht gesetzt = Großschreibung (Default), 1 = Großschreibung (explizit), 2 = unverändert, 3 = Kleinschreibung.", "schema": { "type": "integer", "enum": [ 0, 1, 2, 3 ] } } ], "responses": { "200": { "description": "Stationsdaten, standardmäßig als Objekt (Schlüssel = Stations-ID), mit `array=1` als Array.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StationData" } }, { "type": "array", "items": { "$ref": "#/components/schemas/StationData" } } ] } } } } } } }, "/v1/json/songHistory": { "get": { "tags": [ "JSON" ], "summary": "Playlist-Verlauf (gesendete Titel)", "description": "Ohne jegliche Parameter: letzte 10 Titel der Station mit `id=1` der letzten Stunde. Mit Parametern: `from`/`till` als `HH:MM` oder `HH:MM:SS`, oder beide `'latest'` für ein rollendes ±1h-Fenster um jetzt. `date` grenzt zusätzlich auf einen Kalendertag ein (Default: heute). Nur Einträge mit `type='Musik'` (bzw. NULL) werden berücksichtigt.", "parameters": [ { "name": "from", "in": "query", "description": "Startzeit `HH:MM` oder `HH:MM:SS`, oder `'latest'`.", "schema": { "type": "string" } }, { "name": "till", "in": "query", "description": "Endzeit `HH:MM` oder `HH:MM:SS`, oder `'latest'`.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "description": "Kalendertag im Format YYYY-MM-DD. Default: heute.", "schema": { "type": "string", "format": "date" } }, { "name": "station", "in": "query", "description": "Stations-ID (interne `id`, oder bei gesetztem `network` die `ext_id`).", "schema": { "type": "integer" } }, { "name": "network", "in": "query", "description": "Netzwerk-ID. Schaltet `station` auf netzwerk-lokale Auflösung um und aktiviert für network=1 das `cover`-Feld.", "schema": { "type": "integer" } }, { "name": "textFormat", "in": "query", "description": "Formatierung von `artist`/`title`. 0/nicht gesetzt und 1 = Großschreibung, 2 = unverändert, 3 = Kleinschreibung.", "schema": { "type": "integer", "enum": [ 0, 1, 2, 3 ] } } ], "responses": { "200": { "description": "Liste der gesendeten Titel, neueste zuerst.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SongHistoryEntry" } } } } }, "404": { "description": "Die per `network`+`station` angegebene Kombination existiert nicht.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } } } }, "/v1/json/allListeners": { "get": { "tags": [ "JSON" ], "summary": "Summe der aktuellen Hörerzahlen", "description": "Liefert direkt eine JSON-Zahl zurück - kein Objekt/Array als Hülle.", "parameters": [ { "name": "network", "in": "query", "description": "Eine oder mehrere (kommagetrennte) Netzwerk-IDs, z. B. `1,2,3`. Ohne Angabe wird über alle sichtbaren Stationen summiert.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Summe der `listeners`-Werte aller passenden, nicht versteckten Stationen.", "content": { "application/json": { "schema": { "type": "integer" }, "example": 4231 } } } } } }, "/v1/json/showSchedule": { "get": { "tags": [ "JSON" ], "summary": "Sendeplan", "parameters": [ { "name": "stationID", "in": "query", "description": "Interne Stations-ID (`rgde_stations.id`).", "schema": { "type": "integer" } }, { "name": "network", "in": "query", "description": "Netzwerk-ID.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Liste aller passenden Sendungen inkl. etwaiger Absagen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowScheduleResponse" } } } }, "500": { "description": "Interner Fehler.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/json/newSongs": { "get": { "tags": [ "JSON" ], "summary": "Manuell im ACP als \"neu\" markierte Songs", "description": "`stations` enthält bei jedem Song immer alle zugeordneten Sender, unabhängig vom per `stationID`/`network` gesetzten Filter - der Filter wirkt nur auf die Auswahl der Songs selbst.", "parameters": [ { "name": "stationID", "in": "query", "description": "Interne Stations-ID. Filtert Songs, die (unter anderem) diesem Sender zugeordnet sind.", "schema": { "type": "integer" } }, { "name": "network", "in": "query", "description": "Netzwerk-ID. Filtert Songs, die (unter anderem) einem Sender dieses Netzwerks zugeordnet sind.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Liste neuer Songs, neueste zuerst.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSongsResponse" } } } }, "500": { "description": "Interner Fehler.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/json/genres": { "get": { "tags": [ "JSON" ], "summary": "Genres (redaktionelle Kategorien) eines Netzwerks", "description": "Im RadioACP unter Sender → Genres gepflegt. `genre_id` ist netzwerk-lokal (jedes Netzwerk vergibt eigene IDs) und entspricht `?genre=` sowie dem Feld `genres` in `stationData`. Sortiert nach `sort_order`. Ausgeblendete Genres (`hidden: true`, z. B. saisonal) sind enthalten, sollen aber nicht als Filter angezeigt werden.", "parameters": [ { "name": "network", "in": "query", "description": "Netzwerk-ID. Ohne Angabe werden die Genres aller Netzwerke geliefert. Alternativ als Pfad: `/v1/{json|xml}/1/genres` bzw. `/v1/{json|xml}/lionfm/genres`.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Genre-Liste.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreListResponse" } } } }, "500": { "description": "Interner Fehler.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/json/events": { "get": { "tags": [ "JSON" ], "summary": "Events pro Sender", "description": "Veranstaltungen (z. B. RadioAid), im RadioACP unter Sendeplan → Events pro Sender gepflegt. Sortiert nach Datum und Startzeit. Events versteckter Sender werden nicht ausgeliefert.", "parameters": [ { "name": "stationID", "in": "query", "description": "Interne Stations-ID – nur Events dieses Senders.", "schema": { "type": "integer" } }, { "name": "network", "in": "query", "description": "Netzwerk-ID. Alternativ als Pfad: `/v1/{json|xml}/1/events` bzw. `/v1/{json|xml}/lionfm/events`.", "schema": { "type": "integer" } }, { "name": "include_past", "in": "query", "description": "`1` = auch vergangene Events. Standard: nur Events, deren (End-)Datum heute oder später ist.", "schema": { "type": "integer", "enum": [ 1 ] } } ], "responses": { "200": { "description": "Event-Liste.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" } } } }, "500": { "description": "Interner Fehler.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/json/listenerCounter": { "get": { "tags": [ "JSON" ], "summary": "Legacy-Hörerzähler (Cron-artiger Seiteneffekt-Endpunkt)", "description": "**Legacy/Altlast, nicht für neue Integrationen gedacht.** Jeder Aufruf fragt live die laut.fm-API für eine fest hinterlegte Liste von Sendern ab, schreibt die Hörerzahlen in `rgde_stations` zurück und überschreibt zwei statische Cache-Dateien (`listenerCounter.json`, `listenerCounterArray.json`) auf dem Server. Die zurückgegebenen Schlüssel (`station-1`, `station-2`, ...) entsprechen fest verdrahteten internen Stations-/Gruppen-IDs und sind nicht generisch erweiterbar. Kein Parameter.", "parameters": [], "responses": { "200": { "description": "Aktuelle Summen-Hörerzahlen je (teils zu Gruppen zusammengefasster) Station.", "content": { "application/json": { "schema": { "type": "object", "description": "Feste Schlüsselmenge: `all` (Gesamtsumme) sowie `station-1`, `station-2`, `station-3`, `station-4`, `station-5`, `station-6`, `station-7`, `station-8`, `station-9`, `station-10`, `station-11`, `station-12`, `station-13`, `station-15`, `station-17` (jeweils `{\"listeners\": number}`).", "properties": { "all": { "type": "integer" } }, "additionalProperties": { "type": "object", "properties": { "listeners": { "type": "integer" } } } } } } } } } }, "/v1/json/status": { "get": { "tags": [ "JSON" ], "summary": "Statischer Backend-Status (legacy, geschützt)", "description": "**Legacy/Altlast.** Erfordert den Query-Parameter `secKey` mit einem fest im Code hinterlegten Geheimwert. Bei falschem oder fehlendem `secKey` liefert der Endpunkt einen leeren Response-Body ohne Fehlermeldung oder angepassten Statuscode. Die zurückgegebenen Daten sind vollständig statisch im Code hinterlegt (kein echter Backend-Health-Check) und sollten nicht als Live-Status missverstanden werden.", "security": [ { "secKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Statische Liste von Sendern mit (fest hinterlegtem) Status. Bei falschem/fehlendem secKey: leerer Body.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "station": { "type": "object", "properties": { "name": { "type": "string" }, "backend_running": { "type": "boolean" }, "backend_info": { "type": "string", "description": "Meist leer; bei Backup-Sendern Name des primären Backends." } } } } } } } } } } } }, "/v1/xml/stationData": { "get": { "tags": [ "XML" ], "summary": "Stationsdaten inkl. aktuellem Titel (XML)", "description": "XML-Gegenstück zu `/v1/json/stationData`. Unterstützt dieselben Parameter mit derselben Bedeutung, **außer** `array`: Dieser Parameter wird zwar entgegengenommen, hat in der XML-Variante aber keine Wirkung - die Antwort ist immer eine flache Liste von ``-Elementen unter dem Wurzelelement ``, nie ein geschlüsseltes Objekt (XML kennt dieses Konzept ohnehin nicht). Die Genre-Zuordnung steht je Sender in `…`.", "parameters": [ { "name": "network", "in": "query", "schema": { "type": "integer" } }, { "name": "station", "in": "query", "schema": { "type": "integer" } }, { "name": "stationID", "in": "query", "schema": { "type": "integer" } }, { "name": "genre", "in": "query", "schema": { "type": "integer" }, "description": "Netzwerk-lokale Genre-ID (siehe `/v1/xml/genres`), benötigt `network`." }, { "name": "topStations", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2 ] } }, { "name": "array", "in": "query", "description": "Wird angenommen, aber ohne Wirkung (siehe Beschreibung).", "schema": { "type": "integer" } }, { "name": "textFormat", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1, 2, 3 ] } } ], "responses": { "200": { "description": "`......`", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/v1/xml/songHistory": { "get": { "tags": [ "XML" ], "summary": "Playlist-Verlauf (XML)", "description": "XML-Gegenstück zu `/v1/json/songHistory`, identisches Verhalten/Parameter. Wurzelelement `` mit einer Liste von ``-Elementen.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "till", "in": "query", "schema": { "type": "string" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "station", "in": "query", "schema": { "type": "integer" } }, { "name": "network", "in": "query", "schema": { "type": "integer" } }, { "name": "textFormat", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1, 2, 3 ] } } ], "responses": { "200": { "description": "`