Reports: Query

Important:Les requêtes API envoyées à cette méthode nécessitent désormais un accès au champ d'application https://www.googleapis.com/auth/youtube.readonly.

Cette méthode vous permet d'extraire 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 métrique. Vous pouvez également fournir d'autres paramètres de requête, tels que des dimensions, des filtres et des instructions de tri.

  • Les métriques correspondent à des mesures individuelles de l'activité des utilisateurs, comme le nombre de vues des vidéos ou les notes (J'aime et Je n'aime pas).
  • Les dimensions sont des critères courants utilisés pour agréger des données, comme la date à laquelle l'utilisateur a effectué l'activité ou le pays dans lequel se trouvaient les utilisateurs. Dans un rapport, chaque ligne de données est associée à une combinaison unique de valeurs de dimension.
  • Les filtres sont des valeurs de dimensions qui spécifient les données à récupérer. Par exemple, vous pouvez récupérer les données pour un pays, une vidéo en particulier ou un groupe de vidéos en particulier.

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

Cas d'utilisation courants

Requête

Requête HTTP

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

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

Les requêtes API YouTube Analytics utilisent les niveaux d'autorisation suivants:

Lunettes
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 sur l'activité des utilisateurs, comme le nombre de vues et le nombre de notes.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Consultez 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 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înes utilisent ce champ pour gérer les groupes et les éléments de groupes 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 pour gérer les groupes et les éléments de groupes YouTube Analytics.

Paramètres

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

Paramètres
Paramètres obligatoires
endDate string
Date de fin de 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 date de fin de la demande est le 5 juillet 2017 et que les valeurs de toutes les métriques demandées ne sont disponibles que jusqu'au 3 juillet 2017, ces données seront incluses dans la réponse pour la dernière fois. (Cela est vrai même si les données de certaines métriques demandées sont disponibles pour 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 lequel vous souhaitez récupérer des données YouTube Analytics.

  • Pour demander des données pour 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 pour un propriétaire de contenu YouTube, définissez la valeur du paramètre ids sur contentOwner==OWNER_NAME, où OWNER_NAME correspond à la 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 relative aux rapports sur les canaux ou aux rapports sur les propriétaires de contenu pour découvrir la liste des rapports que vous pouvez récupérer et les métriques disponibles dans chacun d'eux. Le document Métriques contient les définitions de toutes les métriques.
startDate string
Date de début de l'extraction 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 sur les revenus estimés suivantes: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, 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 dans la liste des devises ci-dessous. L'API renvoie une erreur si une devise non prise en charge est spécifiée. La valeur par défaut est USD.
dimensions string
Liste de dimensions YouTube Analytics séparées par une virgule, telles que video ou ageGroup,gender. Consultez la documentation concernant les rapports sur les canaux ou les rapports sur les propriétaires de contenu pour connaître 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 canaux et les rapports sur les propriétaires de contenu identifie les dimensions qui peuvent être utilisées pour 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 (;). Le tableau de résultats renvoyé respectera les deux filtres. Par exemple, si la valeur du paramètre filters est video==dMH0bHeiRNg;country==IT, l'ensemble de résultats est limité aux données de 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 d'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 du paramètre filters est video==pd1FJh59zxQ,Zhawgd0REhA;country==IT, l'ensemble de résultats est limité 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. Ce principe s'applique même si le filtre n'est pas listé comme dimension acceptée pour un rapport particulier. 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 en fonction de la manière dont les internautes ont accédé au contenu vidéo de la chaîne. Supposons également que la demande 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 fournira 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 des sources de trafic pour les 10 vidéos.
includeHistoricalChannelData boolean
Remarque:Ce paramètre ne s'applique qu'aux rapports du propriétaire de contenu.

Indique si la réponse de l'API doit inclure la durée de visionnage et les données sur les vues des chaînes pour la période précédant l'association des chaînes au propriétaire de contenu. La valeur du paramètre par défaut 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 pour les dates auxquelles les chaînes ont été associées au propriétaire de contenu.

N'oubliez pas 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. 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 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 l'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 compatible avec 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 JSON-P JavaScript.
prettyPrint

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

  • Renvoie la réponse dans un format lisible si la valeur est 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 ajoute la compatibilité avec 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 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 à l'ordre dans 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 de la table de 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 à 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 aucune ligne pour les 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 obtenir le nombre de 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 en local pour la première fois, vous devez configurer des identifiants d'autorisation pour votre projet :
  1. Créez ou sélectionnez un projet dans la console Google APIs.
  2. Activez l'API YouTube Analytics pour votre projet.
  3. En haut de la page Identifiants, sélectionnez l'onglet Écran de consentement OAuth. Sélectionnez une adresse e-mail, entrez 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 Application Web.
  6. 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 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.

Enregistrez ensuite l'exemple 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:

  1. Ouvrez le fichier local dans 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 Authorize and load (Autoriser et charger) pour lancer le flux d'autorisations utilisateur. Si vous autorisez l'application à récupérer les données de votre canal, 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 avez bien inséré votre ID client dans le code, comme décrit ci-dessus.
  4. Cliquez sur le bouton execute pour appeler l'API. Un objet response devrait 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>

yt_analytics_v2.html

Python

Cet exemple appelle l'API YouTube Analytics pour obtenir le nombre de 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 en local pour la première fois, vous devez configurer des identifiants d'autorisation pour votre projet :
  1. Créez ou sélectionnez un projet dans la console Google APIs.
  2. Activez l'API YouTube Analytics pour votre projet.
  3. En haut de la page Identifiants, sélectionnez l'onglet Écran de consentement OAuth. Sélectionnez une adresse e-mail, entrez 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 de l'API YouTube Analytics", puis cliquez sur le bouton "Créer".
  6. Cliquez sur OK pour fermer la boîte de dialogue qui s'affiche.
  7. Cliquez sur le bouton (Télécharger au format 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, ainsi que certaines 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'échantillon:

  1. Copiez l'exemple de code ci-dessous dans votre répertoire de travail.
  2. Dans l'exemple, modifiez 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 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 votre terminal, puis cliquez sur [retour].
  5. La requête API s'exécute et la réponse JSON est renvoyé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'
  )

yt_analytics_v2.py

Essayer

Utilisez APIs Explorer pour appeler cette API et afficher la requête et la réponse de l'API.