Analytics-API: Plattformen, Verfügbarkeit und Limits

Die öffentliche LabelGrid-API liefert Streaming-Analytics über GET /analysen/summary (ein zusammengesetzter Endpoint, der die von Ihnen gewählten Sektionen zurückgibt) und eigenständige Serien-Endpoints wie GET /analysen/streams. Diese Seite behandelt die Plattform-Menge, die Ermittlung dessen, was jede Plattform meldet, die Meldekadenz und die Anfrage-Limits.

Unterstützte Plattformen

filter[platform] akzeptiert zehn Werte für neun Stores:

SPOTIFY, APPLE_MUSIC (ITUNES wird als Alias für denselben Store akzeptiert), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Lassen Sie filter[platform] weg, um die kombinierte Ansicht über alle Plattformen zu erhalten, für die Ihr Konto Daten hat.

Verfügbarkeit ermitteln: GET /analysen/availability

Nicht jede Plattform meldet jede Metrik. Der Verfügbarkeits-Discovery-Endpoint liefert das Gesamtbild in einem Aufruf:

GET /analysen/availability

{
  "data": {
    "sections": ["streams", "listeners", "saves", ...],
    "platforms": ["SPOTIFY", "APPLE_MUSIC", "DEEZER", "BOOMPLAY", "AWA", "AUDIOMACK", "KUGOU", "KUWO", "QQMUSIC"],
    "availability": {
      "streams": { "SPOTIFY": "available", "KUGOU": "available" },
      "listeners": { "SPOTIFY": "available", "KUGOU": "not_available_for_platform" }
    },
    "platform_cadence": { "SPOTIFY": "daily", "KUGOU": "weekly" }
  }
}

• sections — jeder Analytics-Sektions-Key in kanonischer Reihenfolge. Diese Liste ist maßgeblich: Es ist dieselbe Menge, die metrics[] auf /analysen/summary akzeptiert.
• platforms — jeder Wert, den filter[platform] akzeptiert.
• availability — nach Sektion, dann nach Plattform indiziert. Jede Zelle ist available oder not_available_for_platform.
• platform_cadence — daily oder weekly pro Plattform (siehe Meldekadenz).

Die Antwort ist statische Konfiguration — sie hängt weder von Ihrem Konto noch von einem Datumsbereich oder Filter ab — holen Sie sie einmal und cachen Sie sie. Der Endpoint nimmt keine Parameter und nutzt dieselbe Authentifizierung und dieselben Rate-Limits wie die anderen /analysen/*-Endpoints.

Das availability-Feld bei gefilterten Anfragen

Wenn Sie eine Analytics-Anfrage nach einer einzelnen Plattform filtern (etwa filter[platform]=DEEZER), trägt die Antwort zusätzlich ein availability-Feld neben data:

• available — die Plattform meldet diese Metrik; data ist normal befüllt.
• not_available_for_platform — die Plattform meldet diese Metrik nicht; data ist leer. Das ist erwartetes Verhalten, kein Fehler.

Eigenständige Endpoints tragen einen einzelnen Top-Level-Wert; /analysen/summary trägt eine Map mit einem Eintrag pro angefragter Sektion. Anfragen ohne Plattform-Filter tragen kein availability-Feld. Lesen Sie immer availability, bevor Sie ein leeres data als „keine Aktivität” interpretieren.

Was die Plattformen melden

Die Matrix auf einen Blick (rufen Sie den Endpoint für die maßgebliche, aktuelle Version auf):

Sektionen	Meldende Plattformen
streams	Alle neun Plattformen
listeners	SPOTIFY, APPLE_MUSIC, AUDIOMACK
saves	SPOTIFY, AUDIOMACK
skips, shares, completion-rate, lyrics-view-rate, canvas-view-rate, device-split, source-split, saves-by-tier, shares-by-country	SPOTIFY
streams-by-country	SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AUDIOMACK
streams-by-gender, streams-by-age	SPOTIFY, APPLE_MUSIC
library-adds, playlist-adds, shazams, shazams-by-city, shazams-by-state, Apple-Dimensions-Sektionen	APPLE_MUSIC
Listener-Audience-Zusammensetzung und Per-Stream-Sektionen (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /analysen/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Ein Hinweis zur Listener-Semantik: Spotify und Apple Music melden eine deduplizierte tägliche Hörerzahl pro Track. Die tägliche Audiomack-Zahl ist die Summe der pro Land und Abo-Stufe gemeldeten Hörerzahlen — ein Hörer, der am selben Tag in mehr als einem Segment aktiv ist, zählt also mehrfach.

Meldekadenz: tägliche und wöchentliche Plattformen

Jede GET /analysen/summary-Antwort trägt eine meta.platform_cadence-Map, die angibt, wie oft jede Plattform meldet:

• daily — ein Bericht pro Tag: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — ein Bericht pro Woche: KUGOU, KUWO, QQMUSIC

Eine wöchentliche Plattform erzeugt einen Datenpunkt pro Track und Woche, datiert auf den Tag, den der Bericht abdeckt, mit der Summe der ganzen Woche. Die Summe wird nie auf die sieben Tage verteilt. In einer Tagesserie sehen Sie eine befüllte Datumszeile pro Woche, ohne Zeilen an den Tagen dazwischen.

Behandeln Sie das im Consumer, indem Sie platform_cadence lesen, statt die Kadenz aus dem Abstand der Daten abzuleiten:

• Behandeln Sie die Lücke zwischen zwei Wochenpunkten nicht als fehlende Daten.
• Teilen Sie einen Wochenpunkt nicht in einen Tagesdurchschnitt auf.
• Das Aufsummieren der Punkte, wie sie sind, ergibt weiterhin die korrekte Summe jedes Bereichs.

Die Kadenz ist von meta.section_granularity zu unterscheiden, das angibt, wie die Punkte einer zurückgegebenen Serie datiert sind (day oder week). Eine Antwort kann gleichzeitig die Granularität "day" und die Kadenz "weekly" tragen — tagesdatierte Punkte, einer pro Woche.

Sektionen auswählen: metrics[] auf /analysen/summary

metrics[] ist auf GET /analysen/summary erforderlich: Nennen Sie die gewünschten Sektionen, von 1 bis 12 pro Anfrage.

GET /analysen/summary?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&metrics[]=streams&metrics[]=listeners

Mehr als 12 Keys anzufragen liefert ein 422 mit der Aufforderung, die Auswahl aufzuteilen. Jede Projektion wird unabhängig pro Umfang und Fenster gecacht, sodass das Aufteilen einer größeren Auswahl in mehrere Anfragen bei wiederholten Aufrufen günstig ist. Die gültigen Sektions-Keys sind die sections-Liste aus GET /analysen/availability; eine ungültige metrics[]-Anfrage zählt sie zudem in ihrer Fehlermeldung auf.

Datumsbereichs-Limits

GET /analysen/summary und die eigenständigen Serien- und Demografie-Endpoints akzeptieren einen Datumsbereich von bis zu 400 Tagen — genug für ein volles Jahr plus einen Vergleichszeitraum in einer Anfrage. Ein Bereich über dem Limit liefert einen 422, dessen Fehlermeldung das Limit nennt.

Endpoint-Familie	Maximaler Bereich
/analysen/summary und eigenständige Serien-/Demografie-Endpoints	400 Tage
/analysen/leaderboards, /analysen/placements	180 Tage

Die Ranking-Endpoints behalten ihr eigenes 180-Tage-Limit — und beachten Sie, dass das Kombinieren mehrerer kürzerer Top-N-Fenster nicht die Top-N über den längeren Zeitraum rekonstruiert.

Zwei weitere Verhaltensweisen kommen mit dem 400-Tage-Fenster:

• Anfragen über mehr als 90 Tage werden gegen ein zweites, niedrigeres Rate-Limit gezählt, zusätzlich zum Standard-Analytics-Limit (30/Minute pro Konto gegenüber standardmäßig 60; die Budgets pro Partner-Egress-IP werden ebenso halbiert). Anfragen von 90 Tagen oder weniger sind nicht betroffen. Das Überschreiten eines der beiden Limits liefert 429 mit den üblichen Retry-After- und X-RateLimit-*-Headern.
• Ein Bereich innerhalb des Limits kann trotzdem zu schwer zu berechnen sein — etwa ein sehr großer Katalog über das volle Fenster mit vielen metrics[]. Das liefert 422 mit einer „Datumsbereich verkleinern”-Meldung. Behandeln Sie es als wiederholbar: Versuchen Sie es mit einem kürzeren Bereich oder weniger Sektionen erneut. Ein unabhängiger Serverfehler liefert weiterhin 500 — ein 422 hier bedeutet also verlässlich „diese Anfrage war zu groß”.

Verwandt

• API-Überblick — Authentifizierung, Endpoints und die vollständige Referenz <<<<<<< HEAD
• Analytics — das Analytics-Dashboard und was jeder Tab zeigt =======
• Analytics — das Analytics-Dashboard und was jede Ansicht zeigt
• Ihren KI-Assistenten mit LabelGrid verbinden (MCP) — fragen Sie Ihre Analytics in natürlicher Sprache ab

origin/main