Reports: Query

Important : Les requêtes API adressé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 demande 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 statistique. Vous pouvez également fournir des paramètres de requête supplémentaires, tels que des dimensions, des filtres et des instructions de tri.

  • Les statistiques correspondent à des mesures individuelles de l'activité des utilisateurs, comme le nombre de vues ou d'avis sur les vidéos ("J'aime" et "Je n'aime pas").
  • Les dimensions sont des critères courants utilisés pour regrouper des données, comme la date à laquelle l'activité de l'utilisateur a eu lieu 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.
  • Les filtres sont des valeurs de dimension qui spécifient les données à récupérer. Par exemple, vous pouvez récupérer les données d'un pays, d'une vidéo ou d'un groupe de vidéos spécifiques.

Remarque:Seuls les partenaires de contenu YouTube qui participent au Programme Partenaire YouTube peuvent accéder aux rapports des propriétaires de contenu.

Cas d'utilisation courants

Demande

Requête HTTP :

GET https://youtubeanalytics.googleapis.com/v2/reports

Toutes les demandes de 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 demandes d'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 relatifs à votre contenu YouTube. Elle permet d'accéder aux métriques d'activité des utilisateurs, comme le nombre de vues et d'avis.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Affichez les rapports monétaires YouTube Analytics relatifs à votre contenu YouTube. Elle permet d'accéder aux métriques d'activité des utilisateurs, ainsi qu'aux métriques sur les revenus estimés 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îne utilisent ce champ d'application pour gérer les groupes et les éléments de groupe YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Affichez et gérez les éléments 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.

Paramètres

Les tableaux suivants répertorient les paramètres de requête obligatoires et facultatifs pour les requêtes API permettant de récupérer les rapports sur les requêtes. Les paramètres de requête standards répertoriés dans le tableau sont également facultatifs et compatibles avec de nombreuses API Google.

Paramètres
Paramètres obligatoires
endDate string
Date de fin de récupération 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 lesquelles toutes les métriques de la requête sont disponibles au moment de la requête. Par exemple, si la demande 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 à laquelle les données seront incluses dans la réponse. (Cela est valable même si des données sont disponibles pour certaines métriques demandées depuis le 4 juillet 2017.)
Remarque : Dans la version 1 de l'API, ce paramètre s'appelait end-date.
ids string
Identifie la chaîne YouTube ou le propriétaire de contenu pour lesquels vous récupérez des données YouTube Analytics.

  • Pour demander des données concernant une chaîne YouTube, définissez la valeur du paramètre ids sur channel==MINE ou channel==CHANNEL_ID, où CHANNEL_ID identifie la chaîne YouTube de l'utilisateur actuellement authentifié.
  • Pour demander des données à un propriétaire de contenu YouTube, définissez la valeur du paramètre ids sur contentOwner==OWNER_NAME, où OWNER_NAME correspond à la valeur content owner ID de l'utilisateur.

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 sur les rapports de propriétaires de contenu pour obtenir la liste des rapports que vous pouvez récupérer et les 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 de 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 s'appelait start-date.
Paramètres facultatifs
currency string
Devise utilisée par l'API pour spécifier les métriques de revenus estimés suivantes: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm et playbackBasedCpm. Les valeurs renvoyées par l'API pour ces métriques sont des estimations calculées à l'aide des 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 de la liste 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 sur les rapports de 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 de filtres à appliquer lors de la récupération des données YouTube Analytics. La documentation sur les rapports sur les canaux et les rapports sur le propriétaire de contenu identifie les dimensions qui permettent de filtrer chaque rapport, et le document Dimensions définit ces dimensions.

Si une demande utilise plusieurs filtres, associez-les à l'aide d'un point-virgule (;), et le tableau des résultats renvoyé satisfera aux deux filtres. Par exemple, si la valeur d'un paramètre filters est video==dMH0bHeiRNg;country==IT, l'ensemble de résultats n'inclut que des données pour la vidéo 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, si la valeur d'un paramètre filters est video==pd1FJh59zxQ,Zhawgd0REhA;country==IT, l'ensemble de résultats n'inclut que les données concernant les vidéos 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 valable même si le filtre n'est pas répertorié en tant que dimension compatible pour un rapport spécifique. Si vous ajoutez le filtre à la liste des dimensions, l'API utilise également les valeurs du 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 regroupe les statistiques de visionnage selon la façon dont les internautes ont accédé au contenu vidéo de la chaîne. Supposons également que la requête de paramètre filters de votre demande identifie une liste de 10 vidéos pour lesquelles des données doivent être renvoyées.
  • Si vous ajoutez video à la valeur du paramètre dimensions, la réponse de l'API fournit des statistiques de source de trafic distinctes pour chacune des 10 vidéos.
  • Si vous n'ajoutez pas video à la valeur du paramètre dimensions, la réponse de l'API regroupera les statistiques sur les sources de trafic des 10 vidéos.
includeHistoricalChannelData boolean
Remarque : Ce paramètre ne s'applique qu'aux rapports de propriétaires de contenu.

Indique si la réponse de l'API doit inclure la durée de visionnage des chaînes et les données sur les vues pour la période antérieure à l'association des chaînes 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 la durée de visionnage et les données sur les vues à partir des dates auxquelles les chaînes étaient associées au propriétaire de contenu.

Il est important de se rappeler que différentes chaînes peuvent avoir été associées à un propriétaire de contenu à différentes dates. Si la requête API récupère des données pour plusieurs canaux 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 de chaque canal respectif. Si la valeur du paramètre est true, la réponse de l'API contient des données correspondant aux dates spécifiées dans la requête API.
Remarque:Dans la version 1 de l'API, ce paramètre s'appelait 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 s'appelait max-results.
sort string
Liste de dimensions ou de métriques séparées par une virgule déterminant l'ordre de tri des données YouTube Analytics. Par défaut, l'ordre de tri est croissant. Le préfixe - entraîne un ordre de tri 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 s'appelait start-index.
Paramètres standards
access_token Jeton OAuth 2.0 pour l'utilisateur actuel.
  • Un moyen de fournir un jeton OAuth 2.0.
alt Ce paramètre n'est pas accepté dans la version 2 de l'API, qui n'accepte que les réponses JSON.Format de données de la réponse de l'API.
  • Valeurs valides : json et csv
  • Valeur par défaut : json
callback Fonction de rappel.
  • Il s'agit du nom de la fonction de rappel JavaScript qui gère la réponse.
  • Utilisé dans les requêtes JavaScript JSON-P.
prettyPrint

Renvoie une réponse avec des indentations et des sauts de ligne.

  • Renvoie la réponse dans un format lisible si true.
  • Valeur par défaut : true
  • Lorsque la valeur est false, la taille de la réponse peut être réduite, ce qui améliore les performances dans certains environnements.
quotaUser Ce paramètre était compatible avec 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 compatible avec 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:

JSON
{
  "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 inclus 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 est compatible avec d'autres méthodes, les réponses de ces méthodes peuvent introduire d'autres valeurs de propriétés kind.
columnHeaders[] list
Cette valeur spécifie les 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 une virgule.

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 des données de la colonne (STRING, INTEGER, FLOAT, etc.).
rows[] list
La liste contient toutes les lignes de la table des résultats. Chaque élément de la liste est un tableau contenant des données séparées par une virgule correspondant à une seule ligne de données. L'ordre des champs de données séparés par une virgule correspond à celui des colonnes répertoriées dans le champ columnHeaders.

Si aucune donnée n'est disponible pour la requête donnée, l'élément rows est omis dans la réponse.

La réponse à une requête avec la dimension day ne contiendra pas les lignes des jours les plus récents.

CSV
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 peuvent ne pas représenter tous les langages de programmation compatibles. Consultez la documentation sur les bibliothèques clientes pour obtenir la liste des langages compatibles.

JavaScript

Cet exemple appelle l'API YouTube Analytics pour récupérer les vues quotidiennes et d'autres métriques concernant 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 localement pour la première fois, vous devez configurer les identifiants d'autorisation pour votre projet :
  1. Créez ou sélectionnez un projet dans la console d'API Google.
  2. Activez l'API YouTube Analytics pour votre projet.
  3. 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 si ce n'est pas déjà fait, puis cliquez sur le bouton "Enregistrer".
  4. Sur la page Identifiants, cliquez sur le bouton Créer des identifiants, puis sélectionnez ID client OAuth.
  5. Sélectionnez le type d'application Web.
  6. Dans le champ "Origines JavaScript autorisées", saisissez l'URL à partir de laquelle vous diffuserez l'exemple de code. Vous pouvez par exemple utiliser http://localhost:8000 ou http://yourserver.example.com. Vous pouvez laisser le champ "URI de redirection autorisés" vide.
  7. Cliquez sur le bouton Créer pour terminer la création de vos identifiants.
  8. Avant de fermer la boîte de dialogue, copiez l'ID client que vous devrez insérer dans l'exemple de code.

Ensuite, enregistrez l'exemple dans un fichier local. Dans l'exemple, recherchez la ligne suivante et remplacez YOUR_CLIENT_ID par l'ID client 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'exemple:

  1. Ouvrez le fichier local à partir d'un navigateur Web et ouvrez la console de débogage dans le navigateur. Une page contenant deux boutons doit s'afficher.
  2. Cliquez sur le bouton Autoriser et charger pour lancer le parcours 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
  3. 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 insérez votre ID client dans le code comme décrit ci-dessus.
  4. 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 est mappée sur 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 concernant 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 localement pour la première fois, vous devez configurer les identifiants d'autorisation pour votre projet :
  1. Créez ou sélectionnez un projet dans la console d'API Google.
  2. Activez l'API YouTube Analytics pour votre projet.
  3. 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 si ce n'est pas déjà fait, puis cliquez sur le bouton "Enregistrer".
  4. Sur la page Identifiants, cliquez sur le bouton Créer des identifiants, puis sélectionnez ID client OAuth.
  5. Sélectionnez le type d'application Autre, saisissez "Guide de démarrage rapide pour l'API YouTube Analytics", puis cliquez sur le bouton "Créer".
  6. Cliquez sur OK pour fermer la boîte de dialogue correspondante.
  7. Cliquez sur le bouton (Télécharger JSON) à droite de l'ID client.
  8. Déplacez le fichier téléchargé dans votre répertoire de travail.

Vous devez également installer la bibliothèque cliente des API Google pour Python et quelques bibliothèques supplémentaires:

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'exemple:

  1. Copiez l'exemple de code ci-dessous dans votre répertoire de travail.
  2. 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.
  3. Exécutez l'exemple de code dans une fenêtre de terminal :
    python yt_analytics_v2.py
  4. Suivez la procédure 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 votre fenêtre de terminal, puis cliquez sur [return].
  5. La requête API s'exécute et la réponse JSON est générée dans la fenêtre de 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 API et la réponse.