Analytics-API: plattformar, tillgänglighet och gränser

LabelGrids publika API levererar streaminganalytics via GET /analys/summary (en sammansatt endpoint som returnerar de sektioner du väljer) och fristående serie-endpoints som GET /analys/streams. Den här sidan täcker plattformsuppsättningen, hur du tar reda på vad varje plattform rapporterar, rapporteringskadensen och förfrågningsgränserna.

Plattformar som stöds

filter[platform] accepterar tio värden som täcker nio butiker:

SPOTIFY, APPLE_MUSIC (ITUNES accepteras som alias för samma butik), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Utelämna filter[platform] för att få den kombinerade vyn över alla plattformar som ditt konto har data för.

Upptäcka tillgänglighet: GET /analys/availability

Alla plattformar rapporterar inte alla mått. Discovery-endpointen för tillgänglighet returnerar hela bilden i ett anrop:

GET /analys/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 — varje analytics-sektionsnyckel, i kanonisk ordning. Denna lista är auktoritativ: det är samma uppsättning som metrics[] accepterar på /analys/summary.
• platforms — varje värde som filter[platform] accepterar.
• availability — indexerad per sektion, sedan per plattform. Varje cell är available eller not_available_for_platform.
• platform_cadence — daily eller weekly per plattform (se Rapporteringskadens).

Svaret är statisk konfiguration — det beror inte på ditt konto, ett datumintervall eller något filter — hämta det en gång och cacha det. Endpointen tar inga parametrar och använder samma autentisering och samma hastighetsgränser som övriga /analys/*-endpoints.

availability-fältet på filtrerade förfrågningar

När du filtrerar en analytics-förfrågan på en enda plattform (till exempel filter[platform]=DEEZER) bär svaret också ett availability-fält bredvid data:

• available — plattformen rapporterar detta mått; data fylls i som vanligt.
• not_available_for_platform — plattformen rapporterar inte detta mått; data är tomt. Detta är förväntat beteende, inte ett fel.

Fristående endpoints bär ett enda toppnivåvärde; /analys/summary bär en map med en post per begärd sektion. Förfrågningar utan plattformsfilter bär inget availability-fält. Läs alltid availability innan du tolkar ett tomt data som “ingen aktivitet”.

Vad plattformarna rapporterar

Matrisen i korthet (anropa endpointen för den auktoritativa, aktuella versionen):

Sektioner	Rapporterande plattformar
streams	Alla nio plattformar
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-dimensionssektioner	APPLE_MUSIC
Lyssnarsammansättning och per-stream-sektioner (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /analys/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

En notis om lyssnarsemantik: Spotify och Apple Music rapporterar ett dagligt lyssnarantal utan dubbletter per låt. Audiomacks dagssiffra är summan av antalen som rapporteras per land och prenumerationsnivå, så en lyssnare som är aktiv i mer än ett segment samma dag bidrar mer än en gång.

Rapporteringskadens: dagliga och veckovisa plattformar

Varje GET /analys/summary-svar bär en meta.platform_cadence-map som anger hur ofta varje plattform rapporterar:

• daily — en rapport per dag: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — en rapport per vecka: KUGOU, KUWO, QQMUSIC

En veckovis plattform producerar en datapunkt per låt och vecka, daterad till dagen rapporten täcker och med hela veckans summa. Summan delas aldrig upp över de sju dagarna. I en dagserie ser du ett ifyllt datum per vecka, utan rader på datumen däremellan.

Hantera detta i din konsument genom att läsa platform_cadence i stället för att härleda kadensen ur datumens avstånd:

• Behandla inte glappet mellan två veckopunkter som saknad data.
• Dela inte upp en veckopunkt i ett dagsgenomsnitt.
• Att summera punkterna som de är ger fortfarande rätt summa för valfritt intervall.

Kadens är skilt från meta.section_granularity, som anger hur punkterna i en returnerad serie är daterade (day eller week). Ett svar kan bära granularitet "day" och kadens "weekly" samtidigt — dagdaterade punkter, en per vecka.

Välja sektioner: metrics[] på /analys/summary

metrics[] är obligatoriskt på GET /analys/summary: ange de sektioner du vill ha, från 1 upp till 12 per förfrågan.

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

Att begära fler än 12 nycklar returnerar 422 med en uppmaning att dela upp urvalet. Varje projektion cachas oberoende per omfattning och fönster, så att dela upp ett större urval i flera förfrågningar är billigt vid upprepade anrop. De giltiga sektionsnycklarna är sections-listan från GET /analys/availability; en ogiltig metrics[]-förfrågan räknar också upp dem i sitt felmeddelande.

Gränser för datumintervall

GET /analys/summary och de fristående serie- och demografi-endpointerna accepterar ett datumintervall på upp till 400 dagar — nog för ett helt år plus en jämförelseperiod i en enda förfrågan. Ett intervall över gränsen returnerar ett 422 vars felmeddelande anger gränsen.

Endpoint-familj	Maximalt intervall
/analys/summary och fristående serie-/demografi-endpoints	400 dagar
/analys/leaderboards, /analys/placements	180 dagar

Ranking-endpointerna behåller sin egen 180-dagarsgräns — och observera att kombinera flera kortare topp-N-fönster inte återskapar topp-N över en längre period.

Två beteenden till kommer med 400-dagarsfönstret:

• Förfrågningar som spänner över mer än 90 dagar mäts mot en andra, lägre hastighetsgräns, utöver den vanliga analytics-gränsen (30/minut per konto mot standardens 60; budgetarna per partner-egress-IP halveras på samma sätt). Förfrågningar på 90 dagar eller mindre påverkas inte. Att överskrida någon av gränserna returnerar 429 med de vanliga Retry-After- och X-RateLimit-*-headrarna.
• Ett intervall inom gränsen kan ändå vara för tungt att beräkna — till exempel en mycket stor katalog över hela fönstret med många metrics[]. Det returnerar 422 med ett meddelande om att “minska datumintervallet”. Behandla det som omförsökbart: försök igen med ett kortare intervall eller färre sektioner. Ett orelaterat serverfel returnerar fortfarande 500, så en 422 här betyder tillförlitligt “den här förfrågan var för stor”.

Relaterat

• API-översikt — autentisering, endpoints och den fullständiga referensen <<<<<<< HEAD
• Analytics — analytics-panelen och vad varje flik visar =======
• Analytics — analytics-dashboarden och vad varje vy visar
• Anslut din AI-assistent till LabelGrid (MCP) — fråga din analytics på naturligt språk

origin/main