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 sur les chaînes et les propriétaires de contenu. Les champs des rapports sont considérés comme des dimensions ou des métriques:

Les dimensions sont des critères courants utilisés pour regrouper 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 possède une combinaison unique de valeurs de dimension. Par conséquent, les dimensions que vous choisissez pour un rapport déterminent la manière 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 avis ("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 de manière native ces fonctions. L'API vous permet également de récupérer les données des groupes YouTube Analytics. Un groupe est une collection personnalisée rassemblant un maximum de 500 vidéos, playlists, chaînes ou éléments.

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 pendant laquelle le rapport contiendra des données. La réponse de l'API contient en fait les données jusqu'au dernier jour spécifié, pour lesquelles toutes les métriques dans 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 canaux, 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 relatives à une chaîne, un rapport peut être filtré de manière à n'afficher que les statistiques 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 vidéo, playlist et chaîne. Dans ce cas, vous pouvez également inclure ce filtre dans la liste afin que les statistiques 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 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. En fonction de ces valeurs, le rapport contiendra des données sur une période de deux mois.
Le rapport sur le type d'appareil accepte 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 listées dans la liste suivante, et une troisième est expliquée plus loin dans la section consacrée à la valeur du paramètre filters.
- 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 toute la période couverte par le rapport. Ainsi, les données du rapport répondront aux questions suivantes:
  - Combien de fois les vidéos de la chaîne ont-elles été regardé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 indiquera le nombre total de vues et la durée de visionnage pour chaque type d'appareil.
- Si vous définissez le paramètre sur day,deviceType, le nombre de vues et la durée de visionnage sont calculés par type d'appareil pour chaque jour de la période du rapport. Ainsi, les données du rapport répondront aux questions suivantes:
  - Combien de fois les vidéos de la chaîne ont-elles été regardées sur des appareils mobiles le 1er juin 2015 ?
  - Combien de fois les vidéos de la chaîne ont-elles été regardées à la télévision le 14 juillet 2015 ?
Enfin, le paramètre filters permet au propriétaire de la chaîne de limiter le rapport à n'inclure que les données correspondant à des valeurs de filtre spécifiques. Étant donné que le rapport accepte un trop grand nombre d'options de filtrage pour chacune d'entre elles, ces exemples ne représentent qu'une petite partie des rapports que vous pouvez générer.
- Le propriétaire de la chaîne peut filtrer la demande pour n'afficher que les valeurs correspondant au système d'exploitation Android. (Combien de vues ont été réalisé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 demande pour n'afficher que les valeurs correspondant à un pays donné. (Combien de fois des 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 demande pour n'afficher que les valeurs correspondant à des vidéos spécifiques. Cependant, comme le filtre video accepte une liste de valeurs séparées par des virgules, le rapport pourrait contenir des données pour de nombreuses vidéos.
  
  En outre, si le filtre video spécifie plusieurs valeurs, video peut également être spécifié en tant que 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 indiquent les valeurs individuelles de chaque vidéo. (Combien de fois la vidéo XYZ a-t-elle été regardé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 indiquent 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 sur les rapports de propriétaires de contenu pour obtenir la liste des rapports compatibles avec l'API. Chaque définition de rapport identifie les valeurs autorisées par le rapport pour les paramètres metrics, dimensions et filters.

Bonnes pratiques

Les applications qui utilisent l'API YouTube Analytics doivent toujours respecter les pratiques suivantes:

Utilisez l'en-tête de la réponse pour déterminer l'ordre des colonnes du rapport. Par exemple, ne partez pas du principe que les vues seront la première métrique affichée dans une réponse simplement parce qu'il s'agit de la première métrique répertorié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. Conformément aux Conditions d'utilisation des services d'API YouTube (sections III.E.4.b à III.E.4.d), les clients API doivent soit supprimer, soit actualiser les métadonnées de ressources stockées à partir de cette API au bout de 30 jours.

Regrouper les métriques et les éléments supprimés

Les réponses de l'API YouTube Analytics ne contiennent pas de statistiques détaillées 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 répertoriée dans une réponse d'API qui renvoie des métriques vidéo par vidéo. Toutefois, les rapports qui regroupent les métriques d'un ensemble de ressources incluent toujours les métriques associées aux éléments supprimés.

Par exemple, supposons qu'un propriétaire de canal récupère deux rapports. Le premier rapport indique le nombre total de vues quotidiennes de toutes les vidéos de la chaîne sur une période donnée. Le second rapport répertorie le nombre total de vues quotidiennes par vidéo au cours de la même période.

Dans ce cas, les valeurs indiquées dans le premier rapport incluront le nombre de vues des vidéos supprimées par la suite, car le premier rapport contient des données cumulées quotidiennes. Toutefois, le deuxième rapport n'inclura pas les vues associées aux éléments supprimés, car le second répertorie les vues de chaque 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 vues quotidiennes enregistrées 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 ne contient pas tout ou partie de vos données si:

Le trafic d'une vidéo ou d'une chaîne sur une période donnée est limité.

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

Lorsque les données sont limitées, il peut y avoir une différence entre les totaux indiqués dans les différents rapports, selon la manière dont ces rapports regroupent les données.

Par exemple, supposons qu'un propriétaire de canal récupère deux rapports. Le premier rapport indique le nombre total de vues pour une vidéo spécifique, et le second rapport présente le nombre total de vues pour cette vidéo par pays. Imaginons que la vidéo ait été vue 1 000 fois pendant cette période, avec 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é vue 1 000 fois. Le deuxième rapport indiquerait que la vidéo a été vue 500 fois aux États-Unis et 498 fois au Canada. Ainsi, il existe une différence entre le nombre total de vues dans les deux rapports. Notez que le deuxième rapport ne contient aucune indication que deux autres vues se sont également produites (ni que des vues se sont produites 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 (âge et sexe, par exemple)
Données géographiques, y compris les métriques ou dimensions liées aux pays ou régions où les spectateurs se trouvaient (par exemple, leurs pays ou régions). Toutefois, notez que les rapports n'appliquent pas de seuils géographiques aux métriques sur les revenus.
Statistiques liées à des sources de trafic spécifiques (termes de recherche ou URL externes ayant généré des vues de vos vidéos, par exemple) Par exemple, les termes de recherche et les URL qui génèrent un nombre très faible de vues n'apparaissent pas dans les rapports. Toutefois, vous verrez tout de même des termes et des URL qui conduisent un grand nombre de spectateurs à consulter votre contenu.

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

Utilisation du quota

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