Analytics-API: scopefilters en data per track

Elk analytics-verzoek bestrijkt een deel van je catalogus, en elk verzoek geeft één geaggregeerd resultaat over dat deel terug. Die twee feiten samen zorgen voor verwarring: filter je een aanroep op de UPC van een album, dan krijg je de cijfers van het album, niet een rij per track. Deze gids behandelt de filters die de scope bepalen, wat het aggregeren met het resultaat doet, en de twee endpoints die een scope alsnog per track uitsplitsen.

De scopefilters

Vier filters beperken een analytics-verzoek tot een deel van je catalogus. Ze werken op GET /analytics/summary, op de losse serie- en demografie-endpoints en op GET /analytics/leaderboards en /analytics/placements.

Filter	Type	De tracks die het oplevert
filter[release_id]	integer	elke track op die release
filter[isrc]	string	de ene opname met die ISRC
filter[upc]	string	elke track op de release met die barcode
filter[artist_names][]	array van strings	elke track in je catalogus die aan die artiesten is toegeschreven

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

Stuur je er geen enkele mee, dan bestrijkt het verzoek de hele catalogus waar je toegang toe hebt: de standaardscope van elke analytics-aanroep.

Er telt maar één filter

De vier worden in een vaste volgorde afgehandeld: eerst release_id, dan isrc, dan upc, dan artist_names[]. Het eerste filter dat aanwezig is, wint. filter[release_id] en filter[upc] samen meesturen combineert ze niet tot een doorsnede; de UPC wordt genegeerd. Stuur alleen het filter dat je bedoelt.

Wat er gebeurt als de identifier niet van jou is

De drie filters op releaseniveau reageren verschillend als de identifier niets in je catalogus oplevert:

• filter[release_id] geeft een fout: 404 als de release niet bestaat, 403 als hij bestaat maar niet van jou is.
• filter[isrc] en filter[upc] leveren een lege scope op, en het verzoek slaagt met een lege data.

Bouw je de aanroep op een identifier die een gebruiker heeft ingetypt, controleer dan op een lege data in plaats van op een 404 te wachten.

Beperken tot één van je labels

GET /analytics/summary en GET /analytics/leaderboards accepteren daarnaast filter[label_id], dat het verzoek beperkt tot één van je eigen labels. Een onbekend label geeft 404, een label dat niet van jou is geeft 403. Het kan je scope alleen beperken: er is geen waarde die hem verruimt.

Wil je in plaats daarvan op platform beperken, gebruik dan filter[platform]. Zie Analytics-API: platformen, beschikbaarheid en limieten voor de geaccepteerde waarden en de matrix van secties per platform.

Eén scope erin, één reeks eruit

De serie- en summary-secties aggregeren over de scope die het filter oplevert. Een dagelijkse reeks groepeert op datum en platform en telt de meetwaarde op over elke track in die scope. Hoeveel rijen je terugkrijgt, hangt dus af van hoeveel datums en platformen hebben gerapporteerd, nooit van hoeveel tracks het filter raakte.

GET /analytics/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 }
  ]
}

Een album met twaalf tracks en een single geven allebei deze vorm terug. De total op elke rij is het cijfer van de hele scope voor die datum en dat platform, en die waarde is hetzelfde of het album nu twee tracks heeft of twintig.

De demografie-endpoints doen hetzelfde, maar dan één dimensie verder: /analytics/streams-by-country groepeert op land en telt op over de scope, dus een op UPC gefilterde aanroep geeft de landenverdeling van het album en niet die van elke track apart. Elke sectie van /analytics/summary volgt dezelfde regel, op twee genoemde uitzonderingen na die hieronder aan bod komen.

Opmerking

Dit is bewust zo, geen beperking die je moet omzeilen. Niets in het verzoek verandert eraan: er is geen “group by track”-parameter op de serie-endpoints. Cijfers per track haal je uit de twee endpoints hieronder.

Cijfers per track ophalen

Wat je wilt	Waar je het haalt
Alles voor één track	filter[isrc] op elk analytics-endpoint
Totalen per track over een periode, gerangschikt	GET /analytics/leaderboards?type=tracks
Dagelijkse reeks per track	GET /analytics/summary met metrics[]=track-streams-daily

Totalen per track: het leaderboards-endpoint

GET /analytics/leaderboards rangschikt je catalogus op de opgetelde streams over het venster. Het is het API-equivalent van de kaart Top performers in het analytics-dashboard.

type is verplicht en accepteert artists, tracks, albums of all (alle drie de lijsten in één verzoek). De scopefilters beperken het endpoint precies zoals ze een reeks beperken, dus type=tracks met filter[upc] geeft je de tracks van dat album en verder niets.

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

Trackrijen bevatten name, artistName, streams, release_id, identifier (de platform-identifier, of null als de rij meer dan één platform beslaat) en isrc (de opname waar de streams van die rij bij horen). De rijen komen terug op streams gesorteerd, hoogste eerst.

isrc komt mee zodra de rij onmiskenbaar één opname betreft, ook als meerdere platformen diezelfde opname elk onder hun eigen identifier rapporteren: dat is het normale beeld bij een track die op meer dan één dienst staat. Het veld is null als niet aan te tonen valt dat de rij één opname beslaat: bij aanroepen zonder filter, die je hele catalogus op naam rangschikken; bij rijen die alleen met filter[artist_names][] zijn afgebakend; en bij rijen waarin dezelfde titel met dezelfde artiest twee verschillende opnames omvat. Een null betekent dat die rij geen eenduidige opname heeft om aan te koppelen, niet dat de opname geen ISRC heeft. Behandel isrc en identifier los van elkaar: de een kan null zijn terwijl de ander een waarde heeft. Moet elke rij een ISRC hebben, gebruik dan de dagelijkse secties per track hieronder.

Twee limieten om rekening mee te houden:

• limit staat standaard op 10 en kan niet hoger dan 50. Een album met meer dan 50 tracks krijg je via dit endpoint niet compleet in beeld; gebruik dan de dagelijkse secties per track en tel de rijen zelf op.
• Het venster mag niet groter zijn dan 180 dagen, krapper dan de 400 dagen die de serie-endpoints toestaan. Meerdere kortere vensters aan elkaar plakken reconstrueert geen langere ranglijst: de top tien van elke maand is niet de top tien van het kwartaal.

Dagelijkse reeksen per track: twee summary-secties

GET /analytics/summary draagt twee secties die elke track apart rapporteren in plaats van het totaal over de hele release:

Sectie	Vorm van de rij	Gerapporteerd door
track-streams-daily	{ date, platform, isrc, streams }	elk platform
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music en Amazon Music

Beide zijn opt-in: ze worden alleen berekend als je ze in metrics[] benoemt, en beide vereisen filter[release_id], filter[isrc] of filter[upc]. Benoem je er een zonder release- of trackfilter, dan volgt een 422 met de fout gekoppeld aan metrics. Een filter op artiestnaam voldoet niet aan die eis.

De rijen zijn gesorteerd op datum, dan platform, dan ISRC, en een dag zonder activiteit levert geen rij op in plaats van een nul. Luisteraarscijfers zijn tellingen per dag en zijn niet optelbaar over datums heen: dezelfde persoon die op twee dagen luistert, telt op beide dagen als één luisteraar.

Opgepast

Een verzoek waarvan tracks × dagen × platformen te groot uitvalt, geeft een 422 met het verzoek het datumbereik te verkleinen, filter[platform] te zetten of met filter[isrc] op één track te filteren. Het bereik wordt geweigerd en niet afgekapt, zodat een halve reeks nooit als compleet in je grafieken belandt.

Uitgewerkt voorbeeld: streams per track voor een album

Je hebt een album met UPC 0123456789012 en je wilt de cijfers van juni uitgesplitst per track.

Voor een gerangschikte lijst met totalen per track vraag je het leaderboards-endpoint om de tracks van het album:

GET /analytics/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 }
}

Voor de dagelijkse reeks van elke track afzonderlijk vraag je het summary-endpoint om de sectie per track:

GET /analytics/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 }
    ]
  }
}

Voeg metrics[]=track-listeners-daily toe aan diezelfde aanroep om naast streams ook luisteraars te krijgen. Gaat het je maar om één track van het album, laat de UPC dan weg en stuur in plaats daarvan de filter[isrc] van die track mee: elk analytics-endpoint rapporteert dan alleen nog over die opname.

Gerelateerd

• Analytics-API: platformen, beschikbaarheid en limieten — welke platformen welke metrics rapporteren, de rapportagecadans en de limieten op het datumbereik
• API-overzicht en snelstart — authenticatie, sandbox en de volledige endpointreferentie
• Analytics — dezelfde data in het dashboard
• Je AI-assistent met LabelGrid verbinden (MCP) — bevraag je analytics in natuurlijke taal