Analytics-API: Umfangsfilter und Daten pro Track

Jede Analytics-Anfrage deckt einen Teil Ihres Katalogs ab, und jede Anfrage liefert genau ein aggregiertes Ergebnis über diesen Teil. Zusammen sorgen diese beiden Punkte regelmäßig für Überraschungen: Filtern Sie einen Aufruf nach dem UPC eines Albums, erhalten Sie die Zahlen des Albums, nicht eine Zeile pro Track darauf. Diese Seite behandelt die Filter, die den Umfang festlegen, die Wirkung der Aggregation auf das Ergebnis und die zwei Endpoints, die einen Umfang Track für Track aufschlüsseln.

Die Umfangsfilter

Vier Filter schränken eine Analytics-Anfrage auf einen Teil Ihres Katalogs ein. Sie funktionieren auf GET /analysen/summary, auf den eigenständigen Serien- und Demografie-Endpoints sowie auf GET /analysen/leaderboards und /analysen/placements.

Filter	Typ	Die Tracks, die er erfasst
filter[release_id]	Ganzzahl	jeder Track dieses Releases
filter[isrc]	Zeichenkette	die eine Aufnahme mit diesem ISRC
filter[upc]	Zeichenkette	jeder Track des Releases mit diesem Barcode
filter[artist_names][]	Array von Zeichenketten	jeder Track in Ihrem Katalog, der diesen Künstlern zugeschrieben ist

GET /analysen/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012

Senden Sie keinen davon, deckt die Anfrage Ihren gesamten zugänglichen Katalog ab: der Standardumfang für jeden Analytics-Aufruf.

Nur ein Filter wirkt

Die vier werden in einer festen Reihenfolge aufgelöst: release_id, dann isrc, dann upc, dann artist_names[]. Der erste vorhandene Filter gewinnt. Senden Sie filter[release_id] und filter[upc] gemeinsam, wird daraus keine Schnittmenge gebildet; der UPC wird schlicht ignoriert. Senden Sie nur den Filter, den Sie meinen.

Wenn die Kennung nicht zu Ihrem Katalog gehört

Die drei Filter auf Release-Ebene reagieren unterschiedlich, wenn sich die Kennung nicht in Ihrem Katalog auflösen lässt:

• filter[release_id] löst einen Fehler aus: 404, wenn kein solches Release existiert, 403, wenn es existiert, aber nicht Ihnen gehört.
• filter[isrc] und filter[upc] lösen zu einem leeren Umfang auf, und die Anfrage ist mit leerem data erfolgreich.

Wenn Sie die API also mit einer Kennung ansteuern, die ein Nutzer eingegeben hat, prüfen Sie auf leeres data, statt auf einen 404 zu warten.

Auf eines Ihrer Labels einschränken

GET /analysen/summary und GET /analysen/leaderboards akzeptieren zusätzlich filter[label_id] und schränken die Anfrage damit auf genau eines Ihrer eigenen Labels ein. Ein unbekanntes Label liefert 404, ein Label, das Ihnen nicht gehört, 403. Der Filter kann den Umfang nur verkleinern; es gibt keinen Wert, der ihn erweitert.

Um stattdessen nach Store einzuschränken, nutzen Sie filter[platform]. Die akzeptierten Werte und die Matrix der Sektionen pro Plattform finden Sie unter Analytics-API: Plattformen, Verfügbarkeit und Limits.

Ein Umfang hinein, eine Serie heraus

Die Serien- und Summary-Sektionen aggregieren über den aufgelösten Umfang. Eine Tagesserie gruppiert nach Datum und Plattform und summiert den Messwert über alle Tracks im Umfang. Wie viele Zeilen Sie zurückbekommen, hängt deshalb davon ab, für wie viele Tage und Plattformen gemeldet wurde, und nie davon, auf wie viele Tracks der Filter gepasst hat.

GET /analysen/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-02&filter[upc]=0123456789012

{
  "data": [
    { "date": "2026-06-01", "platform": "SPOTIFY", "total": 1804 },
    { "date": "2026-06-01", "platform": "DEEZER", "total": 96 },
    { "date": "2026-06-02", "platform": "SPOTIFY", "total": 1731 }
  ]
}

Ein Album mit zwölf Tracks und eine Single liefern beide dieselbe Form. total ist in jeder Zeile die Zahl für den gesamten Umfang an diesem Datum und auf dieser Plattform, und der Wert ist derselbe, ob das Album zwei Tracks hat oder zwanzig.

Die Demografie-Endpoints verhalten sich genauso, nur eine Dimension weiter: /analysen/streams-by-country gruppiert nach Land und summiert über den Umfang. Ein nach UPC gefilterter Aufruf liefert also die Länderaufteilung des Albums, nicht die jedes einzelnen Tracks. Jede Sektion von /analysen/summary folgt derselben Regel, mit zwei benannten Ausnahmen, die weiter unten stehen.

Hinweis

Das ist so gewollt und keine Einschränkung, die es zu umgehen gilt. Über die Anfrage lässt sich daran nichts ändern: Die Serien-Endpoints haben keinen Parameter, der nach Track gruppiert. Zahlen pro Track liefern die beiden Endpoints weiter unten.

Zahlen pro Track abrufen

Was Sie brauchen	Woher es kommt
Alles zu einem einzelnen Track	filter[isrc] auf jedem Analytics-Endpoint
Summen pro Track für einen Zeitraum, als Rangliste	GET /analysen/leaderboards?type=tracks
Tagesserie pro Track	GET /analysen/summary mit metrics[]=track-streams-daily

Summen pro Track: der Leaderboards-Endpoint

GET /analysen/leaderboards sortiert Ihren Katalog nach den summierten Streams im Fenster. Der Endpoint ist das API-Gegenstück zur Karte Top performers im Analytics-Dashboard.

type ist erforderlich und nimmt artists, tracks, albums oder all (alle drei Listen in einer Anfrage). Die Umfangsfilter schränken ihn genauso ein wie eine Serie; type=tracks mit filter[upc] liefert Ihnen also die Tracks dieses Albums und sonst nichts.

GET /analysen/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

Track-Zeilen tragen name, artistName, streams, release_id, identifier (die Plattform-Kennung, oder null, wenn die Zeile mehr als eine umfasst) und isrc (die Aufnahme, zu der die Streams der Zeile gehören). Die Zeilen kommen nach Streams sortiert zurück, die höchste zuerst.

isrc kommt immer dann zurück, wenn die Zeile zweifelsfrei genau einer Aufnahme entspricht. Das gilt auch, wenn mehrere Plattformen dieselbe Aufnahme jeweils mit ihrem eigenen identifier melden, was bei einem Track auf mehr als einem Dienst der Normalfall ist. null steht dort, wo sich nicht belegen lässt, dass die Zeile nur eine Aufnahme abdeckt: bei Abrufen ohne Filter, die nach Namen über Ihren gesamten Katalog sortieren, bei Zeilen, die allein über filter[artist_names][] eingegrenzt sind, und bei Zeilen, in denen derselbe Titel mit demselben Künstler zwei verschiedene Aufnahmen umfasst. Ein null heißt, dass sich dieser Zeile keine eindeutige Aufnahme zuordnen lässt, nicht dass die Aufnahme keinen ISRC hätte. Behandeln Sie isrc und identifier als unabhängig voneinander: Eines von beiden kann null sein, während das andere einen Wert trägt. Und wenn jede Zeile einen ISRC tragen muss, nutzen Sie die Tagessektionen pro Track weiter unten.

Zwei Limits, die Sie einplanen sollten:

• limit steht standardmäßig auf 10 und darf 50 nicht überschreiten. Ein Album mit mehr als 50 Tracks lässt sich über diesen Endpoint nicht vollständig auflisten. Nutzen Sie dafür die Tagessektionen pro Track und summieren Sie die Zeilen selbst.
• Das Fenster darf 180 Tage nicht überschreiten, enger als die 400 Tage, die die Serien-Endpoints erlauben. Mehrere kürzere Fenster aneinanderzureihen ergibt keine längere Rangliste, denn die Top Ten jedes Monats sind nicht die Top Ten des Quartals.

Tagesserien pro Track: zwei Summary-Sektionen

GET /analysen/summary trägt zwei Sektionen, die jeden Track einzeln melden statt der Summe über das ganze Release:

Sektion	Zeilenform	Gemeldet von
track-streams-daily	{ date, platform, isrc, streams }	alle Plattformen
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music und Amazon Music

Beide sind optional zuschaltbar: Sie werden nur berechnet, wenn Sie sie in metrics[] nennen, und beide setzen filter[release_id], filter[isrc] oder filter[upc] voraus. Nennen Sie eine dieser Sektionen ohne Release- oder Track-Filter, kommt ein 422 zurück, dessen Fehler an metrics hängt. Ein Filter auf Künstlernamen erfüllt die Voraussetzung nicht.

Die Zeilen sind nach Datum, dann Plattform, dann ISRC sortiert, und ein Tag ohne Aktivität trägt gar keine Zeile statt einer Null. Hörerzahlen sind Tageswerte und lassen sich nicht über mehrere Tage aufsummieren: Dieselbe Person, die an zwei Tagen hört, ist an jedem der beiden Tage ein Hörer.

Achtung

Eine Anfrage, deren Produkt aus Tracks × Tagen × Plattformen zu groß wird, liefert 422 mit der Aufforderung, den Datumsbereich zu verkleinern, filter[platform] zu setzen oder mit filter[isrc] auf einen einzelnen Track zu filtern. Der Bereich wird abgelehnt statt gekürzt, damit nie eine unvollständige Serie in Ihren Diagrammen landet und dort vollständig aussieht.

Beispiel: Streams pro Track für ein Album

Sie haben ein Album mit dem UPC 0123456789012 und möchten die Juni-Zahlen nach Track aufgeschlüsselt sehen.

Für eine Rangliste der Summen pro Track fragen Sie beim Leaderboards-Endpoint die Tracks des Albums ab:

GET /analysen/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

{
  "data": [
    { "name": "Nine Roses", "artistName": "Wiguez", "streams": 41208, "release_id": 88213, "identifier": "3n2f9xk2p1", "isrc": "USABC2600001" },
    { "name": "Harbour Lights", "artistName": "Wiguez", "streams": 18740, "release_id": 88213, "identifier": "7b1q4mz8v2", "isrc": "USABC2600002" }
  ],
  "meta": { "type": "tracks", "start_date": "2026-06-01", "end_date": "2026-06-30", "limit": 50 }
}

Für die Tag-für-Tag-Serie jedes Tracks fragen Sie beim Summary-Endpoint die Sektion pro Track ab:

GET /analysen/summary?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&metrics[]=track-streams-daily

{
  "data": {
    "track-streams-daily": [
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600001", "streams": 1412 },
      { "date": "2026-06-01", "platform": "DEEZER", "isrc": "USABC2600001", "streams": 78 },
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600002", "streams": 392 }
    ]
  }
}

Ergänzen Sie denselben Aufruf um metrics[]=track-listeners-daily, um neben den Streams auch die Hörer zu erhalten. Und wenn Sie nur an einem Track des Albums interessiert sind, lassen Sie den UPC weg und übergeben stattdessen den filter[isrc] dieses Tracks: Jeder Analytics-Endpoint meldet dann ausschließlich zu dieser Aufnahme.

Verwandt

• Analytics-API: Plattformen, Verfügbarkeit und Limits — welche Plattformen welche Metriken melden, die Meldekadenz und die Datumsbereichs-Limits
• API-Überblick und Schnellstart — Authentifizierung, Sandbox und die vollständige Endpoint-Referenz
• Analytics — dieselben Daten im Dashboard
• Ihren KI-Assistenten mit LabelGrid verbinden (MCP) — fragen Sie Ihre Analytics in natürlicher Sprache ab