Analytics-API: omfattningsfilter och data per låt

Varje analytics-förfrågan täcker en del av din katalog, och varje förfrågan ger ett aggregerat resultat över just den delen. Det är de två tillsammans som brukar ställa till det: filtrerar du ett anrop på ett albums UPC får du albumets siffror, inte en rad per låt. Den här guiden går igenom filtren som sätter omfattningen, vad aggregeringen gör med resultatet, och de två endpoints som bryter ner en omfattning låt för låt.

Omfattningsfiltren

Fyra filter avgränsar en analytics-förfrågan till en del av din katalog. De fungerar på GET /analys/summary, på de fristående serie- och demografi-endpointerna samt på GET /analys/leaderboards och /analys/placements.

Filter	Typ	Låtarna filtret omfattar
filter[release_id]	heltal	alla låtar på den releasen
filter[isrc]	sträng	den enda inspelningen med den ISRC-koden
filter[upc]	sträng	alla låtar på releasen med den streckkoden
filter[artist_names][]	array av strängar	alla låtar i din katalog där de artisterna är krediterade

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

Skickar du inget av dem täcker förfrågan hela den katalog du har åtkomst till. Det är standardomfattningen för varje analytics-anrop.

Bara ett filter gäller

De fyra löses upp i en fast ordning: release_id, sedan isrc, sedan upc, sedan artist_names[]. Det första som finns med vinner. Att skicka filter[release_id] och filter[upc] tillsammans kombinerar dem inte, utan UPC:n ignoreras. Skicka bara det filter du menar.

När identifieraren inte är din

De tre filtren på releasenivå svarar olika när identifieraren inte går att hitta i din katalog:

• filter[release_id] ger ett fel: 404 när ingen sådan release finns, 403 när den finns men inte är din.
• filter[isrc] och filter[upc] löses upp till en tom omfattning, och förfrågan lyckas med tomt data.

Bygger du API-anropen på en identifierare som en användare skrivit in bör du alltså testa på tomt data i stället för att vänta på en 404.

Avgränsa till ett av dina skivbolag

GET /analys/summary och GET /analys/leaderboards accepterar också filter[label_id], som avgränsar förfrågan till ett enda av dina egna skivbolag. Ett okänt bolag ger 404 och ett bolag du inte äger ger 403. Filtret kan bara begränsa din omfattning; det finns inget värde som vidgar den.

Vill du avgränsa per butik i stället använder du filter[platform]. Se Analytics-API: plattformar, tillgänglighet och gränser för de accepterade värdena och matrisen över sektioner per plattform.

En omfattning in, en serie ut

Serie- och summary-sektionerna aggregerar över den omfattning filtret ger. En dagserie grupperar på datum och plattform och summerar måttet över alla låtar i omfattningen. Antalet rader du får tillbaka beror alltså på hur många datum och plattformar som rapporterade, aldrig på hur många låtar filtret träffade.

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

Ett album med tolv låtar och en singel ger samma form. total på varje rad är hela omfattningens siffra för det datumet och den plattformen, och värdet är detsamma vare sig albumet har två låtar eller tjugo.

Demografi-endpointerna fungerar likadant, fast längs en annan dimension: /analys/streams-by-country grupperar på land och summerar över omfattningen, så ett UPC-filtrerat anrop ger albumets fördelning per land, inte varje låts. Varje sektion i /analys/summary följer samma regel, med två namngivna undantag som tas upp nedan.

Note

Det här är avsiktligt, inte en begränsning att kringgå. Inget i förfrågan ändrar på det: det finns ingen parameter för att gruppera per låt på serie-endpointerna. Siffror per låt kommer från de två endpoints som beskrivs nedan.

Så får du siffror per låt

Det du vill ha	Var du får det
Allt för en enskild låt	filter[isrc] på vilken analytics-endpoint som helst
Rangordnade totaler per låt för en period	GET /analys/leaderboards?type=tracks
Dagsserie per låt	GET /analys/summary med metrics[]=track-streams-daily

Totaler per låt: leaderboards-endpointen

GET /analys/leaderboards rangordnar din katalog efter summerade streams i det valda fönstret. Det är API-motsvarigheten till kortet Top performers i analytics-dashboarden.

type är obligatoriskt och tar artists, tracks, albums eller all (alla tre listorna i en förfrågan). Omfattningsfiltren avgränsar rangordningen precis som de avgränsar en serie, så type=tracks tillsammans med filter[upc] ger dig det albumets låtar och inget annat.

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

Låtraderna innehåller name, artistName, streams, release_id, identifier (plattformens identifierare, eller null när raden spänner över mer än en) och isrc (inspelningen som radens streams hör till). Raderna kommer sorterade efter streams, högst först.

isrc följer med så snart raden utan tvekan motsvarar en enda inspelning, även när flera plattformar rapporterar samma inspelning var och en under sin egen identifier, vilket är det vanliga för en låt som finns på mer än en tjänst. Fältet är null när det inte går att visa att raden täcker en enda inspelning: anrop utan filter, som rangordnar på namn över hela din katalog; rader som bara avgränsats med filter[artist_names][]; och rader där samma titel och samma artist rymmer två olika inspelningar. Ett null betyder att raden saknar en entydig inspelning att koppla den till, inte att inspelningen saknar ISRC. Behandla isrc och identifier som oberoende av varandra: det ena kan vara null medan det andra bär ett värde. Behöver varje rad en ISRC, använder du dagssektionerna per låt längre ner.

Två gränser värda att planera för:

• limit är 10 som standard och kan inte överstiga 50. Ett album med fler än 50 låtar går inte att lista i sin helhet via den här endpointen. Använd dagssektionerna per låt i stället och summera raderna själv.
• Fönstret kan inte överstiga 180 dagar, alltså snävare än de 400 dagar serie-endpointerna tillåter. Att sy ihop flera kortare fönster återskapar inte en längre rangordning: topp tio för varje månad är inte topp tio för kvartalet.

Dagsserier per låt: två summary-sektioner

GET /analys/summary bär två sektioner som rapporterar varje låt för sig i stället för totalen för hela releasen:

Sektion	Radens form	Rapporteras av
track-streams-daily	{ date, platform, isrc, streams }	alla plattformar
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music och Amazon Music

Båda är tillval: de beräknas bara när du anger dem i metrics[], och båda kräver filter[release_id], filter[isrc] eller filter[upc]. Anger du en av dem utan ett release- eller låtfilter får du 422 med felet kopplat till metrics. Ett filter på artistnamn räcker inte.

Raderna sorteras på datum, sedan plattform, sedan ISRC, och en dag utan aktivitet får ingen rad alls i stället för en nolla. Lyssnarsiffrorna är dagsantal och går inte att summera över datum: samma person som lyssnar två dagar räknas som en lyssnare båda dagarna.

Caution

Blir kombinationen av låtar, dagar och plattformar för stor returnerar förfrågan 422 med en uppmaning att korta datumintervallet, sätta filter[platform] eller avgränsa till en enda låt med filter[isrc]. Intervallet nekas i stället för att kapas, så en halv serie kan aldrig hamna i dina diagram och se komplett ut.

Praktiskt exempel: streams per låt för ett album

Du har ett album med UPC 0123456789012 och vill se junisiffrorna uppdelade per låt.

Vill du ha en rangordnad lista med totaler per låt frågar du leaderboards-endpointen efter albumets låtar:

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

Vill du ha varje låts serie dag för dag frågar du summary-endpointen efter sektionen per låt:

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

Lägg till metrics[]=track-listeners-daily i samma anrop för att få lyssnare vid sidan av streams. Och bryr du dig bara om en enda låt på albumet: släpp UPC:n och skicka den låtens filter[isrc] i stället, så rapporterar varje analytics-endpoint bara om den inspelningen.

Relaterat

• Analytics-API: plattformar, tillgänglighet och gränser — vilka plattformar som rapporterar vilka mått, rapporteringskadens och gränserna för datumintervall
• API-översikt och snabbstart — autentisering, sandlåda och den fullständiga endpoint-referensen
• Analytics — samma data i dashboarden
• Anslut din AI-assistent till LabelGrid (MCP) — fråga din analytics på naturligt språk