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 contenu. 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 de 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, par exemple, le nombre de vues et les notes (J'aime et Je n'aime pas).
L'API Analytics fournit des paramètres de filtrage et de tri. L'application appelante n'a donc 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, un groupe étant une collection personnalisée de 500 vidéos, playlists, chaînes ou éléments 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 comment les valeurs du rapport seront calculées :
Les paramètres
startDateetendDatespé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
metricsspé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 mentions "J'aime". Certaines métriques mesurent également les performances des annonces ou les revenus estimés.Le paramètre
dimensionsexplique comment les métriques seront regroupées.Le paramètre
filtersexplique comment les données de rapport seront filtrées. Par exemple, 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 certain pays, d'une certaine vidéo ou d'un certain groupe de vidéos.Remarque : L'API vous permet de spécifier plusieurs valeurs pour les filtres video, playlist et channel. 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
Par exemple, supposons que le propriétaire d'une chaîne souhaite récupérer un rapport sur les types d'appareils vidéo pour déterminer le nombre de vues des vidéos de la chaîne sur les appareils mobiles, les consoles de jeu, les téléviseurs, etc.
Le propriétaire de la chaîne définit le paramètre
startDatesur2015-06-01et le paramètreendDatesur2015-07-31. Sur la base de ces valeurs, le rapport contiendra des données pour une période de deux mois.Le rapport sur les types d'appareils est compatible avec les métriques views et estimatedMinutesWatched. Le propriétaire de la chaîne définit donc le paramètre
metricssurviews,estimatedMinutesWatched.Pour le paramètre
dimensions, le propriétaire de la chaîne dispose de plusieurs options. Deux d'entre eux sont présentés dans la liste suivante, et un troisième est abordé dans l'explication de la valeur du paramètrefiltersplus loin dans cette section.Si vous définissez la valeur du paramètre sur
deviceType, 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 à des questions telles que :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 le nombre total de vues et la durée de visionnage pour chaque type d'appareil.
Si vous définissez la valeur du paramètre sur
day,deviceType, 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 à des questions telles que :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
filterspermet au propriétaire de la chaîne de limiter le rapport aux données correspondant à des valeurs de filtre spécifiques. Le rapport accepte 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 pendant 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 certaines vidéos. Toutefois, le filtre video accepte une liste de valeurs d'éléments séparés par une virgule. Le rapport peut donc contenir des données pour de nombreuses vidéos.
De plus, si le filtre video spécifie plusieurs valeurs, video peut également être spécifié en tant que dimension. Cela signifie que le paramètre
dimensionsaccepte également les valeursdeviceType,videoetday,deviceType,video.- Si le propriétaire de la chaîne inclut video 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 video dans la liste des dimensions, les métriques spécifient les 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 ont été entièrement traitées.
En raison de la latence des données, vous pouvez constater 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 videos.list de l'API YouTube Data au lieu de l'API YouTube Analytics.
Récupération 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 contenu 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 partez pas du principe que views sera 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 la description d'un rapport. Utilisez plutôt la ligne d'en-tête de la réponse pour déterminer quelle colonne contient 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 Règles du développeur 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 le propriétaire d'une chaîne supprime une vidéo, celle-ci n'apparaîtra plus dans une réponse de l'API qui renvoie des métriques vidéo par vidéo. Toutefois, les rapports qui agrègent les métriques d'un ensemble de ressources incluent toujours les métriques associées aux éléments supprimés.
Par exemple, supposons que le propriétaire d'une 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 second rapport indique le nombre total de vues quotidiennes pour chaque 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 second 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 quotidiennes par vidéo dans le second 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 d'entre elles) 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.
Par exemple, supposons que le propriétaire d'une chaîne récupère deux rapports. Le premier rapport indique le nombre total de vues d'une vidéo spécifique, et le second indique 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 vues au Canada et deux vues en France.
Dans cet exemple, le premier rapport indiquerait que la vidéo a été regardée 1 000 fois. Le second rapport indiquerait uniquement que la vidéo a été visionnée 500 fois aux États-Unis et 498 fois au Canada. Il y aurait donc une différence entre le nombre total de vues dans les deux rapports. Notez que le second rapport n'indiquerait pas que deux autres vues ont également été enregistrées (ni que des vues ont été constatées en France).
Types de données limités
La disponibilité des données suivantes peut être limitée 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, comme leurs pays ou leurs 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'apparaîtront pas dans les rapports, mais vous verrez toujours les termes et les URL qui attirent un grand nombre de spectateurs vers votre contenu.
Pour en savoir plus sur la disponibilité limitée des données dans les rapports YouTube Analytics, consultez le Centre d'aide YouTube.
Utilisation du quota
Chaque requête API que vous effectuez est comptabilisée 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 Cloud.