YouTube Analytics API: Content Owner Reports

Remarque : Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program.

Cette page liste les rapports que les propriétaires de contenu peuvent récupérer avec l'API YouTube Analytics. Les rapports de propriétaires de contenu contiennent des métriques pour les chaînes associées à un propriétaire de contenu YouTube spécifique. Les métriques sont des mesures individuelles de l'activité des utilisateurs, des performances des annonces ou des revenus estimés.

  • Les rapports vidéo contiennent des métriques sur l'activité des utilisateurs, les performances des annonces et les revenus estimés pour les vidéos des chaînes d'un propriétaire de contenu.

  • Les rapports sur les playlists fournissent des statistiques spécifiques aux vues de vidéos qui se produisent dans le contexte d'une playlist. Les rapports sur les playlists utilisent de nombreuses dimensions et de nombreux filtres identiques à ceux des rapports sur les vidéos.

  • Les rapports sur les performances des annonces contiennent des métriques liées aux revenus et aux performances des annonces. Ils utilisent la dimension adType pour regrouper les métriques en fonction des types d'annonces diffusées lors des lectures de vidéos. La section Rapports sur les performances des annonces explique les deux types de métriques sur les performances des annonces compatibles avec l'API.

Récupérer un rapport

Pour récupérer un rapport sur un propriétaire de contenu, appelez la méthode reports.query de l'API et définissez la valeur de paramètre ids dans la requête API sur contentOwner==OWNER_NAME, où OWNER_NAME spécifie l'ID du propriétaire de contenu. En cas de doute, demandez à votre Partner Manager.

Autorisation

Toutes les requêtes envoyées à l'API YouTube Analytics doivent être autorisées. Le guide d'autorisation explique comment utiliser le protocole OAuth 2.0 pour récupérer des jetons d'autorisation.

Les requêtes de l'API YouTube Analytics utilisent les champs d'application d'autorisation suivants :

Niveaux d'accès
https://www.googleapis.com/auth/yt-analytics.readonly Affichez les rapports YouTube Analytics sur vos contenus YouTube. Ce champ d'application permet d'accéder aux métriques d'activité des utilisateurs, comme le nombre de vues et le nombre de notes.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Affichez les rapports monétaires YouTube Analytics pour vos contenus YouTube. Ce champ d'application permet d'accéder aux métriques sur l'activité des utilisateurs, ainsi qu'aux métriques estimées sur les revenus et les performances des annonces.
https://www.googleapis.com/auth/youtube Gérez votre compte YouTube. Dans l'API YouTube Analytics, les propriétaires de chaînes utilisent ce champ d'application pour gérer les groupes et les éléments de groupe YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Consultez et gérez vos composants YouTube et le contenu associé sur YouTube. Dans l'API YouTube Analytics, les propriétaires de contenu utilisent ce champ d'application pour gérer les groupes et les éléments de groupe YouTube Analytics.

Remarque : Les métriques marquées d'un astérisque (*) nécessitent un jeton d'autorisation qui accorde l'accès au champ d'application https://www.googleapis.com/auth/yt-analytics-monetary.readonly.

Filtres

Toutes les requêtes API permettant de récupérer des rapports sur les propriétaires de contenu doivent filtrer les données à l'aide de la dimension video, de la dimension channel ou d'une combinaison compatible des dimensions claimedStatus et uploaderType. (Les combinaisons compatibles sont listées dans la définition de la dimension uploaderType.)

Les tableaux qui expliquent les rapports compatibles identifient les filtres qui peuvent être utilisés pour un rapport donné. Dans les descriptions, les filtres entre parenthèses sont facultatifs. Par exemple, si un rapport liste video(,country) comme option de filtrage, il peut être filtré pour n'inclure que les données d'une vidéo spécifique ou celles d'une vidéo spécifique dans un pays spécifique.

L'API permet également de spécifier plusieurs valeurs pour les filtres video, playlist et channel. Si vous spécifiez plusieurs valeurs pour l'un de ces filtres, vous pouvez également l'ajouter à la liste des dimensions que vous spécifiez pour la requête. Cela est vrai même si le filtre n'est pas listé comme dimension compatible pour un rapport spécifique.

Consultez la définition du paramètre filters pour obtenir une explication complète sur la façon de filtrer les résultats de l'API pour une valeur ou un ensemble de valeurs spécifiques.

Comprendre les tableaux de rapports

Cette section explique la mise en forme et la terminologie utilisées dans les tableaux qui définissent les rapports compatibles avec l'API. Le tableau suivant liste les dimensions, les métriques et les filtres acceptés pour le rapport vidéo "Détails de la lecture" à l'aide de la dimension temporelle et de la métrique averageViewPercentage.

Sommaire
Dimensions :
Utilisez 0 ou plus creatorContentType, subscribedStatus, youtubeProduct
Utilisez 0 ou 1. jour, mois
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage
Filtres :
Utilisez 0 ou 1. country, province, continent, subContinent
Utilisez 0 ou 1. vidéo, groupe
Utilisez 0 ou plus subscribedStatus, youtubeProduct

Le tableau contient deux lignes pour les dimensions, une ligne pour les métriques et trois lignes pour les filtres. Pour les dimensions et les filtres, les valeurs de chaque ligne peuvent être combinées dans une requête API, à condition que la combinaison respecte les règles d'utilisation du tableau. Par exemple, les valeurs de paramètre dimensions valides pour ce rapport incluent :

  • dimensions=day
  • dimensions=day,subscribedStatus
  • dimensions=month,subscribedStatus,youtubeProduct
  • dimensions=month,youtubeProduct

Toutefois, la valeur du paramètre day,month n'est pas valide, car elle utilise deux dimensions temporelles. La requête doit utiliser 0 ou 1.

Alors que les tableaux de rapports définissent les dimensions, les métriques et les filtres acceptés, l'API applique des contraintes inter-paramètres. L'interrogation de combinaisons non compatibles ou mutuellement exclusives (par exemple, la combinaison de filtres géographiques incompatibles ou l'omission de paramètres obligatoires) entraîne une erreur HTTP 400 badRequest avec le message The query is not supported. Consultez les tableaux de rapports individuels sur cette page pour connaître les restrictions spécifiques qui s'appliquent à chaque rapport.

Terminologie des tableaux de rapports

Les tableaux utilisent la terminologie suivante pour indiquer si les dimensions sont obligatoires ou facultatives :

  • Ces termes indiquent qu'une valeur est requise :
    • Obligatoire : vous devez inclure la valeur.
    • Utiliser exactement 1 : vous devez inclure une valeur du groupe.
    • Utilisez une ou plusieurs valeurs : vous pouvez inclure toutes les valeurs du groupe ou une partie d'entre elles, mais vous devez en inclure au moins une.
  • Ces termes indiquent qu'une valeur est facultative :
    • Facultatif : vous pouvez inclure la valeur.
    • Utilisez 0 ou 1 : vous pouvez inclure une valeur du groupe.
    • Utiliser zéro valeur ou plus : vous pouvez inclure tout ou partie des valeurs du groupe.
Important : Toutes les requêtes d'API permettant de récupérer des rapports sur les vidéos d'un propriétaire de contenu doivent filtrer les données à l'aide de la dimension video, channel ou group, ou d'une combinaison compatible des dimensions claimedStatus et uploaderType. (Certains rapports ne sont pas compatibles avec toutes ces options.) Les combinaisons acceptées, qui sont également listées dans la définition de la dimension uploaderType, sont les suivantes :
  • uploaderType==self
  • claimedStatus==claimed
  • claimedStatus==claimed;uploaderType==self
  • claimedStatus==claimed;uploaderType==thirdParty

Signalements de vidéos

Statistiques de base

Statistiques de base (y compris le nombre d'abonnés)

Ce rapport fournit des statistiques sur les actions des utilisateurs sur toutes les chaînes d'un propriétaire de contenu. Vous pouvez filtrer le rapport pour n'afficher que les données d'une vidéo ou d'un pays spécifique. Vous pouvez également l'utiliser pour récupérer uniquement les statistiques des contenus revendiqués, y compris ceux mis en ligne par le propriétaire du contenu, des tiers ou les deux.

Sommaire
Dimensions :
[None]
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, comments, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks, subscribersGained, subscribersLost, estimatedRevenue*, estimatedAdRevenue*, grossRevenue*, estimatedRedPartnerRevenue
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Utilisez 0 ou 1. country, continent, subContinent

Statistiques de base pour les États américains

Ce rapport fournit des statistiques pour un État américain ou le district de Columbia. Notez que ce rapport n'est compatible qu'avec un sous-ensemble des métriques disponibles dans le rapport spécifique à un pays décrit ci-dessus.

Sommaire
Dimensions :
[None]
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Obligatoire province

En fonction du temps

Activité pour les périodes

Ce rapport fournit des statistiques sur les actions des utilisateurs sur toutes les chaînes d'un propriétaire de contenu pour des intervalles de temps spécifiques. Vous pouvez filtrer le rapport pour n'afficher que les données d'une vidéo ou d'un pays spécifique.

Sommaire
Dimensions :
Utiliser exactement 1 jour, mois
Facultatif creatorContentType
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, comments, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks, subscribersGained, subscribersLost, uniques, estimatedRevenue*, estimatedAdRevenue*, grossRevenue*, estimatedRedPartnerRevenue*, monetizedPlaybacks*, playbackBasedCpm*, adImpressions*, cpm*
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Utilisez 0 ou 1. country, continent, subContinent

Activité des utilisateurs dans les États américains pour des périodes spécifiques

Ce rapport fournit des statistiques pour un État américain ou le district de Columbia. Notez que ce rapport n'est compatible qu'avec un sous-ensemble des métriques disponibles dans le rapport spécifique à un pays décrit ci-dessus.

Sommaire
Dimensions :
Utiliser exactement 1 jour, mois
Facultatif creatorContentType
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Obligatoire province

Zone géographique de l'utilisateur

Activité des utilisateurs par pays

Ce rapport fournit des statistiques sur l'activité des utilisateurs pour tous les canaux d'un propriétaire de contenu, pays par pays. Vous pouvez filtrer le rapport pour n'afficher que les données d'une vidéo ou d'une chaîne spécifique.

Sommaire
Dimensions :
Obligatoire country
Facultatif creatorContentType
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, comments, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks, subscribersGained, subscribersLost, estimatedRevenue*, estimatedAdRevenue*, grossRevenue*, estimatedRedPartnerRevenue*, monetizedPlaybacks*, playbackBasedCpm*, adImpressions*, cpm*
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Utilisez 0 ou 1. continent, subContinent

Activité des utilisateurs par province

Ce rapport fournit des statistiques sur l'activité des utilisateurs pour les États américains et le district de Columbia. Pour ce rapport, vous devez définir la valeur du paramètre filters sur country==US.

Sommaire
Dimensions :
Obligatoire province
Facultatif creatorContentType
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Obligatoire country==US

Détails de la lecture

Les rapports détaillés sur la lecture fournissent des statistiques liées aux attributs de visionnage suivants :

  • S'agissait-il d'une vue d'une vidéo diffusée en direct ou d'une vidéo à la demande ?
  • Le spectateur était-il abonné à la chaîne qui possède la vidéo ?
  • Sur quel produit YouTube la vue a-t-elle été enregistrée ?

Techniquement, les dimensions de détails de lecture compatibles avec ces rapports sont toutes facultatives. Si vous n'incluez pas de dimensions de détails de lecture dans votre demande, le rapport renvoyé sera en fait semblable à l'un des rapports Statistiques de base, Basé sur le temps ou Géographie des utilisateurs.

Remarque : La dimension et le filtre liveOrOnDemand ne peuvent pas être utilisés avec la métrique averageViewPercentage. Par conséquent, chacune des sous-sections suivantes liste deux rapports. Un rapport est compatible avec la dimension (et le filtre) liveOrOnDemand, tandis que l'autre est compatible avec la métrique averageViewPercentage.

Activité des utilisateurs par état d'abonnement

Ce rapport fournit des métriques sur l'activité des utilisateurs abonnés et non abonnés. Les statistiques peuvent être regroupées par période (jour ou mois). Le rapport peut également être filtré par pays, continent ou subContinent.

Sommaire
Dimensions :
Utilisez 0 ou plus creatorContentType, subscribedStatus
Utilisez 0 ou 1. jour, mois
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, likes, dislikes, videosAddedToPlaylists, videosRemovedFromPlaylists, shares, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Utilisez 0 ou 1. country, continent, subContinent
Facultatif subscribedStatus

Activité des utilisateurs par état d'abonnement pour les provinces

Ce rapport fournit des métriques sur l'activité des utilisateurs abonnés et non abonnés dans les États américains ou dans le district de Columbia. Ce rapport accepte moins de métriques que le précédent.

Sommaire
Dimensions :
Utilisez 0 ou plus creatorContentType, subscribedStatus
Utilisez 0 ou 1. jour, mois
Métriques :
Utilisez un ou plusieurs engagedViews, views, redViews, estimatedMinutesWatched, estimatedRedMinutesWatched, averageViewDuration, averageViewPercentage, annotationClickThroughRate, annotationCloseRate, annotationImpressions, annotationClickableImpressions, annotationClosableImpressions, annotationClicks, annotationCloses, cardClickRate, cardTeaserClickRate, cardImpressions, cardTeaserImpressions, cardClicks, cardTeaserClicks
Filtres :
Utiliser exactement 1 video, channel, group ou une combinaison compatible de uploaderType et claimedStatus
Obligatoire province
Facultatif subscribedStatus

Détails de la lecture avec une dimension temporelle facultative

La dimension temporelle (jour ou mois) est facultative pour ces rapports, car vous devez de toute façon utiliser les paramètres de requête startDate et endDate pour spécifier la plage de dates que le rapport couvrira. Si elle est présente, la dimension indique que vous souhaitez que les données du rapport soient agrégées par jour, par mois, etc.

Détails de la lecture avec dimension temporelle facultative et statistiques liveOrOnDemand

Ce rapport fournit des statistiques détaillées sur la lecture pour des intervalles de temps spécifiques. Il est compatible avec la dimension (et le filtre)