Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

YouTube Analytics API - Data Model

L'API YouTube Analytics vous permet de générer des rapports personnalisés contenant des données YouTube Analytics. L'API est compatible avec les rapports pour les chaînes et les propriétaires de contenus. Les champs de rapport sont caractérisés comme des dimensions ou des métriques :

Les dimensions sont des critères courants utilisés pour agréger des données, comme la date à laquelle une action s'est produite ou le pays où se trouvaient les utilisateurs.

Dans un rapport, chaque ligne de données présente une combinaison unique de valeurs de dimension. Par conséquent, les dimensions que vous choisissez pour un rapport déterminent la façon dont YouTube calcule les valeurs des métriques dans ce rapport.
Les métriques sont des mesures individuelles liées à l'activité des utilisateurs, aux performances des annonces ou aux revenus estimés. Les métriques d'activité des utilisateurs incluent des éléments tels que le nombre de vues et les évaluations des vidéos (J'aime et Je n'aime pas).

L'API Analytics fournit des paramètres de filtrage et de tri, de sorte que l'application appelante n'a pas besoin de prendre en charge ces fonctions de manière native. L'API vous permet également de récupérer des données pour les groupes YouTube Analytics, où un groupe est une collection personnalisée de 500 vidéos, playlists, chaînes ou éléments au maximum.

Choisir les paramètres du rapport

Lorsque vous demandez un rapport à l'aide de la méthode reports.query de l'API, la requête API contient cinq paramètres qui déterminent le mode de calcul des valeurs du rapport :

Les paramètres startDate et endDate spécifient la période pour laquelle le rapport contiendra des données. La réponse de l'API contient en fait des données jusqu'au dernier jour spécifié pour lequel toutes les métriques de la requête sont disponibles au moment de la requête.
Le paramètre metrics spécifie les mesures qui seront incluses dans le rapport. Dans les rapports sur les chaînes, les métriques mesurent l'activité des utilisateurs et incluent des valeurs telles que les vues et les J'aime. Certaines métriques mesurent également les performances des annonces ou les revenus estimés.
Le paramètre dimensions explique comment les métriques seront regroupées.
Le paramètre filters explique comment les données du rapport seront filtrées. Ainsi, au lieu de renvoyer toutes les données d'une chaîne, un rapport peut être filtré pour ne contenir que les métriques d'un pays, d'une vidéo ou d'un groupe de vidéos spécifiques.

Remarque : L'API vous permet de spécifier plusieurs valeurs pour les filtres de vidéos, de playlists et de chaînes. Si vous le faites, vous pouvez également inclure ce filtre dans la liste des dimensions afin que les métriques renvoyées soient également regroupées par vidéo, playlist ou chaîne.

Exemples d'options de création de rapports

Supposons, par exemple, qu'un propriétaire de chaîne souhaite récupérer un rapport sur le type d'appareil vidéo pour déterminer le nombre de vues des vidéos de la chaîne sur des appareils mobiles, des consoles de jeu, des téléviseurs, etc.

Le propriétaire de la chaîne définit le paramètre startDate sur 2015-06-01 et le paramètre endDate sur 2015-07-31. Sur la base de ces valeurs, le rapport contiendra des données sur une période de deux mois.
Le rapport sur le type d'appareil est compatible avec les métriques Vues et estimatedMinutesWatched. Le propriétaire de la chaîne définit donc le paramètre metrics sur views,estimatedMinutesWatched.
Pour le paramètre dimensions, le propriétaire de la chaîne dispose de plusieurs options. Deux d'entre elles sont présentées dans la liste suivante, et une troisième est abordée dans l'explication de la valeur du paramètre filters plus loin dans cette section.
- Définir la valeur du paramètre sur deviceType signifie que le nombre de vues et la durée de visionnage seront regroupés par type d'appareil pour l'ensemble de la période couverte par le rapport. Ainsi, avec cette valeur, les données du rapport répondront aux questions suivantes :
  - Combien de fois les vidéos de la chaîne ont-elles été visionnées sur des appareils mobiles entre le 1er juin 2015 et le 31 juillet 2015 ?
  - Combien de fois les vidéos de la chaîne ont-elles été visionnées sur des consoles de jeu entre le 1er juin 2015 et le 31 juillet 2015 ?
  Le rapport contiendra en fait un nombre total de vues et une durée de visionnage pour chaque type d'appareil.
- Définir la valeur du paramètre sur day,deviceType signifie que le nombre de vues et la durée de visionnage seront calculés par type d'appareil pour chaque jour de la période de référence. Ainsi, avec cette valeur, les données du rapport répondront aux questions suivantes :
  - Combien de fois les vidéos de la chaîne ont-elles été visionnées sur des appareils mobiles le 1er juin 2015 ?
  - Combien de fois les vidéos de la chaîne ont-elles été visionnées sur des téléviseurs le 14 juillet 2015 ?
Enfin, le paramètre filters permet au propriétaire de la chaîne de limiter le rapport afin qu'il n'inclue que les données correspondant à des valeurs de filtre spécifiques. Le rapport est compatible avec trop d'options de filtrage pour toutes les expliquer. Ces exemples ne représentent donc qu'une fraction des rapports que vous pouvez générer.
- Le propriétaire de la chaîne peut filtrer la requête pour ne renvoyer que les valeurs du système d'exploitation Android. (Combien de vues ont été enregistrées sur des appareils mobiles Android au cours de la période de référence ?)
- Le propriétaire de la chaîne peut filtrer la requête pour ne renvoyer que les valeurs d'un pays spécifique. (Combien de fois les vidéos ont-elles été visionnées au Canada chaque jour de la période de référence ?)
- Le propriétaire de la chaîne peut filtrer la requête pour ne renvoyer que les valeurs de vidéos spécifiques. Toutefois, le filtre vidéo est compatible avec une liste de valeurs séparées par des virgules. Le rapport peut donc contenir des données pour de nombreuses vidéos.
  
  De plus, si le filtre vidéo spécifie plusieurs valeurs, alors la vidéo peut également être spécifiée comme dimension. Cela signifie que le dimensions paramètre est également compatible avec les valeurs deviceType,video et day,deviceType,video.
  - Si le propriétaire de la chaîne inclut la vidéo dans la liste des dimensions, les métriques spécifient des valeurs individuelles pour chaque vidéo. (Combien de fois la vidéo XYZ a-t-elle été visionnée sur une console de jeu le 1er juin 2015 ?)
  - Si le propriétaire de la chaîne n'inclut pas la vidéo dans la liste des dimensions, les métriques spécifient des valeurs totales couvrant toutes les vidéos spécifiées. (Combien de fois les vidéos ABC, DEF et XYZ ont-elles été visionnées sur une console de jeu le 1er juin 2015 ?)

Fraîcheur des données et latence

Bien que l'API YouTube Analytics soit compatible avec les requêtes ciblées, les données d'analyse sous-jacentes ne sont pas en temps réel. Le traitement des données introduit généralement une latence de 48 à 72 heures. Par conséquent, les réponses de l'API ne contiennent pas de données pour les jours les plus récents, et le endDate de votre rapport n'inclut que les données jusqu'au dernier jour pour lequel toutes les métriques demandées sont entièrement traitées.

Compte tenu de la latence des données, vous remarquerez peut-être des écarts entre les données renvoyées par l'API et les métriques en temps réel visibles dans YouTube Studio. Si votre application nécessite des statistiques en temps réel pour des vidéos individuelles , telles que le nombre actuel de vues, de J'aime ou de commentaires, utilisez la méthode YouTube Data API's videos.list au lieu de l'API YouTube Analytics.

Récupérer des rapports

Pour récupérer un rapport, envoyez une requête GET autorisée à la méthode reports.query de l'API, en spécifiant les paramètres qui définissent le rapport que vous souhaitez récupérer.

Consultez la documentation sur les rapports sur les chaînes et les rapports sur les propriétaires de contenus pour obtenir la liste des rapports compatibles avec l'API. Chaque définition de rapport identifie les valeurs que le rapport autorise pour les paramètres metrics, dimensions et filters.

Bonnes pratiques

Les applications qui utilisent l'API YouTube Analytics doivent toujours suivre ces pratiques :

Utilisez la ligne d'en-tête d'une réponse pour déterminer l'ordre des colonnes du rapport. Par exemple, ne supposez pas que les vues seront la première métrique renvoyée dans une réponse simplement parce qu'il s'agit de la première métrique listée dans une description de rapport. Utilisez plutôt la ligne d'en-tête de la réponse pour déterminer la colonne contenant ces données.
Utilisez l'API YouTube Data pour récupérer des métadonnées supplémentaires pour les ressources identifiées dans les réponses de l'API YouTube Analytics. Comme indiqué dans les Conditions d'utilisation des services d'API YouTube (sections III.E.4.b à III.E.4.d), les clients API doivent supprimer ou actualiser les métadonnées de ressources stockées à partir de cette API après 30 jours.

Métriques agrégées et éléments supprimés

Les réponses de l'API YouTube Analytics ne contiennent pas de répartition des métriques pour les éléments supprimés. Par exemple, si un propriétaire de chaîne supprime une vidéo, elle ne sera plus listée dans une réponse d'API qui renvoie des métriques vidéo par vidéo. Toutefois, les rapports qui agrègent des métriques pour un ensemble de ressources incluent toujours les métriques associées aux éléments supprimés.

Supposons, par exemple, qu'un propriétaire de chaîne récupère deux rapports. Le premier rapport liste le nombre total de vues quotidiennes pour toutes les vidéos de la chaîne sur une période donnée. Le deuxième rapport liste le nombre total de vues quotidiennes vidéo par vidéo sur la même période.

Dans ce cas, les chiffres du premier rapport incluront les vues des vidéos qui ont été supprimées par la suite, car le premier rapport contient des agrégats quotidiens. Toutefois, le deuxième rapport n'inclura pas les vues associées aux éléments supprimés, car il liste les vues vidéo par vidéo. Par conséquent, si la chaîne a supprimé des vidéos au cours de la période couverte par le rapport, le nombre total de vues quotidiennes indiqué dans le premier rapport peut être supérieur à la somme des nombres de vues quotidiens spécifiques aux vidéos dans le deuxième rapport.

Anonymisation des données

Certaines données YouTube Analytics sont limitées lorsque les métriques n'atteignent pas un certain seuil. Cela peut se produire dans différents rapports. En pratique, cela signifie qu'un rapport peut ne pas contenir toutes vos données (ou aucune) si :

une vidéo ou une chaîne enregistre un trafic limité pendant une période donnée,

ou
vous avez sélectionné un filtre ou une dimension, comme la source de trafic ou le pays, dont les valeurs n'atteignent pas un certain seuil.

Dans ce cas, vous pouvez constater une différence entre les totaux indiqués dans certains rapports, en fonction de la manière dont ces rapports agrègent les données.

Supposons, par exemple, qu'un propriétaire de chaîne récupère deux rapports. Le premier rapport liste le nombre total de vues d'une vidéo spécifique, et le deuxième rapport liste le nombre total de vues de cette vidéo par pays. Au cours de la période spécifiée, supposons que la vidéo a été regardée 1 000 fois, dont 500 vues aux États-Unis, 498 au Canada et deux en France.

Dans cet exemple, le premier rapport indique que la vidéo a été visionnée 1 000 fois. Le deuxième rapport indique uniquement que la vidéo a été visionnée 500 fois aux États-Unis et 498 fois au Canada. Il existe donc une différence entre le nombre total de vues dans les deux rapports. Notez que le deuxième rapport n'indique pas que deux autres vues ont également été enregistrées (ni qu'aucune vue n'a été enregistrée en France).

Les seuils réels auxquels les données sont limitées ne sont pas publiés et peuvent être modifiés à la discrétion de YouTube.

Types de données limités

Les données suivantes peuvent être limitées dans les rapports YouTube Analytics :

Données démographiques, telles que l'âge et le genre.
Données géographiques, y compris les métriques ou les dimensions liées aux pays ou aux régions où se trouvaient les spectateurs, telles que leurs pays ou régions. Notez toutefois que les rapports n'appliquent pas de seuils géographiques aux métriques de revenus.
Métriques liées à des sources de trafic spécifiques, telles que les termes de recherche ou les URL externes qui ont généré des vues de vos vidéos. Par exemple, les termes de recherche et les URL qui génèrent un très faible nombre de vues n'apparaissent pas dans les rapports, mais vous verrez toujours les termes et les URL qui génèrent un grand nombre de spectateurs pour votre contenu.

Pour en savoir plus sur les données limitées dans les rapports YouTube Analytics, consultez le Centre d'aide YouTube.

Utilisation du quota

Chaque requête API que vous effectuez compte comme une unité de votre quota d'utilisation de l'API. Les limites de quota sont visibles dans le panneau "Quotas" de la console Google APIs.