API Analytics : plateformes, disponibilité et limites

L’API publique de LabelGrid sert les analytics de streaming via GET /statistiques/summary (un endpoint composite qui renvoie les sections que vous sélectionnez) et des endpoints de séries autonomes comme GET /statistiques/streams. Cette page couvre l’ensemble des plateformes, la découverte de ce que chaque plateforme rapporte, la cadence de rapport et les limites des requêtes.

Plateformes prises en charge

filter[platform] accepte dix valeurs couvrant neuf stores :

SPOTIFY, APPLE_MUSIC (ITUNES est accepté comme alias du même store), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Omettez filter[platform] pour recevoir la vue combinée de toutes les plateformes pour lesquelles votre compte a des données.

Découvrir la disponibilité : GET /statistiques/availability

Toutes les plateformes ne rapportent pas toutes les métriques. L’endpoint de découverte de la disponibilité renvoie le tableau complet en un seul appel :

GET /statistiques/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 — toutes les clés de section d’analytics, dans l’ordre canonique. Cette liste fait autorité : c’est le même ensemble que metrics[] accepte sur /statistiques/summary.
• platforms — toutes les valeurs acceptées par filter[platform].
• availability — indexé par section, puis par plateforme. Chaque cellule vaut available ou not_available_for_platform.
• platform_cadence — daily ou weekly par plateforme (voir Cadence de rapport).

La réponse est une configuration statique — elle ne dépend ni de votre compte, ni d’une plage de dates, ni d’un filtre — récupérez-la une fois et mettez-la en cache. Elle ne prend aucun paramètre et utilise la même authentification et les mêmes limites de débit que les autres endpoints /statistiques/*.

Le champ availability sur les requêtes filtrées

Quand vous filtrez une requête d’analytics par une seule plateforme (par exemple filter[platform]=DEEZER), la réponse porte aussi un champ availability à côté de data :

• available — la plateforme rapporte cette métrique ; data est rempli normalement.
• not_available_for_platform — la plateforme ne rapporte pas cette métrique ; data est vide. C’est un comportement attendu, pas une erreur.

Les endpoints autonomes portent une seule valeur de premier niveau ; /statistiques/summary porte une map avec une entrée par section demandée. Les requêtes sans filtre de plateforme ne portent pas de champ availability. Lisez toujours availability avant d’interpréter un data vide comme « aucune activité ».

Ce que les plateformes rapportent

La matrice en un coup d’œil (appelez l’endpoint pour la version actuelle faisant autorité) :

Sections	Plateformes qui les rapportent
streams	Les neuf plateformes
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, sections de dimensions Apple	APPLE_MUSIC
Composition d’audience des listeners et sections per-stream (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /statistiques/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Une note sur la sémantique des listeners : Spotify et Apple Music rapportent un décompte quotidien de listeners dédupliqué par titre. Le chiffre quotidien d’Audiomack est la somme des décomptes rapportés par pays et par niveau d’abonnement — un listener actif dans plusieurs segments le même jour contribue donc plusieurs fois.

Cadence de rapport : plateformes quotidiennes et hebdomadaires

Chaque réponse de GET /statistiques/summary porte une map meta.platform_cadence indiquant la fréquence de rapport de chaque plateforme :

• daily — un rapport par jour : SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — un rapport par semaine : KUGOU, KUWO, QQMUSIC

Une plateforme hebdomadaire produit un point de données par titre et par semaine, daté du jour couvert par le rapport et portant le total de la semaine. Le total n’est jamais réparti sur les sept jours. Sur une série quotidienne, vous verrez une date renseignée par semaine, sans lignes entre les deux.

Gérez cela côté client en lisant platform_cadence plutôt qu’en déduisant la cadence de l’espacement des dates :

• Ne traitez pas le trou entre deux points hebdomadaires comme des données manquantes.
• Ne divisez pas un point hebdomadaire en moyenne quotidienne.
• Additionner les points tels quels donne toujours le bon total sur n’importe quelle plage.

La cadence est distincte de meta.section_granularity, qui indique comment les points d’une série renvoyée sont datés (day ou week). Une réponse peut porter à la fois la granularité "day" et la cadence "weekly" — des points datés au jour, un par semaine.

Sélectionner les sections : metrics[] sur /statistiques/summary

metrics[] est obligatoire sur GET /statistiques/summary : nommez les sections voulues, de 1 à 12 par requête.

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

Demander plus de 12 clés renvoie un 422 vous invitant à scinder la sélection. Chaque projection est mise en cache indépendamment par périmètre et par fenêtre : scinder une grande sélection en plusieurs requêtes coûte peu sur les appels répétés. Les clés de section valides sont la liste sections de GET /statistiques/availability ; une requête metrics[] invalide les énumère aussi dans son message d’erreur.

Limites de plage de dates

GET /statistiques/summary et les endpoints autonomes de séries et de démographie acceptent une plage de dates allant jusqu’à 400 jours — de quoi couvrir une année complète plus une période de comparaison en une seule requête. Une plage au-delà de la limite renvoie un 422 dont le message d’erreur indique la limite.

Famille d’endpoints	Plage maximale
/statistiques/summary et endpoints autonomes de séries/démographie	400 jours
/statistiques/leaderboards, /statistiques/placements	180 jours

Les endpoints de classement gardent leur propre limite de 180 jours — et notez que combiner plusieurs fenêtres top-N plus courtes ne reconstruit pas le top-N sur une période plus longue.

Deux comportements supplémentaires arrivent avec la fenêtre de 400 jours :

<<<<<<< HEAD

• Aperçu de l’API — authentification, endpoints et la référence complète
• Analytiques — le tableau de bord d’analytiques et ce que montre chaque onglet =======
• Les requêtes couvrant plus de 90 jours sont comptées contre une seconde limite de débit plus basse, en plus de la limite standard d’analytics (30/minute par compte contre 60 en standard ; les budgets par IP de sortie partenaire sont réduits de moitié de la même manière). Les requêtes de 90 jours ou moins ne sont pas affectées. Dépasser l’une des deux limites renvoie 429 avec les en-têtes habituels Retry-After et X-RateLimit-*.
• Une plage dans la limite peut rester trop lourde à calculer — par exemple un très gros catalogue sur la fenêtre complète avec beaucoup de metrics[]. Cela renvoie 422 avec un message « réduisez la plage de dates ». Traitez-le comme réessayable : relancez avec une plage plus courte ou moins de sections. Une erreur serveur sans rapport renvoie toujours 500, donc un 422 ici signifie de façon fiable « cette requête était trop grosse ».

Voir aussi

• Présentation de l’API — authentification, endpoints et référence complète
• Analytics — le dashboard d’analytics et ce que montre chaque vue
• Connecter votre assistant IA à LabelGrid (MCP) — interrogez vos analytics en langage naturel

origin/main