API Analytics: filtri di ambito e dati per traccia

Ogni richiesta di analytics copre una porzione del tuo catalogo, e ogni richiesta restituisce un unico risultato aggregato su quella porzione. Messi insieme, questi due fatti sorprendono spesso: se filtri una chiamata con l’UPC di un album ottieni i numeri dell’album, non una riga per ciascuna delle sue tracce. Questa guida spiega i filtri che definiscono l’ambito, che effetto ha l’aggregazione sul risultato e i due endpoint che scompongono un ambito traccia per traccia.

I filtri di ambito

Quattro filtri restringono una richiesta di analytics a una parte del tuo catalogo. Funzionano su GET /statistiche/summary, sugli endpoint autonomi di serie e demografia e su GET /statistiche/leaderboards e /statistiche/placements.

Filtro	Tipo	Le tracce a cui si risolve
filter[release_id]	intero	tutte le tracce di quella release
filter[isrc]	stringa	l’unica registrazione che porta quell’ISRC
filter[upc]	stringa	tutte le tracce della release con quel barcode
filter[artist_names][]	array di stringhe	tutte le tracce del tuo catalogo accreditate a quegli artisti

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

Se non ne invii nessuno, la richiesta copre tutto il catalogo a cui hai accesso: è l’ambito predefinito di ogni chiamata di analytics.

Vale un solo filtro

I quattro vengono risolti in un ordine fisso: prima release_id, poi isrc, poi upc, poi artist_names[]. Vince il primo presente. Inviare insieme filter[release_id] e filter[upc] non ne interseca gli ambiti: l’UPC viene ignorato. Invia solo il filtro che ti serve davvero.

Cosa succede se l’identificativo non è tuo

I tre filtri a livello di release si comportano in modo diverso quando l’identificativo non si risolve dentro il tuo catalogo:

• filter[release_id] genera un errore: 404 se quella release non esiste, 403 se esiste ma non è tua.
• filter[isrc] e filter[upc] si risolvono in un ambito vuoto e la richiesta va a buon fine con data vuoto.

Quindi, se la tua integrazione parte da un identificativo digitato da un utente, verifica che data sia vuoto invece di aspettarti un 404.

Restringere a una delle tue etichette

GET /statistiche/summary e GET /statistiche/leaderboards accettano anche filter[label_id], che restringe la richiesta a una sola delle tue etichette. Un’etichetta sconosciuta restituisce 404, un’etichetta che non è tua restituisce 403. Può solo restringere il tuo ambito: nessun valore lo allarga.

Per restringere invece per store, usa filter[platform]. Consulta API Analytics: piattaforme, disponibilità e limiti per i valori accettati e la matrice delle sezioni per piattaforma.

Un ambito in ingresso, una serie in uscita

Le sezioni di serie e di riepilogo aggregano sull’ambito risolto. Una serie giornaliera raggruppa per data e piattaforma e somma la misura su tutte le tracce in ambito, quindi il numero di righe che ricevi dipende da quante date e quante piattaforme hanno riportato dati, mai da quante tracce ha selezionato il filtro.

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

Un album di dodici tracce e un singolo restituiscono la stessa struttura. Il total di ogni riga è la cifra dell’intero ambito per quella data e quella piattaforma, ed è lo stesso valore sia che l’album abbia due tracce sia che ne abbia venti.

Gli endpoint demografici funzionano allo stesso modo, solo su un’altra dimensione: /statistiche/streams-by-country raggruppa per paese e somma sull’ambito, quindi una chiamata filtrata per UPC dà la ripartizione per paese dell’album, non quella di ogni singola traccia. Ogni sezione di /statistiche/summary segue la stessa regola, con due eccezioni esplicite di cui parliamo più sotto.

Nota

È un comportamento deliberato, non un limite da aggirare, e nessun parametro della richiesta lo modifica: sugli endpoint di serie non esiste un modo per raggruppare per traccia. I numeri per traccia arrivano dai due endpoint qui sotto.

Ottenere numeri per traccia

Cosa ti serve	Dove ottenerlo
Tutto su una singola traccia	filter[isrc] su qualsiasi endpoint di analytics
I totali per traccia di un periodo, in classifica	GET /statistiche/leaderboards?type=tracks
Una serie giornaliera per traccia	GET /statistiche/summary con metrics[]=track-streams-daily

Totali per traccia: l’endpoint leaderboards

GET /statistiche/leaderboards classifica il tuo catalogo per stream sommati nella finestra scelta. È l’equivalente via API della scheda Top performers nella dashboard Analytics.

type è obbligatorio e accetta artists, tracks, albums oppure all (tutte e tre le liste in una sola richiesta). I filtri di ambito lo restringono esattamente come restringono una serie, quindi type=tracks con filter[upc] ti dà le tracce di quell’album e nient’altro.

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

Le righe delle tracce portano name, artistName, streams, release_id, identifier (l’identificativo sulla piattaforma, oppure null quando la riga copre più di una piattaforma) e isrc (la registrazione a cui appartengono gli stream della riga). Le righe tornano ordinate per stream, dal valore più alto in giù.

isrc torna ogni volta che la riga corrisponde senza dubbio a una sola registrazione, anche quando più piattaforme riportano quella stessa registrazione ciascuna con il proprio identifier: è il caso normale di una traccia presente su più servizi. Vale null quando non si può dimostrare che la riga copra una registrazione sola: le chiamate senza filtro, che ordinano per nome su tutto il tuo catalogo; le righe ristrette con il solo filter[artist_names][]; e le righe in cui uno stesso titolo con lo stesso artista comprende due registrazioni diverse. Un null significa che quella riga non ha una registrazione unica a cui agganciarsi, non che la registrazione sia priva di ISRC. Tratta isrc e identifier come indipendenti: uno dei due può essere null mentre l’altro porta un valore. E se ti serve che ogni riga abbia un ISRC, usa le sezioni giornaliere per traccia qui sotto.

Due limiti da mettere in conto:

• limit vale 10 per impostazione predefinita e non può superare 50. Un album con più di 50 tracce non si può elencare per intero da questo endpoint: usa piuttosto le sezioni giornaliere per traccia e somma tu le righe.
• La finestra non può superare i 180 giorni, meno dei 400 concessi dagli endpoint di serie. Unire più finestre brevi non ricostruisce una classifica su un periodo più lungo, perché la top ten di ogni mese non è la top ten del trimestre.

Serie giornaliere per traccia: due sezioni di /statistiche/summary

GET /statistiche/summary porta due sezioni che riportano ogni traccia separatamente invece del totale dell’intera release:

Sezione	Struttura della riga	Riportata da
track-streams-daily	{ date, platform, isrc, streams }	tutte le piattaforme
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music e Amazon Music

Entrambe vanno richieste esplicitamente: vengono calcolate solo se le indichi in metrics[], ed entrambe richiedono filter[release_id], filter[isrc] o filter[upc]. Indicarne una senza un filtro di release o di traccia restituisce 422, con l’errore agganciato a metrics. Un filtro per nome d’artista non soddisfa il requisito.

Le righe sono ordinate per data, poi per piattaforma, poi per ISRC, e un giorno senza attività non produce una riga a zero: semplicemente non c’è. Le cifre dei listener sono conteggi giornalieri e non si sommano tra date diverse: la stessa persona che ascolta in due giorni è un listener in ciascuno dei due.

Attenzione

Una richiesta il cui prodotto tracce × giorni × piattaforme è troppo grande restituisce 422 e ti chiede di restringere l’intervallo di date, impostare filter[platform] o filtrare su una sola traccia con filter[isrc]. L’intervallo viene rifiutato, non troncato: così una serie parziale non finisce mai nei tuoi grafici con l’aria di essere completa.

Esempio pratico: gli stream traccia per traccia di un album

Hai un album con UPC 0123456789012 e vuoi i numeri di giugno scomposti per traccia.

Per una classifica dei totali per traccia, chiedi all’endpoint leaderboards le tracce dell’album:

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

Per la serie giorno per giorno di ogni traccia, chiedi all’endpoint summary la sezione per traccia:

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

Aggiungi metrics[]=track-listeners-daily alla stessa chiamata per avere i listener accanto agli stream. E se ti interessa una sola traccia dell’album, lascia perdere l’UPC e passa invece il filter[isrc] di quella traccia: da lì in poi ogni endpoint di analytics riporta solo quella registrazione.

Correlati

• API Analytics: piattaforme, disponibilità e limiti — quali piattaforme riportano quali metriche, la cadenza dei report e i limiti dell’intervallo di date
• Panoramica dell’API e guida rapida — autenticazione, sandbox e il riferimento completo degli endpoint
• Analytics — gli stessi dati nella dashboard
• Collega il tuo assistente AI a LabelGrid (MCP) — interroga i tuoi analytics in linguaggio naturale