Cette page a été traduite par l'API Cloud Translation.

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 contenu. Les champs de rapport sont classés comme dimensions ou métriques :

Les dimensions sont des critères courants utilisés pour agréger les données, comme la date à laquelle une action s'est produite ou le pays dans lequel 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 le nombre de vues des vidéos 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 est 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 la façon dont les valeurs du rapport seront calculées :

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. 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 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 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 qu'un propriétaire de chaîne souhaite récupérer un rapport sur les types d'appareils pour déterminer le nombre de vues des vidéos de sa 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 startDate sur 2015-06-01 et le paramètre endDate sur 2015-07-31. En fonction de ces valeurs, le rapport contiendra des données pour une période de deux mois.
Le rapport sur les types d'appareils étant compatible avec les métriques views et estimatedMinutesWatched, le propriétaire de la chaîne définit le paramètre metrics sur views,estimatedMinutesWatched.
Le propriétaire de la chaîne dispose de plusieurs options pour le paramètre dimensions. 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ètre filters plus loin dans cette section.
- Si vous définissez la valeur du paramètre sur deviceType, les nombres de vues et les durées de visionnage seront regroupés par type d'appareil pour toute 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é regardé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 de durée de visionnage pour chaque type d'appareil.
- Si vous définissez la valeur du paramètre sur day,deviceType, les nombres de vues et les durées de visionnage seront calculés par type d'appareil pour chaque jour de la période du 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 le 1er juin 2015 ?
  - Combien de fois les vidéos de la chaîne ont-elles été regardé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 aux données correspondant à des valeurs de filtre spécifiques. Le rapport est compatible avec un trop grand nombre d'options de filtrage pour que nous puissions toutes les expliquer. Ces exemples ne représentent donc qu'une fraction des rapports que vous pourriez générer.
- Le propriétaire de la chaîne peut filtrer la requête pour renvoyer des valeurs uniquement pour le 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 renvoyer des valeurs uniquement pour un pays spécifique. (Combien de fois les vidéos ont-elles été visionnées au Canada chaque jour de la période du rapport ?)
- Le propriétaire de la chaîne peut filtrer la demande pour renvoyer des valeurs uniquement pour certaines vidéos. Toutefois, le filtre Vidéo accepte 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 video spécifie plusieurs valeurs, video peut également être spécifié comme dimension. Cela signifie que le paramètre dimensions accepte également les valeurs deviceType,video et day,deviceType,video.
  - Si le propriétaire de la chaîne inclut 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 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 ?)

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 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 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 au bout de 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 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.

Par exemple, supposons 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 au cours d'une période donnée. Le deuxième rapport liste 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 deuxième rapport n'inclura pas les vues associées aux éléments supprimés, car il les liste 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 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 :

le trafic d'une vidéo ou d'une chaîne est limité pendant une période donnée ;

ou
vous avez sélectionné un filtre ou une dimension, tels que 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 qu'un propriétaire de chaîne récupère deux rapports. Le premier rapport indique le nombre total de vues d'une vidéo spécifique, tandis que 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 deuxième 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 deuxième rapport ne contiendrait aucune indication selon laquelle deux autres vues ont également été enregistrées (ou que des vues ont été constatées en France).

Les seuils réels à partir desquels 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, comme 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 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, comme 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 très peu de vues n'apparaissent pas dans les rapports. En revanche, vous verrez toujours les termes et les URL qui attirent de nombreux spectateurs vers vos contenus.

Consultez le Centre d'aide YouTube pour en savoir plus sur la disponibilité limitée des données dans les rapports YouTube Analytics.

Utilisation du quota

Chaque requête API que vous envoyez 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.

YouTube Analytics API - Data Model Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.