Analytics-API: platformen, beschikbaarheid en limieten

De publieke LabelGrid-API levert streaminganalytics via GET /analytics/summary (een samengesteld endpoint dat de door jou gekozen secties teruggeeft) en losse serie-endpoints zoals GET /analytics/streams. Deze pagina behandelt de platformset, hoe je ontdekt wat elk platform rapporteert, de rapportagecadans en de verzoeklimieten.

Ondersteunde platformen

filter[platform] accepteert tien waarden voor negen stores:

SPOTIFY, APPLE_MUSIC (ITUNES wordt geaccepteerd als alias voor dezelfde store), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Laat filter[platform] weg om de gecombineerde weergave te krijgen over alle platformen waarvoor je account data heeft.

Beschikbaarheid ontdekken: GET /analytics/availability

Niet elk platform rapporteert elke metric. Het beschikbaarheids-discovery-endpoint geeft het hele beeld in één aanroep:

GET /analytics/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 — elke analytics-sectiesleutel, in canonieke volgorde. Deze lijst is leidend: het is dezelfde set die metrics[] accepteert op /analytics/summary.
• platforms — elke waarde die filter[platform] accepteert.
• availability — geïndexeerd op sectie, dan op platform. Elke cel is available of not_available_for_platform.
• platform_cadence — daily of weekly per platform (zie Rapportagecadans).

Het antwoord is statische configuratie — het hangt niet af van je account, een datumbereik of een filter — haal het één keer op en cache het. Het endpoint neemt geen parameters aan en gebruikt dezelfde authenticatie en rate limits als de andere /analytics/*-endpoints.

Het availability-veld op gefilterde verzoeken

Als je een analytics-verzoek filtert op één platform (bijvoorbeeld filter[platform]=DEEZER), draagt het antwoord ook een availability-veld naast data:

• available — het platform rapporteert deze metric; data is normaal gevuld.
• not_available_for_platform — het platform rapporteert deze metric niet; data is leeg. Dat is verwacht gedrag, geen fout.

Losse endpoints dragen één waarde op het hoogste niveau; /analytics/summary draagt een map met één item per gevraagde sectie. Verzoeken zonder platformfilter dragen geen availability-veld. Lees altijd availability voordat je een lege data als “geen activiteit” interpreteert.

Wat de platformen rapporteren

De matrix in één oogopslag (roep het endpoint aan voor de leidende, actuele versie):

Secties	Rapporterende platformen
streams	Alle negen platformen
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-dimensiesecties	APPLE_MUSIC
Listener-audiencesamenstelling en per-stream-secties (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /analytics/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Een opmerking over listener-semantiek: Spotify en Apple Music rapporteren een ontdubbeld dagelijks luisteraarsaantal per track. Het dagelijkse Audiomack-cijfer is de som van de per land en abonnementsniveau gerapporteerde aantallen — een luisteraar die op dezelfde dag in meer dan één segment actief is, telt dus vaker mee.

Rapportagecadans: dagelijkse en wekelijkse platformen

Elk GET /analytics/summary-antwoord draagt een meta.platform_cadence-map die aangeeft hoe vaak elk platform rapporteert:

• daily — één rapport per dag: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — één rapport per week: KUGOU, KUWO, QQMUSIC

Een wekelijks platform levert één datapunt per track per week, gedateerd op de dag die het rapport dekt en met het totaal van die week. Het totaal wordt nooit over de zeven dagen verdeeld. In een dagserie zie je één gevulde datum per week, zonder rijen op de dagen ertussen.

Vang dit in je consumer op door platform_cadence te lezen in plaats van de cadans af te leiden uit de afstand tussen datums:

• Behandel het gat tussen twee weekpunten niet als ontbrekende data.
• Deel een weekpunt niet op in een daggemiddelde.
• De punten optellen zoals ze zijn geeft nog steeds het juiste totaal van elk bereik.

Cadans is iets anders dan meta.section_granularity, dat aangeeft hoe de punten van een teruggegeven serie gedateerd zijn (day of week). Een antwoord kan tegelijk granulariteit "day" en cadans "weekly" dragen — dag-gedateerde punten, één per week.

Secties selecteren: metrics[] op /analytics/summary

metrics[] is verplicht op GET /analytics/summary: benoem de secties die je wilt, van 1 tot 12 per verzoek.

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

Meer dan 12 sleutels aanvragen levert een 422 op met het verzoek de selectie op te splitsen. Elke projectie wordt onafhankelijk gecachet per bereik en venster, dus een grotere selectie opsplitsen in meerdere verzoeken is goedkoop bij herhaalde aanroepen. De geldige sectiesleutels zijn de sections-lijst uit GET /analytics/availability; een ongeldig metrics[]-verzoek somt ze ook op in zijn foutmelding.

Datumbereiklimieten

GET /analytics/summary en de losse serie- en demografie-endpoints accepteren een datumbereik van maximaal 400 dagen — genoeg voor een volledig jaar plus een vergelijkingsperiode in één verzoek. Een bereik boven de limiet geeft een 422 waarvan de foutmelding de limiet noemt.

Endpoint-familie	Maximaal bereik
/analytics/summary en losse serie-/demografie-endpoints	400 dagen
/analytics/leaderboards, /analytics/placements	180 dagen

De ranking-endpoints houden hun eigen limiet van 180 dagen — en let op: meerdere kortere top-N-vensters combineren reconstrueert niet de top-N over een langere periode.

Twee extra gedragingen komen mee met het 400-dagenvenster:

• Verzoeken die meer dan 90 dagen beslaan, tellen mee tegen een tweede, lagere rate limit, bovenop de standaard analytics-limiet (30/minuut per account tegenover standaard 60; de budgetten per partner-egress-IP worden op dezelfde manier gehalveerd). Verzoeken van 90 dagen of minder blijven ongemoeid. Een van beide limieten overschrijden geeft 429 met de gebruikelijke Retry-After- en X-RateLimit-*-headers.
• Een bereik binnen de limiet kan nog steeds te zwaar zijn om te berekenen — bijvoorbeeld een heel grote catalogus over het volle venster met veel metrics[]. Dat geeft 422 met een melding “verklein het datumbereik”. Behandel het als opnieuw te proberen: probeer een korter bereik of minder secties. Een niet-gerelateerde serverfout geeft nog steeds 500, dus een 422 hier betekent betrouwbaar “dit verzoek was te groot”.

Gerelateerd

• API-overzicht — authenticatie, endpoints en de volledige referentie <<<<<<< HEAD
• Analytics — het analytics-dashboard en wat elk tabblad toont =======
• Analytics — het analytics-dashboard en wat elke weergave toont
• Je AI-assistent met LabelGrid verbinden (MCP) — bevraag je analytics in natuurlijke taal

origin/main