Important : Les requêtes d'API envoyées à cette méthode nécessitent désormais l'accès au champ d'application https://www.googleapis.com/auth/youtube.readonly
.
Cette méthode vous permet de récupérer de nombreux rapports Analytics différents. Chaque requête utilise des paramètres de requête pour spécifier un ID de chaîne ou un propriétaire de contenu, une date de début, une date de fin et au moins une métrique. Vous pouvez également fournir des paramètres de requête supplémentaires, tels que des dimensions, des filtres et des instructions de tri.
- Les métriques sont des mesures individuelles de l'activité des utilisateurs, comme les vues de vidéos ou les évaluations (mentions "J'aime" et "Je n'aime pas").
- Les dimensions sont des critères courants utilisés pour agréger les données, comme la date à laquelle l'activité de l'utilisateur 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.
- Les filtres sont des valeurs de dimension qui spécifient les données à récupérer. Par exemple, vous pouvez récupérer des données pour un pays spécifique, une vidéo spécifique ou un groupe de vidéos.
Remarque : Les rapports sur les propriétaires de contenu ne sont accessibles qu'aux partenaires de contenu YouTube qui participent au Programme Partenaire YouTube.
Cas d'utilisation courants
Requête
Requête HTTP
GET https://youtubeanalytics.googleapis.com/v2/reports
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 votre contenu 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 concernant votre contenu 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 éléments 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. |
Paramètres
Les tableaux suivants listent les paramètres de requête obligatoires et facultatifs pour les requêtes d'API permettant de récupérer des rapports sur les requêtes. Les paramètres de requête standards listés dans le tableau sont également facultatifs et sont compatibles avec de nombreuses API Google.
Paramètres | ||
---|---|---|
Paramètres obligatoires | ||
endDate |
string Date de fin pour l'extraction des données YouTube Analytics. La valeur doit être au format YYYY-MM-DD .La réponse de l'API contient des données jusqu'au dernier jour pour lequel toutes les métriques de la requête sont disponibles au moment de la requête. Par exemple, si la requête spécifie une date de fin au 5 juillet 2017 et que les valeurs de toutes les métriques demandées ne sont disponibles que jusqu'au 3 juillet 2017, il s'agira de la dernière date pour laquelle des données seront incluses dans la réponse. (Cela est vrai même si les données de certaines des métriques demandées sont disponibles pour le 4 juillet 2017.) Remarque : Dans la version 1 de l'API, ce paramètre était nommé end-date |
|
ids |
string Identifie la chaîne YouTube ou le propriétaire de contenu pour lesquels vous récupérez les données YouTube Analytics.
|
|
metrics |
string Liste de métriques YouTube Analytics séparées par une virgule, telles que views ou likes,dislikes . Consultez la documentation sur les rapports sur les chaînes ou les rapports sur les propriétaires de contenu pour obtenir la liste des rapports que vous pouvez récupérer et des métriques disponibles dans chaque rapport. (Le document Métriques contient les définitions de toutes les métriques.)
|
|
startDate |
string Date de début pour la récupération des données YouTube Analytics. La valeur doit être au format YYYY-MM-DD .Remarque : Dans la version 1 de l'API, ce paramètre était nommé
start-date |
|
Paramètres facultatifs | ||
currency |
string Devise que l'API utilisera pour spécifier les métriques de revenus estimés suivantes : estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. Les valeurs que l'API renvoie pour ces métriques sont des estimations calculées à l'aide de taux de change qui changent quotidiennement. Si aucune de ces métriques n'est demandée, le paramètre est ignoré. La valeur du paramètre est un code de devise ISO 4217 à trois lettres figurant dans la liste des devises ci-dessous. L'API renvoie une erreur si une devise non acceptée est spécifiée. La valeur par défaut est USD . |
|
dimensions |
string Liste de dimensions YouTube Analytics séparées par une virgule, comme video ou ageGroup,gender . Consultez la documentation sur les rapports sur les chaînes ou les rapports sur les propriétaires de contenu pour obtenir la liste des rapports que vous pouvez récupérer et les dimensions utilisées pour ces rapports. (Le document Dimensions contient les définitions de toutes les dimensions.)
|
|
filters |
string Liste des filtres à appliquer lors de la récupération des données YouTube Analytics. La documentation sur les rapports sur les chaînes et les rapports sur les propriétaires de contenu identifie les dimensions pouvant être utilisées pour filtrer chaque rapport. Le document Dimensions définit ces dimensions. Si une requête utilise plusieurs filtres, joignez-les avec un point-virgule ( ; ). La table de résultats renvoyée répondra aux deux filtres. Par exemple, une valeur de paramètre filters de video==dMH0bHeiRNg;country==IT limite l'ensemble de résultats pour inclure les données de la vidéo donnée en Italie.Spécifier plusieurs valeurs pour un filtre L'API permet de spécifier plusieurs valeurs pour les filtres video , playlist et channel . Pour ce faire, spécifiez une liste séparée des ID de vidéos, de playlists ou de chaînes pour lesquels la réponse de l'API doit être filtrée. Par exemple, une valeur de paramètre filters de video==pd1FJh59zxQ,Zhawgd0REhA;country==IT limite l'ensemble de résultats aux données des vidéos concernées en Italie. La valeur du paramètre peut spécifier jusqu'à 500 ID.Lorsque vous spécifiez plusieurs valeurs pour le même filtre, vous pouvez également ajouter ce filtre à la liste des dimensions que vous spécifiez pour la requête. Cela est vrai même si le filtre n'est pas répertorié comme dimension compatible pour un rapport spécifique. Si vous ajoutez le filtre à la liste des dimensions, l'API utilise également les valeurs de filtre pour regrouper les résultats. Par exemple, supposons que vous récupériez le rapport sur les sources de trafic d'une chaîne, qui agrège les statistiques de visionnage en fonction de la manière dont les spectateurs ont accédé au contenu vidéo de la chaîne. Supposons également que le paramètre filters de votre requête identifie une liste de 10 vidéos pour lesquelles des données doivent être renvoyées.
|
|
includeHistoricalChannelData |
boolean Remarque : Ce paramètre ne s'applique qu'aux rapports sur les propriétaires de contenu. Indique si la réponse de l'API doit inclure les données sur la durée de visionnage et les vues des chaînes pour la période précédant leur association au propriétaire de contenu. La valeur par défaut du paramètre est false , ce qui signifie que la réponse de l'API n'inclut que les données sur la durée de visionnage et les vues à partir des dates auxquelles les chaînes ont été associées au propriétaire du contenu.N'oubliez pas que différentes chaînes peuvent avoir été associées à un propriétaire de contenu à des dates différentes. Si la requête API récupère des données pour plusieurs chaînes et que la valeur du paramètre est false , la réponse de l'API contient des données basées sur la date d'association pour chaque chaîne concernée. Si la valeur du paramètre est true , la réponse de l'API contient les données correspondant aux dates spécifiées dans la requête API.Remarque : Dans la version 1 de l'API, ce paramètre était nommé include-historical-channel-data |
|
maxResults |
integer Nombre maximal de lignes à inclure dans la réponse. Remarque : Dans la version 1 de l'API, ce paramètre était nommé max-results |
|
sort |
string Liste de dimensions ou de métriques séparées par une virgule qui déterminent l'ordre de tri des données YouTube Analytics. Par défaut, l'ordre de tri est croissant. Le préfixe - entraîne un tri par ordre décroissant.
|
|
startIndex |
integer Index en base 1 de la première entité à récupérer. (La valeur par défaut est 1 .) Utilisez ce paramètre comme mécanisme de pagination avec le paramètre max-results .Remarque : Dans la version 1 de l'API, ce paramètre était nommé start-index |
|
Paramètres standards | ||
access_token |
Jeton OAuth 2.0 pour l'utilisateur actuel.
|
|
alt |
Ce paramètre n'est pas compatible avec la version 2 de l'API, qui n'accepte que les réponses JSON.Format des données pour la réponse de l'API.
|
|
callback |
Fonction de rappel.
|
|
prettyPrint |
Renvoie une réponse avec des indentations et des sauts de ligne.
|
|
quotaUser |
Ce paramètre était accepté dans la version 1 de l'API, qui est désormais obsolète. Ce paramètre n'est pas compatible avec la version 2 de l'API. | |
userIp |
Ce paramètre était accepté dans la version 1 de l'API, qui est désormais obsolète. Ce paramètre n'est pas compatible avec la version 2 de l'API. |
Corps de la requête
N'envoyez pas de corps de requête lorsque vous appelez cette méthode.
Réponse
Comme indiqué dans la définition du paramètre alt
, l'API peut renvoyer des réponses au format JSON ou CSV. Vous trouverez ci-dessous des informations sur le corps de la réponse pour chaque type :
{ "kind": "youtubeAnalytics#resultTable", "columnHeaders": [ { "name": string, "dataType": string, "columnType": string }, ... more headers ... ], "rows": [ [ {value}, {value}, ... ] ] }
Propriétés | |
---|---|
kind |
string Cette valeur spécifie le type de données incluses dans la réponse de l'API. Pour la méthode query , la valeur de la propriété kind sera youtubeAnalytics#resultTable . Toutefois, si l'API prend en charge d'autres méthodes, les réponses de l'API pour ces méthodes peuvent introduire d'autres valeurs de propriété kind . |
columnHeaders[] |
list Cette valeur spécifie des informations sur les données renvoyées dans les champs rows . Chaque élément de la liste columnHeaders identifie un champ renvoyé dans la valeur rows , qui contient une liste de données séparées par des virgules.La liste columnHeaders commence par les dimensions spécifiées dans la requête API, suivies des métriques spécifiées dans la requête API. L'ordre des dimensions et des métriques correspond à celui de la requête API.Par exemple, si la requête API contient les paramètres dimensions=ageGroup,gender&metrics=viewerPercentage , la réponse de l'API renvoie les colonnes dans cet ordre : ageGroup ,gender ,viewerPercentage . |
columnHeaders[].name |
string Nom de la dimension ou de la métrique. |
columnHeaders[].columnType |
string Type de la colonne ( DIMENSION ou METRIC ). |
columnHeaders[].dataType |
string Type de données de la colonne ( STRING , INTEGER , FLOAT , etc.). |
rows[] |
list La liste contient toutes les lignes du tableau de résultats. Chaque élément de la liste est un tableau contenant des données séparées par des virgules et correspondant à une seule ligne de données. L'ordre des champs de données séparés par une virgule correspond à l'ordre des colonnes listées dans le champ columnHeaders .Si aucune donnée n'est disponible pour la requête donnée, l'élément rows sera omis de la réponse.La réponse à une requête avec la dimension day ne contiendra pas de lignes pour les jours les plus récents. |
day, views, likes, ... "2012-01-01", 12.0, 3, ... "2012-01-02", 16.0, 2, ... "2012-01-03", 18.0, 8, ... ...
Exemples
Remarque : Les exemples de code suivants ne représentent pas forcément tous les langages de programmation compatibles. Consultez la documentation des bibliothèques clientes pour obtenir la liste des langages acceptés.
JavaScript
Cet exemple appelle l'API YouTube Analytics pour récupérer les vues quotidiennes et d'autres métriques pour la chaîne de l'utilisateur autorisé pour l'année civile 2017. L'exemple utilise la bibliothèque cliente JavaScript des API Google.Avant d'exécuter cet exemple en local pour la première fois, vous devez configurer les identifiants d'autorisation pour votre projet :
- Créez ou sélectionnez un projet dans la console Google APIs.
- Activez l'API YouTube Analytics pour votre projet.
- En haut de la page Identifiants, sélectionnez l'onglet Écran d'autorisation OAuth. Sélectionnez une adresse e-mail, saisissez un nom de produit s'il n'est pas déjà défini, puis cliquez sur le bouton "Enregistrer".
- Sur la page Identifiants, cliquez sur le bouton Créer des identifiants, puis sélectionnez ID client OAuth.
- Sélectionnez le type d'application "Application Web".
- Dans le champ "Origines JavaScript autorisées", saisissez l'URL à partir de laquelle vous diffuserez l'exemple de code. Par exemple, vous pouvez utiliser
http://localhost:8000
ouhttp://yourserver.example.com
. Vous pouvez laisser le champ "URI de redirection autorisés" vide. - Cliquez sur le bouton Créer pour terminer la création de vos identifiants.
- Avant de fermer la boîte de dialogue, copiez l'ID client, dont vous aurez besoin pour l'insérer dans l'exemple de code.
Ensuite, enregistrez l'échantillon dans un fichier local. Dans l'exemple, recherchez la ligne suivante et remplacez YOUR_CLIENT_ID par l'ID client que vous avez obtenu lors de la configuration de vos identifiants d'autorisation.
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
Vous êtes maintenant prêt à tester l'échantillon :
- Ouvrez le fichier local à partir d'un navigateur Web, puis ouvrez la console de débogage dans le navigateur. Une page affichant deux boutons devrait s'afficher.
- Cliquez sur le bouton Autoriser et charger pour lancer le flux d'autorisation de l'utilisateur. Si vous autorisez l'application à récupérer les données de votre chaîne, les lignes suivantes devraient s'afficher dans la console du navigateur :
Sign-in successful GAPI client loaded for API
- Si un message d'erreur s'affiche à la place des lignes ci-dessus, vérifiez que vous chargez le script à partir de l'URI de redirection autorisé que vous avez configuré pour votre projet et que vous avez inséré votre ID client dans le code comme décrit ci-dessus.
- Cliquez sur le bouton Exécuter pour appeler l'API. Un objet
response
doit s'afficher dans la console du navigateur. Dans cet objet, la propriétéresult
correspond à un objet contenant les données de l'API.
<script src="https://apis.google.com/js/api.js"></script> <script> function authenticate() { return gapi.auth2.getAuthInstance() .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"}) .then(function() { console.log("Sign-in successful"); }, function(err) { console.error("Error signing in", err); }); } function loadClient() { return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2") .then(function() { console.log("GAPI client loaded for API"); }, function(err) { console.error("Error loading GAPI client for API", err); }); } // Make sure the client is loaded and sign-in is complete before calling this method. function execute() { return gapi.client.youtubeAnalytics.reports.query({ "ids": "channel==MINE", "startDate": "2017-01-01", "endDate": "2017-12-31", "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained", "dimensions": "day", "sort": "day" }) .then(function(response) { // Handle the results here (response.result has the parsed body). console.log("Response", response); }, function(err) { console.error("Execute error", err); }); } gapi.load("client:auth2", function() { gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'}); }); </script> <button onclick="authenticate().then(loadClient)">authorize and load</button> <button onclick="execute()">execute</button>
Python
Cet exemple appelle l'API YouTube Analytics pour récupérer les vues quotidiennes et d'autres métriques pour la chaîne de l'utilisateur autorisé pour l'année civile 2017. L'exemple utilise la bibliothèque cliente Python des API Google.Avant d'exécuter cet exemple en local pour la première fois, vous devez configurer les identifiants d'autorisation pour votre projet :
- Créez ou sélectionnez un projet dans la console Google APIs.
- Activez l'API YouTube Analytics pour votre projet.
- En haut de la page Identifiants, sélectionnez l'onglet Écran d'autorisation OAuth. Sélectionnez une adresse e-mail, saisissez un nom de produit s'il n'est pas déjà défini, puis cliquez sur le bouton "Enregistrer".
- Sur la page Identifiants, cliquez sur le bouton Créer des identifiants, puis sélectionnez ID client OAuth.
- Sélectionnez le type d'application Autre, saisissez le nom "YouTube Analytics API Quickstart" (Démarrage rapide de l'API YouTube Analytics), puis cliquez sur le bouton "Créer".
- Cliquez sur OK pour fermer la boîte de dialogue qui s'affiche.
- Cliquez sur le bouton (Télécharger JSON) à droite de l'ID client.
- Déplacez le fichier téléchargé vers votre répertoire de travail.
Vous devez également installer la bibliothèque cliente des API Google pour Python et d'autres bibliothèques :
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
Vous êtes maintenant prêt à tester l'échantillon :
- Copiez l'exemple de code ci-dessous dans votre répertoire de travail.
- Dans l'exemple, mettez à jour la valeur de la variable
CLIENT_SECRETS_FILE
pour qu'elle corresponde à l'emplacement du fichier que vous avez téléchargé après avoir configuré vos identifiants d'autorisation. - Exécutez l'exemple de code dans une fenêtre de terminal :
python yt_analytics_v2.py
- Suivez le flux d'autorisation. Le flux d'authentification peut se charger automatiquement dans votre navigateur, ou vous devrez peut-être copier l'URL d'authentification dans une fenêtre de navigateur. À la fin du flux d'autorisation, si nécessaire, collez le code d'autorisation affiché dans le navigateur dans la fenêtre de terminal, puis appuyez sur [Retour].
- La requête API s'exécute et la réponse JSON est affichée dans la fenêtre du terminal.
# -*- coding: utf-8 -*- import os import google.oauth2.credentials import google_auth_oauthlib.flow from googleapiclient.discovery import build from googleapiclient.errors import HttpError from google_auth_oauthlib.flow import InstalledAppFlow SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly'] API_SERVICE_NAME = 'youtubeAnalytics' API_VERSION = 'v2' CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json' def get_service(): flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES) credentials = flow.run_console() return build(API_SERVICE_NAME, API_VERSION, credentials = credentials) def execute_api_request(client_library_function, **kwargs): response = client_library_function( **kwargs ).execute() print(response) if __name__ == '__main__': # Disable OAuthlib's HTTPs verification when running locally. # *DO NOT* leave this option enabled when running in production. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' youtubeAnalytics = get_service() execute_api_request( youtubeAnalytics.reports().query, ids='channel==MINE', startDate='2017-01-01', endDate='2017-12-31', metrics='estimatedMinutesWatched,views,likes,subscribersGained' dimensions='day', sort='day' )
Essayer
Utilisez APIs Explorer pour appeler cette API et afficher la requête et la réponse de l'API.