API Analytics : filtres de périmètre et données par titre

Chaque requête d’analytics porte sur une partie de votre catalogue, et chaque requête renvoie un résultat agrégé sur cette partie. C’est la combinaison des deux qui surprend : filtrez un appel par l’UPC d’un album et vous obtenez les chiffres de l’album, pas une ligne par titre. Cette page couvre les filtres qui définissent le périmètre, l’effet de l’agrégation sur le résultat, et les deux endpoints qui détaillent un périmètre titre par titre.

Les filtres de périmètre

Quatre filtres restreignent une requête d’analytics à une partie de votre catalogue. Ils fonctionnent sur GET /statistiques/summary, sur les endpoints autonomes de séries et de démographie, ainsi que sur GET /statistiques/leaderboards et /statistiques/placements.

Filtre	Type	Les titres qu’il sélectionne
filter[release_id]	entier	tous les titres de cette sortie
filter[isrc]	chaîne	l’unique enregistrement portant cet ISRC
filter[upc]	chaîne	tous les titres de la sortie portant ce code-barres
filter[artist_names][]	tableau de chaînes	tous les titres de votre catalogue crédités à ces artistes

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

Si vous n’en envoyez aucun, la requête couvre tout le catalogue auquel vous avez accès : c’est le périmètre par défaut de tous les appels d’analytics.

Un seul filtre s’applique

Les quatre sont résolus dans un ordre fixe : release_id, puis isrc, puis upc, puis artist_names[]. Le premier présent l’emporte. Envoyer filter[release_id] et filter[upc] ensemble ne croise pas les deux périmètres : l’UPC est ignoré. N’envoyez que le filtre que vous voulez réellement appliquer.

Quand l’identifiant n’est pas le vôtre

Les trois filtres au niveau de la sortie ne réagissent pas de la même façon quand l’identifiant ne correspond à rien dans votre catalogue :

• filter[release_id] déclenche une erreur : 404 quand la sortie n’existe pas, 403 quand elle existe mais ne vous appartient pas.
• filter[isrc] et filter[upc] se résolvent en un périmètre vide, et la requête aboutit avec un data vide.

Quand vous pilotez l’API à partir d’un identifiant saisi par un utilisateur, testez donc le data vide plutôt que d’attendre un 404.

Restreindre à l’un de vos labels

GET /statistiques/summary et GET /statistiques/leaderboards acceptent aussi filter[label_id], qui restreint la requête à un seul de vos labels. Un label inconnu renvoie 404, un label qui ne vous appartient pas renvoie 403. Ce filtre ne peut que réduire votre périmètre : aucune valeur ne l’élargit.

Pour restreindre par plateforme, utilisez plutôt filter[platform]. Voir API Analytics : plateformes, disponibilité et limites pour les valeurs acceptées et la matrice des sections par plateforme.

Un périmètre en entrée, une série en sortie

Les endpoints de séries et les sections de /statistiques/summary agrègent les données sur l’ensemble du périmètre résolu. Une série quotidienne regroupe par date et par plateforme et additionne la mesure sur tous les titres du périmètre : le nombre de lignes renvoyées dépend donc du nombre de dates et de plateformes ayant rapporté, jamais du nombre de titres retenus par le filtre.

GET /statistiques/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 de douze titres et un single renvoient tous deux cette forme. Le total de chaque ligne est le chiffre de tout le périmètre pour cette date et cette plateforme, et il reste le même que l’album compte deux titres ou vingt.

Les endpoints de démographie se comportent de la même façon, une dimension plus loin : /statistiques/streams-by-country regroupe par pays et additionne sur le périmètre, si bien qu’un appel filtré par UPC donne la répartition par pays de l’album, pas celle de chaque titre. Toutes les sections de /statistiques/summary suivent la même règle, à deux exceptions près, traitées plus bas.

Note

C’est un choix délibéré, pas une limite à contourner. Rien dans la requête ne le change : il n’existe pas de paramètre « regrouper par titre » sur les endpoints de séries. Les chiffres par titre viennent des deux endpoints ci-dessous.

Obtenir des chiffres par titre

Ce que vous cherchez	Où le trouver
Tout sur un seul titre	filter[isrc] sur n’importe quel endpoint d’analytics
Les totaux par titre sur une période, classés	GET /statistiques/leaderboards?type=tracks
Une série quotidienne par titre	GET /statistiques/summary avec metrics[]=track-streams-daily

Les totaux par titre : l’endpoint leaderboards

GET /statistiques/leaderboards classe votre catalogue selon la somme des streams sur la fenêtre demandée. C’est l’équivalent API de la carte Top performers du dashboard Analytics.

type est obligatoire et accepte artists, tracks, albums ou all (les trois listes en une seule requête). Les filtres de périmètre s’y appliquent exactement comme sur une série : type=tracks avec filter[upc] vous donne les titres de cet album, et rien d’autre.

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

Les lignes de titres portent name, artistName, streams, release_id, identifier (l’identifiant de la plateforme, ou null quand la ligne en couvre plusieurs) et isrc (l’enregistrement auquel appartiennent les streams de la ligne). Elles sont renvoyées par ordre décroissant de streams.

isrc est renvoyé dès que la ligne correspond sans ambiguïté à un seul enregistrement, y compris quand plusieurs plateformes rapportent ce même enregistrement chacune sous son propre identifier, ce qui est courant pour un titre disponible sur plusieurs services. Il vaut null quand rien ne prouve que la ligne couvre un seul enregistrement : les appels sans filtre, qui classent par nom sur tout votre catalogue ; les lignes restreintes par le seul filter[artist_names][] ; et les lignes où un même titre et un même artiste recouvrent deux enregistrements différents. Un null signifie que cette ligne n’a pas d’enregistrement unique auquel se rattacher, pas que l’enregistrement n’a pas d’ISRC. Traitez isrc et identifier comme indépendants : l’un peut valoir null pendant que l’autre porte une valeur. Et quand chaque ligne doit porter un ISRC, passez par les sections quotidiennes par titre ci-dessous.

Deux limites à anticiper :

• limit vaut 10 par défaut et ne peut pas dépasser 50. Un album de plus de 50 titres ne peut pas être listé en entier par cet endpoint : passez plutôt par les sections quotidiennes par titre et faites vous-même les totaux.
• La fenêtre ne peut pas dépasser 180 jours, moins que les 400 jours qu’autorisent les endpoints de séries. Assembler plusieurs fenêtres plus courtes ne reconstitue pas un classement sur une période plus longue : le top dix de chaque mois n’est pas le top dix du trimestre.

Séries quotidiennes par titre : deux sections de /statistiques/summary

GET /statistiques/summary porte deux sections qui rapportent chaque titre séparément au lieu du total de toute la sortie :

Section	Forme de ligne	Rapportée par
track-streams-daily	{ date, platform, isrc, streams }	toutes les plateformes
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music et Amazon Music

Les deux sont à activer explicitement : elles ne sont calculées que si vous les nommez dans metrics[], et toutes deux exigent filter[release_id], filter[isrc] ou filter[upc]. En nommer une sans filtre de sortie ni de titre renvoie 422, avec l’erreur rattachée à metrics. Un filtre par nom d’artiste ne suffit pas.

Les lignes sont triées par date, puis par plateforme, puis par ISRC, et un jour sans activité n’a pas de ligne plutôt qu’un zéro. Les chiffres de listeners sont des décomptes quotidiens et ne s’additionnent pas d’un jour à l’autre : une même personne qui écoute deux jours différents compte comme un listener sur chacun de ces jours.

Attention

Une requête dont le produit titres × jours × plateformes est trop grand renvoie 422 en vous invitant à réduire la plage de dates, à renseigner filter[platform] ou à vous limiter à un seul titre avec filter[isrc]. La plage est refusée plutôt que tronquée : une série partielle n’atteint donc jamais vos graphiques en se faisant passer pour complète.

Exemple concret : les streams titre par titre d’un album

Vous avez un album dont l’UPC est 0123456789012 et vous voulez les chiffres de juin détaillés par titre.

Pour un classement des totaux par titre, demandez les titres de l’album à l’endpoint leaderboards :

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

Pour la série jour par jour de chaque titre, demandez la section par titre à l’endpoint /statistiques/summary :

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

Ajoutez metrics[]=track-listeners-daily au même appel pour obtenir les listeners à côté des streams. Et si un seul titre de l’album vous intéresse, retirez l’UPC et passez plutôt le filter[isrc] de ce titre : tous les endpoints d’analytics ne rapportent alors plus que cet enregistrement.

Voir aussi

• API Analytics : plateformes, disponibilité et limites — quelles plateformes rapportent quelles métriques, la cadence de rapport et les limites de plage de dates
• Aperçu de l’API et démarrage rapide — authentification, sandbox et la référence complète des endpoints
• Analytics — les mêmes données dans le dashboard
• Connecter votre assistant IA à LabelGrid (MCP) — interrogez vos analytics en langage naturel