API Analytics: piattaforme, disponibilità e limiti

L’API pubblica di LabelGrid serve gli analytics dello streaming tramite GET /statistiche/summary (un endpoint composito che restituisce le sezioni che selezioni) ed endpoint di serie autonomi come GET /statistiche/streams. Questa pagina copre l’insieme delle piattaforme, come scoprire cosa riporta ogni piattaforma, la cadenza dei report e i limiti delle richieste.

Piattaforme supportate

filter[platform] accetta dieci valori che coprono nove store:

SPOTIFY, APPLE_MUSIC (ITUNES è accettato come alias dello stesso store), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Ometti filter[platform] per ricevere la vista combinata di tutte le piattaforme per cui il tuo account ha dati.

Scoprire la disponibilità: GET /statistiche/availability

Non tutte le piattaforme riportano tutte le metriche. L’endpoint di scoperta della disponibilità restituisce il quadro completo in una sola chiamata:

GET /statistiche/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 — tutte le chiavi di sezione degli analytics, in ordine canonico. Questa lista è quella autorevole: è lo stesso insieme che metrics[] accetta su /statistiche/summary.
• platforms — tutti i valori che filter[platform] accetta.
• availability — indicizzato per sezione e poi per piattaforma. Ogni cella vale available o not_available_for_platform.
• platform_cadence — daily o weekly per piattaforma (vedi Cadenza dei report).

La risposta è configurazione statica — non dipende dal tuo account, da un intervallo di date o da alcun filtro — quindi recuperala una volta e mettila in cache. Non accetta parametri e usa la stessa autenticazione e gli stessi limiti di frequenza degli altri endpoint /statistiche/*.

Il campo availability sulle richieste filtrate

Quando filtri una richiesta di analytics per una singola piattaforma (per esempio filter[platform]=DEEZER), la risposta porta anche un campo availability accanto a data:

• available — la piattaforma riporta questa metrica; data è popolato normalmente.
• not_available_for_platform — la piattaforma non riporta questa metrica; data è vuoto. È il comportamento previsto, non un errore.

Gli endpoint autonomi portano un singolo valore di primo livello; /statistiche/summary porta una mappa con una voce per ogni sezione richiesta. Le richieste senza filtro di piattaforma non portano il campo availability. Leggi sempre availability prima di interpretare un data vuoto come “nessuna attività”.

Cosa riportano le piattaforme

La matrice a colpo d’occhio (chiama l’endpoint per la versione autorevole e aggiornata):

Sezioni	Piattaforme che le riportano
streams	Tutte e nove le piattaforme
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, sezioni delle dimensioni Apple	APPLE_MUSIC
Composizione dell’audience dei listener e sezioni per-stream (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placement (GET /statistiche/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Una nota sulla semantica dei listener: Spotify e Apple Music riportano un conteggio giornaliero di listener deduplicato per traccia. La cifra giornaliera di Audiomack è la somma dei conteggi riportati per paese e livello di abbonamento, quindi un listener attivo in più di un segmento nello stesso giorno contribuisce più di una volta.

Cadenza dei report: piattaforme giornaliere e settimanali

Ogni risposta di GET /statistiche/summary porta una mappa meta.platform_cadence che indica con quale frequenza riporta ogni piattaforma:

• daily — un report al giorno: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — un report a settimana: KUGOU, KUWO, QQMUSIC

Una piattaforma settimanale produce un punto dati per traccia a settimana, datato al giorno coperto dal report e con il totale dell’intera settimana. Il totale non viene mai suddiviso sui sette giorni. In una serie giornaliera vedrai una data popolata a settimana, senza righe nelle date intermedie.

Gestiscilo nel tuo consumer leggendo platform_cadence invece di dedurre la cadenza dalla spaziatura delle date:

• Non trattare il vuoto tra due punti settimanali come dati mancanti.
• Non dividere un punto settimanale in una media giornaliera.
• Sommare i punti così come sono dà comunque il totale corretto di qualsiasi intervallo.

La cadenza è distinta da meta.section_granularity, che indica come sono datati i punti di una serie restituita (day o week). Una risposta può portare granularità "day" e cadenza "weekly" allo stesso tempo — punti datati al giorno, uno a settimana.

Selezionare le sezioni: metrics[] su /statistiche/summary

metrics[] è obbligatorio su GET /statistiche/summary: indica le sezioni che vuoi, da 1 fino a 12 per richiesta.

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

Richiedere più di 12 chiavi restituisce un 422 che chiede di dividere la selezione. Ogni proiezione viene messa in cache in modo indipendente per ambito e finestra, quindi dividere una selezione grande in più richieste costa poco sulle chiamate ripetute. Le chiavi di sezione valide sono la lista sections di GET /statistiche/availability; una richiesta metrics[] non valida le elenca anche nel messaggio di errore.

Limiti dell’intervallo di date

GET /statistiche/summary e gli endpoint autonomi di serie e demografia accettano un intervallo di date fino a 400 giorni — abbastanza per un anno intero più un periodo di confronto in una sola richiesta. Un intervallo oltre il limite restituisce un 422 il cui messaggio di errore indica il limite.

Famiglia di endpoint	Intervallo massimo
/statistiche/summary ed endpoint autonomi di serie/demografia	400 giorni
/statistiche/leaderboards, /statistiche/placements	180 giorni

Gli endpoint di classifica mantengono il proprio limite di 180 giorni — e nota che combinare più finestre top-N più corte non ricostruisce la top-N su un periodo più lungo.

Con la finestra di 400 giorni arrivano altri due comportamenti:

• Le richieste che coprono più di 90 giorni vengono conteggiate contro un secondo limite di frequenza più basso, in aggiunta al limite standard degli analytics (30/minuto per account contro lo standard di 60; i budget per IP di uscita dei partner sono dimezzati allo stesso modo). Le richieste di 90 giorni o meno non sono toccate. Superare uno dei due limiti restituisce 429 con le consuete intestazioni Retry-After e X-RateLimit-*.
• Un intervallo entro il limite può comunque essere troppo pesante da calcolare — per esempio un catalogo molto grande sull’intera finestra con molte metrics[]. Restituisce 422 con un messaggio “restringi l’intervallo di date”. Trattalo come ritentabile: riprova con un intervallo più corto o meno sezioni. Un errore server non correlato restituisce ancora 500, quindi un 422 qui significa in modo affidabile “questa richiesta era troppo grande”.

Correlati

<<<<<<< HEAD

• Panoramica dell’API — autenticazione, endpoint e il riferimento completo
• Analytics — la dashboard di analytics e cosa mostra ogni scheda =======
• Panoramica dell’API — autenticazione, endpoint e riferimento completo
• Analytics — la dashboard di analytics e cosa mostra ogni vista
• Collega il tuo assistente AI a LabelGrid (MCP) — interroga i tuoi analytics in linguaggio naturale

origin/main