API Core Reporting – Guide de référence

Ce document fournit la documentation de référence complète concernant les requêtes et les réponses pour la version 3.0 de l'API Core Reporting.

Introduction

Vous interrogez l'API Core Reporting pour les données de rapports Google Analytics. Chaque requête nécessite un ID de vue (profil), une date de début et 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 segments, pour affiner votre requête. Consultez le guide de présentation pour comprendre comment tous ces concepts interagissent.

Requête

L'API fournit une méthode unique pour demander des données:

analytics.data.ga.get()

Cette méthode est exposée dans diverses bibliothèques clientes et utilise des interfaces spécifiques à chaque langage pour définir les paramètres de requête.

L'API peut également être interrogée en tant que point de terminaison REST:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

Chaque paramètre de requête d'URL spécifie un paramètre de requête API qui doit être encodé au format URL.

Récapitulatif des paramètres de requête

Le tableau suivant récapitule tous les paramètres de requête acceptés par l'API Core Reporting. Cliquez sur le nom de chaque paramètre pour obtenir une description détaillée.

Nom Valeur Obligatoire Résumé
ids string oui ID de table unique au format ga:XXXX, où XXXX correspond à l'ID de la vue (profil) Analytics pour lequel la requête récupérera les données.
start-date string oui Date de début de la récupération des données Analytics. Les requêtes peuvent spécifier une date de début au format YYYY-MM-DD ou une date relative (par exemple, today, yesterday ou NdaysAgoN est un entier positif).
end-date string oui Date de fin de la récupération des données Analytics. La requête peut spécifier une date de fin au format YYYY-MM-DD ou une date relative (par exemple, today, yesterday ou NdaysAgoN est un entier positif).
metrics string oui Liste de métriques séparées par une virgule, par exemple ga:sessions,ga:bounces.
dimensions string non Une liste de dimensions séparées par une virgule pour vos données Analytics (par exemple, ga:browser,ga:city).
sort string non Liste de dimensions et de métriques séparées par une virgule indiquant l'ordre et le sens de tri des données renvoyées.
filters string non Filtres de dimensions ou de métriques qui limitent les données renvoyées pour votre requête.
segment string non Segmente les données renvoyées pour votre requête.
samplingLevel string non Niveau d'échantillonnage souhaité. Valeurs autorisées :
  • DEFAULT : renvoie la réponse avec une taille d'échantillon qui équilibre la vitesse et la précision.
  • FASTER : renvoie une réponse rapide avec une taille d'échantillon plus petite.
  • HIGHER_PRECISION : renvoie une réponse plus précise avec une taille d'échantillon importante, mais cela peut ralentir la réponse.
include-empty-rows boolean non La valeur par défaut est "true". Si ce paramètre est défini sur "false", les lignes dont toutes les valeurs de métriques sont nulles sont omises de la réponse.
start-index integer non Première ligne de données à récupérer, à partir de 1. Utilisez ce paramètre comme mécanisme de pagination avec le paramètre max-results.
max-results integer non Nombre maximal de lignes à inclure dans la réponse.
output string non Type de sortie souhaité pour les données Analytics renvoyées dans la réponse. Les valeurs acceptables sont json et dataTable. Valeur par défaut : json
fields string non Sélecteur permettant de spécifier un sous-ensemble de champs à inclure dans la réponse.
prettyPrint string non Renvoie une réponse avec des indentations et des sauts de ligne. Valeur par défaut : false.
userIp string non Spécifie l'adresse IP de l'utilisateur final pour le compte duquel l'appel d'API est effectué. Permet de plafonner l'utilisation par adresse IP.
quotaUser string non Alternative à userIp lorsque l'adresse IP de l'utilisateur est inconnue.
access_token string non Un moyen possible de fournir un jeton OAuth 2.0.
callback string non 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.
key string non Utilisé pour l'autorisation OAuth 1.0a afin de spécifier votre application pour obtenir le quota. Exemple : key=AldefliuhSFADSfasdfasdfASdf.

Détails des paramètres de requête

ids

ids=ga:12345
Obligatoire.
Identifiant unique permettant de récupérer les données Analytics. Cet ID correspond à la concaténation de l'espace de noms ga: avec l'ID de la vue (profil) Analytics. Vous pouvez récupérer l'ID de la vue (profil) à l'aide de la méthode analytics.management.profiles.list, qui fournit le id dans la ressource Vue (profil) de l'API de gestion de Google Analytics.

date de début

start-date=2009-04-20
Obligatoire.
Toutes les demandes de données Analytics doivent spécifier une plage de dates. Si vous n'incluez pas les paramètres start-date et end-date dans la requête, le serveur renvoie une erreur. Les valeurs de date peuvent correspondre à une date spécifique en utilisant le format YYYY-MM-DD ou relatives à l'aide de today, yesterday ou NdaysAgo. Les valeurs doivent correspondre à [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
La première valeur de start-date valide est 2005-01-01. Il n'existe pas de limite de limite supérieure pour une date de début.
Les dates relatives sont toujours relatives à la date actuelle au moment de la requête et sont basées sur le fuseau horaire de la vue (profil) spécifiée dans la requête.

Exemple de plage de dates pour les sept derniers jours (à partir d'hier) utilisant des dates relatives:

  &start-date=7daysAgo
  &end-date=yesterday

date de fin

end-date=2009-05-20
Obligatoire.
Toutes les demandes de données Analytics doivent spécifier une plage de dates. Si vous n'incluez pas les paramètres start-date et end-date dans la requête, le serveur renvoie une erreur. Les valeurs de date peuvent correspondre à une date spécifique en utilisant le format YYYY-MM-DD ou relatives à l'aide de today, yesterday ou NdaysAgo. Les valeurs doivent correspondre à [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
La première valeur de end-date valide est 2005-01-01. Il n'existe pas de limite de limite supérieure pour un end-date.
Les dates relatives sont toujours relatives à la date actuelle au moment de la requête et sont basées sur le fuseau horaire de la vue (profil) spécifiée dans la requête.

Exemple de plage de dates pour les 10 derniers jours (à compter d'aujourd'hui) avec des dates relatives:

  &start-date=9daysAgo
  &end-date=today

dimensions

dimensions=ga:browser,ga:city
Facultatif.
Le paramètre dimensions répartit les métriques en fonction de critères communs (par exemple, par ga:browser ou ga:city). Même si vous pouvez demander le nombre total de pages vues sur votre site, il peut être plus intéressant de demander le nombre de pages vues réparties par navigateur. Dans ce cas, vous voyez le nombre de pages vues à partir de Firefox, d'Internet Explorer, de Chrome, etc.

Lorsque vous utilisez dimensions dans une requête de données, tenez compte des contraintes suivantes:

  • Vous pouvez fournir jusqu'à sept dimensions dans une requête.
  • Vous ne pouvez pas envoyer une requête composée uniquement de dimensions: vous devez combiner toutes les dimensions demandées avec au moins une métrique.
  • Seules certaines dimensions peuvent être interrogées dans la même requête. Utilisez l'outil de combinaison valide dans la documentation de référence sur les dimensions et les métriques pour voir quelles dimensions peuvent être utilisées ensemble.


metrics

metrics=ga:sessions,ga:bounces
Obligatoire.
Statistiques cumulées sur l'activité des utilisateurs sur votre site (clics ou pages vues, par exemple). Si une requête ne comporte aucun paramètre dimensions, les métriques renvoyées fournissent des valeurs globales pour la période demandée, telles que le nombre total de pages vues ou le nombre total de rebonds. Toutefois, lorsque des dimensions sont demandées, les valeurs sont segmentées par valeur de dimension. Par exemple, ga:pageviews demandé avec ga:country renvoie le nombre total de pages vues par pays. Lorsque vous demandez des métriques, gardez à l'esprit les points suivants :
  • Toute requête doit fournir au moins une métrique. Une requête ne peut pas comporter uniquement des dimensions.
  • Vous pouvez fournir jusqu'à 10 métriques par requête.
  • La plupart des combinaisons de métriques de plusieurs catégories peuvent être utilisées ensemble, à condition qu'aucune dimension ne soit spécifiée.
  • Vous pouvez combiner une métrique avec d'autres dimensions ou métriques, mais uniquement si des combinaisons valides s'appliquent à cette métrique. Pour en savoir plus, consultez la documentation de référence sur les dimensions et les métriques.


sort

sort=ga:country,ga:browser
Facultatif.

Liste de métriques et de dimensions indiquant l'ordre de tri et le sens de tri des données renvoyées.

  • L'ordre de tri est spécifié par l'ordre de gauche à droite des métriques et dimensions répertoriées.
  • Le direction du tri est défini par défaut dans l'ordre croissant et peut être remplacé par l'ordre décroissant en utilisant un signe moins (-) dans le champ demandé.

Le tri des résultats d'une requête vous permet de poser différentes questions sur vos données. Par exemple, pour répondre à la question "Quels sont mes principaux pays et quels sont les navigateurs qu'ils utilisent le plus ?" vous pouvez créer une requête avec le paramètre suivant. Elle est d'abord triée par ga:country, puis par ga:browser, dans l'ordre croissant:

sort=ga:country,ga:browser

Pour répondre à la question "Quels sont mes principaux navigateurs et quels pays les utilisent le plus ?", vous pouvez créer une requête avec le paramètre suivant. Elle est d'abord triée par ga:browser, puis par ga:country, dans l'ordre croissant :
sort=ga:browser,ga:country

Lorsque vous utilisez le paramètre sort, tenez compte des points suivants:

  • Triez uniquement les données en fonction des valeurs de dimensions ou de métriques que vous avez utilisées dans les paramètres dimensions ou metrics. Si votre requête effectue un tri en fonction d'un champ qui n'est indiqué ni dans les paramètres de dimensions ni de métriques, vous recevrez une erreur.
  • Par défaut, les chaînes sont triées par ordre alphabétique croissant sur les paramètres régionaux en-US.
  • Par défaut, les nombres sont triés par ordre numérique croissant.
  • Par défaut, les dates sont triées par ordre croissant sur la date.

filtres

filters=ga:medium%3D%3Dreferral
Facultatif.

Le paramètre de chaîne de requête filters limite les données renvoyées par votre requête. Pour utiliser le paramètre filters, indiquez une dimension ou une métrique sur laquelle filtrer, suivi de l'expression de filtre. Par exemple, la requête suivante demande ga:pageviews et ga:browser pour la vue (profil) 12134, où la dimension ga:browser commence par la chaîne Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

Les requêtes filtrées limitent les lignes incluses (ou non) dans le résultat. Chaque ligne du résultat est testée par rapport au filtre: si le filtre correspond, la ligne est conservée. Dans le cas contraire, elle est supprimée.

  • Encodage d'URL: les bibliothèques clientes des API Google encodent automatiquement les opérateurs de filtrage.
  • Filtrage des dimensions: le filtrage se produit avant que les dimensions soient agrégées, afin que les métriques renvoyées représentent le total des dimensions pertinentes uniquement. Dans l'exemple ci-dessus, le nombre de pages vues ne correspondrait qu'aux pages vues où le navigateur Firefox est utilisé.
  • Filtrage des métriques: le filtrage des métriques s'effectue après leur agrégation.
  • Combinaisons valides: vous pouvez filtrer en fonction d'une dimension ou d'une métrique qui ne fait pas partie de votre requête, à condition que toutes les dimensions/métriques de la requête et que le filtre soient des combinaisons valides. Par exemple, vous pouvez interroger une liste datée de pages vues en filtrant sur un navigateur particulier. Pour en savoir plus, consultez la documentation de référence sur les dimensions et les métriques.

Syntaxe du filtre


Un filtre unique utilise la forme suivante:

ga:name operator expression

Dans cette syntaxe:

  • name : nom de la dimension ou de la métrique à filtrer. Par exemple: ga:pageviews filtre sur la métrique "Pages vues".
  • operator : définit le type de correspondance de filtre à utiliser. Les opérateurs sont propres aux dimensions ou aux métriques.
  • expression : indique les valeurs à inclure ou à exclure des résultats. Les expressions utilisent une syntaxe d'expression régulière.

Opérateurs de filtrage


Il existe six opérateurs de filtre pour les dimensions et six opérateurs de filtrage pour les métriques. Les opérateurs doivent être encodés au format URL pour pouvoir être inclus dans les chaînes de requête d'URL.

Conseil: Utilisez l'explorateur de requêtes de flux de données pour créer des filtres qui nécessitent d'encoder des URL, car il encode automatiquement les URL contenant des chaînes et des espaces.

Filtres de métriques
Opérateur Description Format d'URL encodé Exemples
== Est égal(e) à %3D%3D Renvoie les résultats où le temps sur la page est exactement de 10 secondes:
filters=ga:timeOnPage%3D%3D10
!= Est différent(e) de !%3D Renvoie les résultats où l'heure sur la page n'est pas de 10 secondes:
filters=ga:timeOnPage!%3D10
> Supérieur à %3E Renvoie les résultats où le temps passé sur la page est strictement supérieur à dix secondes:
filters=ga:timeOnPage%3E10
< Moins de %3C Renvoie les résultats où le temps sur la page est strictement inférieur à 10 secondes:
filters=ga:timeOnPage%3C10
>= Supérieur ou égal à %3E%3D Renvoie les résultats où le temps sur la page est supérieur ou égal à 10 secondes:
filters=ga:timeOnPage%3E%3D10
<= Inférieur ou égal à %3C%3D Renvoie les résultats où le temps sur la page est inférieur ou égal à 10 secondes:
filters=ga:timeOnPage%3C%3D10

Filtres de dimensions
Opérateur Description Format d'URL encodé Exemple
== Correspondance exacte %3D%3D Regroupe les métriques pour lesquelles la ville est Irvine:
filters=ga:city%3D%3DIrvine
!= Ne correspond pas !%3D Regroupe les métriques où la ville n'est pas Irvine:
filters=ga:city!%3DIrvine
=@ Contient une sous-chaîne %3D@ Regroupe les métriques dans lesquelles la ville contient York:
filters=ga:city%3D@York
!@ Ne contient pas de sous-chaîne !@ Regroupe les métriques pour lesquelles la ville ne contient pas York:
filters=ga:city!@York
=~ Contient une correspondance pour l'expression régulière %3D~ Regroupe les métriques où la ville commence par New (Nouveau) :
filters=ga:city%3D~%5ENew.*
(%5E est l'URL encodée à partir du caractère ^ qui ancre un format au début de la chaîne.)
!~ Ne correspond pas à l'expression régulière !~ Regroupe les métriques où la ville ne commence pas par Nouveau:
filters=ga:city!~%5ENew.*

Expressions de filtrage

Voici quelques règles importantes concernant les expressions de filtre:

  • Caractères réservés aux URL : les caractères tels que & doivent être encodés pour les URL comme d'habitude.
  • Caractères réservés:lorsqu'ils apparaissent dans une expression, le point-virgule et la virgule doivent être précédés d'une barre oblique inverse.
    • point-virgule \;
    • virgule \,
  • Expressions régulières : vous pouvez également utiliser des expressions régulières dans des expressions de filtre à l'aide des opérateurs =~ et !~. Leur syntaxe est semblable aux expressions régulières Perl et implique les règles supplémentaires suivantes :
    • Longueur maximale de 128 caractères : les expressions régulières de plus de 128 caractères entraînent le renvoi du code d'état 400 Bad Request par le serveur.
    • Sensibilité à la casse : la correspondance des expressions régulières n'est pas sensible à la casse.

Combiner des filtres

Les filtres peuvent être combinés à l'aide des logiques booléennes OR et AND. Cela vous permet d'étendre efficacement la limite de 128 caractères d'une expression de filtre.

OU

L'opérateur OR est défini à l'aide d'une virgule (,). Il a la priorité sur l'opérateur AND et ne peut PAS être utilisé pour combiner des dimensions et des métriques dans la même expression.

Exemples:(chacune doit être encodée au format URL)

Pays : (États-Unis OU Canada) :
ga:country==United%20States,ga:country==Canada

Utilisateurs de Firefox sur les systèmes d'exploitation (Windows OU Macintosh) :
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

ET

L'opérateur AND est défini à l'aide d'un point-virgule (;). Il est précédé de l'opérateur OR, et peut être utilisé pour combiner des dimensions et des métriques dans la même expression.

Exemples:(chacune doit être encodée au format URL)

Le pays est "États-Unis" ET le navigateur est Firefox:
ga:country==United%20States;ga:browser==Firefox

Le pays correspond aux États-Unis ET la langue ne commence pas par "en":
ga:country==United%20States;ga:language!~^en.*

Le système d'exploitation est (Windows OU Macintosh) ET le navigateur est (Firefox OU Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

Le pays correspond aux États-Unis ET le nombre de sessions est supérieur à 5:
ga:country==United%20States;ga:sessions>5



segmenter

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Facultatif.

Pour en savoir plus sur la façon de demander un segment dans l'API Core Reporting, consultez le Guide du développeur de segments.

Pour obtenir une présentation des concepts liés aux segments, consultez les articles Référence sur les caractéristiques des segments et Segments dans le centre d'aide.

Dimensions et métriques autorisées dans les segments
Toutes les dimensions et métriques ne peuvent pas être utilisées dans les segments. Pour savoir quelles dimensions et métriques sont autorisées dans les segments, accédez à l' Explorateur de dimensions et de métriques.


samplingLevel

samplingLevel=DEFAULT
Facultatif.
Utilisez ce paramètre pour définir le niveau d'échantillonnage (c'est-à-dire le nombre de sessions utilisé pour calculer le résultat) pour une requête de rapport. Les valeurs autorisées sont cohérentes avec l'interface Web et incluent les éléments suivants :
  • DEFAULT : renvoie la réponse avec une taille d'échantillon qui équilibre la vitesse et la précision.
  • FASTER : renvoie une réponse rapide avec une taille d'échantillon plus petite.
  • HIGHER_PRECISION : renvoie une réponse plus précise avec une taille d'échantillon importante, mais cela peut ralentir la réponse.
Si aucun niveau n'est fourni, le niveau d'échantillonnage DEFAULT sera utilisé.
Consultez la section Échantillonnage pour savoir comment calculer le pourcentage de sessions utilisées pour une requête.

inclure-des-lignes-vides

include-empty-rows=true
Facultatif.
Valeur par défaut : "true". Si ce paramètre est défini sur "false", les lignes dont toutes les valeurs de métriques sont nulles sont omises de la réponse. Par exemple, si vous incluez plusieurs métriques dans une requête, les lignes ne sont supprimées que si toutes les valeurs des métriques sont nulles. Cela peut être utile lors d'une requête où le nombre de lignes valides devrait être nettement inférieur au nombre de valeurs de dimension attendues.

start-index

start-index=10
Facultatif.
S'il n'est pas fourni, l'index de départ est 1. (Les index de résultats sont de base 1. Autrement dit, la première ligne est la ligne 1, et non la ligne 0.) Utilisez ce paramètre comme mécanisme de pagination avec le paramètre max-results dans les cas où totalResults dépasse 10 000 et que vous souhaitez récupérer les lignes indexées à 10 001 ou plus.

max-results

max-results=100
Facultatif.
Nombre maximal de lignes à inclure dans cette réponse. Vous pouvez l'utiliser en combinaison avec start-index pour récupérer un sous-ensemble d'éléments, ou l'utiliser seul pour limiter le nombre d'éléments renvoyés, en commençant par le premier. Si max-results n'est pas fourni, la requête renvoie le nombre maximal par défaut de 1 000 lignes.
L'API Core Reporting d'Analytics renvoie un maximum de 10 000 lignes par requête, quel que soit le nombre demandé. Elle peut également renvoyer moins de lignes que demandé, s'il n'y a pas autant de segments de dimension que prévu. Par exemple, il y a moins de 300 valeurs possibles pour ga:country. Par conséquent, lorsque vous segmentez uniquement par pays, vous ne pouvez pas obtenir plus de 300 lignes, même si vous définissez max-results sur une valeur supérieure.

sortie

output=dataTable
Facultatif.
Utilisez ce paramètre pour définir le type de sortie des données Analytics renvoyées dans la réponse. Les valeurs autorisées sont les suivantes :
  • json : renvoie la propriété rows par défaut dans la réponse, contenant un objet JSON.
  • dataTable : génère une propriété dataTable dans la réponse, contenant un objet Data Table. Cet objet Data Table peut être utilisé directement avec les visualisations Google Charts.
Si elle n'est pas fournie, la réponse JSON par défaut sera utilisée.

champs

fields=rows,columnHeaders(name,dataType)
Facultatif.

Spécifie les champs à renvoyer dans une réponse partielle. Si vous n'utilisez qu'un sous-ensemble des champs dans la réponse de l'API, vous pouvez utiliser le paramètre fields pour spécifier les champs à inclure.

Le format de la valeur du paramètre de requête "fields" repose globalement sur la syntaxe XPath. La syntaxe acceptée est résumée ci-dessous.

  • Incluez une liste dont les éléments sont séparés par une virgule pour sélectionner plusieurs champs.
  • Incluez a/b pour sélectionner un champ b imbriqué dans le champ a. Incluez a/b/c pour sélectionner un champ c imbriqué dans le champ b.
  • Utilisez un sous-sélecteur pour demander un ensemble de sous-champs spécifiques de tableaux ou d'objets en plaçant des expressions entre parenthèses : "( )".
    Par exemple: fields=columnHeaders(name,dataType) ne renvoie que les champs name et dataType du tableau columnHeaders. Vous pouvez également spécifier un sous-champ unique, où fields=columnHeader(name) équivaut à fields=columnHeader/name.

prettyPrint

prettyPrint=false
Facultatif.

Renvoie la réponse dans un format lisible si la valeur est true. Valeur par défaut : false.


quotaUser

quotaUser=4kh4r2h4
Facultatif.

Vous permet d' appliquer des quotas par utilisateur à partir d'une application côté serveur, même lorsque l'adresse IP de l'utilisateur est inconnue. Cela peut se produire, par exemple, avec les applications qui exécutent des tâches Cron sur App Engine pour le compte d'un utilisateur. Vous pouvez choisir n'importe quelle chaîne arbitraire permettant d'identifier un utilisateur de manière unique, mais elle est limitée à 40 caractères.

Cette valeur remplace userIp si les deux sont fournis.


Réponse

Si la requête aboutit, cette requête renvoie un corps de réponse avec la structure JSON définie ci-dessous. Si le paramètre output est défini sur dataTable, la requête renvoie un corps de réponse avec la structure JSON (Table de données) définie ci-dessous.

Remarque: Le terme "résultats" fait référence à l'ensemble des lignes correspondant à la requête, tandis que le terme "réponse" fait référence à l'ensemble de lignes renvoyées sur la page de résultats actuelle. Ils peuvent être différents si le nombre total de résultats est supérieur à la taille de page de la réponse actuelle, comme expliqué dans itemsPerPage.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Champs de réponse

Les propriétés de la structure du corps de la réponse sont définies comme suit:

Nom de propriété Valeur Description
kind string Type de ressource. La valeur est "analytics#gaData".
id string ID de cette réponse de données.
query object Cet objet contient toutes les valeurs transmises en tant que paramètres à la requête. La signification de chaque champ est expliquée dans la description du paramètre de requête correspondant.
query.start-date string Date de début.
query.end-date string Date de fin.
query.ids string ID de table unique.
query.dimensions[] list Liste des dimensions Analytics.
query.metrics[] list Liste des métriques d'analyse.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean La valeur par défaut est "true". Si ce paramètre est défini sur "false", les lignes dont toutes les valeurs de métriques sont égales à zéro seront omises de la réponse.
query.sort[] list Liste des métriques ou dimensions selon lesquelles les données sont triées.
query.filters string Liste de filtres de métriques ou de dimensions séparés par une virgule.
query.segment string Segment Analytics.
query.start-index integer Index de début.
query.max-results integer Nombre maximal de résultats par page.
startIndex integer Index de départ des lignes spécifiées par le paramètre de requête start-index. La valeur par défaut est 1.
itemsPerPage integer Nombre maximal de lignes que la réponse peut contenir, quel que soit le nombre réel de lignes renvoyées. Si le paramètre de requête max-results est spécifié, la valeur de itemsPerPage correspond à max-results ou à 10 000,selon la plus petite des deux. La valeur par défaut de itemsPerPage est 1 000.
totalResults integer Nombre total de lignes dans le résultat de la requête, quel que soit le nombre de lignes renvoyées dans la réponse. Pour les requêtes qui génèrent un grand nombre de lignes, la valeur totalResults peut être supérieure à itemsPerPage. Pour en savoir plus sur totalResults et itemsPerPage pour les requêtes volumineuses, consultez la section Paging.
startDate string Date de début de la requête de données, comme spécifié par le paramètre start-date.
endDate string Date de fin de la requête de données, comme spécifié par le paramètre end-date.
profileInfo object Informations sur la vue (profil) pour laquelle les données ont été demandées. Les données des vues (profils) sont disponibles via l'API de gestion Google Analytics.
profileInfo.profileId string ID de la vue (profil), tel que 1174.
profileInfo.accountId string ID du compte auquel appartient cette vue (profil), par exemple 30481.
profileInfo.webPropertyId string ID de propriété Web à laquelle appartient cette vue (profil), par exemple UA-30481-1.
profileInfo.internalWebPropertyId string ID interne du site Web auquel appartient cette vue (profil), tel que UA-30481-1.
profileInfo.profileName string Nom de la vue (profil).
profileInfo.tableId string ID de table pour la vue (profil), composé de "ga:" suivi de l'ID de la vue (profil).
containsSampledData boolean "True" si la réponse contient des données échantillonnées.
sampleSize string Nombre d'échantillons utilisés pour calculer les données échantillonnées.
sampleSpace string Taille totale de l'espace d'échantillonnage. Indique la taille totale de l'espace d'échantillon disponible dans lequel les échantillons ont été sélectionnés.
columnHeaders[] list En-têtes de colonne répertoriant les noms de dimension suivis des noms de métriques. L'ordre des dimensions et des métriques est le même que celui spécifié dans la requête via les paramètres metrics et dimensions. Le nombre d'en-têtes correspond au nombre de dimensions + le nombre de métriques.
columnHeaders[].name string Nom de la dimension ou de la métrique.
columnHeaders[].columnType string Type de colonne "DIMENSION" ou "METRIC".
columnHeaders[].dataType string Type de données Les en-têtes de colonnes de dimension ne possèdent que le type de données STRING. Les en-têtes des colonnes de métriques possèdent des types de données pour les valeurs de métriques telles que INTEGER, PERCENT, TIME, CURRENCY, FLOAT, etc. Consultez la réponse de l'API de métadonnées pour tous les types de données possibles.
totalsForAllResults object Valeurs totales des métriques demandées sous forme de paires clé/valeur de noms et de valeurs de métriques. L'ordre des totaux des métriques est le même que celui spécifié dans la requête.
rows[] list Lignes de données Analytics, chaque ligne contenant une liste de valeurs de dimension suivies des valeurs des métriques. L'ordre des dimensions et des métriques est le même que celui spécifié dans la requête. Chaque ligne comporte une liste de N champs, où N = le nombre de dimensions + le nombre de métriques.
JSON (table de données)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

Champs de réponse

Les propriétés de la structure du corps de la réponse sont définies comme suit:

Nom de propriété Valeur Description
kind string Type de ressource. La valeur est "analytics#gaData".
id string ID de cette réponse de données.
query object Cet objet contient toutes les valeurs transmises en tant que paramètres à la requête. La signification de chaque champ est expliquée dans la description du paramètre de requête correspondant.
query.start-date string Date de début.
query.end-date string Date de fin.
query.ids string ID de table unique.
query.dimensions[] list Liste des dimensions Analytics.
query.metrics[] list Liste des métriques d'analyse.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean La valeur par défaut est "true". Si ce paramètre est défini sur "false", les lignes dont toutes les valeurs de métriques sont égales à zéro seront omises de la réponse.
query.sort[] list Liste des métriques ou dimensions selon lesquelles les données sont triées.
query.filters string Liste de filtres de métriques ou de dimensions séparés par une virgule.
query.segment string Segment Analytics.
query.start-index integer Index de début.
query.max-results integer Nombre maximal de résultats par page.
startIndex integer Index de départ des lignes spécifiées par le paramètre de requête start-index. La valeur par défaut est 1.
itemsPerPage integer Nombre maximal de lignes que la réponse peut contenir, quel que soit le nombre réel de lignes renvoyées. Si le paramètre de requête max-results est spécifié, la valeur de itemsPerPage correspond à max-results ou à 10 000,selon la plus petite des deux. La valeur par défaut de itemsPerPage est 1 000.
totalResults integer Nombre total de lignes dans le résultat de la requête, quel que soit le nombre de lignes renvoyées dans la réponse. Pour les requêtes qui génèrent un grand nombre de lignes, la valeur totalResults peut être supérieure à itemsPerPage. Pour en savoir plus sur totalResults et itemsPerPage pour les requêtes volumineuses, consultez la section Paging.
startDate string Date de début de la requête de données, comme spécifié par le paramètre start-date.
endDate string Date de fin de la requête de données, comme spécifié par le paramètre end-date.
profileInfo object Informations sur la vue (profil) pour laquelle les données ont été demandées. Les données des vues (profils) sont disponibles via l'API de gestion Google Analytics.
profileInfo.profileId string ID de la vue (profil), tel que 1174.
profileInfo.accountId string ID du compte auquel appartient cette vue (profil), par exemple 30481.
profileInfo.webPropertyId string ID de propriété Web à laquelle appartient cette vue (profil), par exemple UA-30481-1.
profileInfo.internalWebPropertyId string ID interne du site Web auquel appartient cette vue (profil), tel que UA-30481-1.
profileInfo.profileName string Nom de la vue (profil).
profileInfo.tableId string ID de table pour la vue (profil), composé de "ga:" suivi de l'ID de la vue (profil).
containsSampledData boolean "True" si la réponse contient des données échantillonnées.
sampleSize string Nombre d'échantillons utilisés pour calculer les données échantillonnées.
sampleSpace string Taille totale de l'espace d'échantillonnage. Indique la taille totale de l'espace d'échantillon disponible dans lequel les échantillons ont été sélectionnés.
columnHeaders[] list En-têtes de colonne répertoriant les noms de dimension suivis des noms de métriques. L'ordre des dimensions et des métriques est le même que celui spécifié dans la requête via les paramètres metrics et dimensions. Le nombre d'en-têtes correspond au nombre de dimensions + le nombre de métriques.
columnHeaders[].name string Nom de la dimension ou de la métrique.
columnHeaders[].columnType string Type de colonne "DIMENSION" ou "METRIC".
columnHeaders[].dataType string Type de données Les en-têtes de colonnes de dimension ne possèdent que le type de données STRING. Les en-têtes des colonnes de métriques possèdent des types de données pour les valeurs de métriques telles que INTEGER, PERCENT, TIME, CURRENCY, FLOAT, etc. Consultez la réponse de l'API de métadonnées pour tous les types de données possibles.
totalsForAllResults object Valeurs totales des métriques demandées sous forme de paires clé/valeur de noms et de valeurs de métriques. L'ordre des totaux des métriques est le même que celui spécifié dans la requête.
dataTable object Un objet Table de données pouvant être utilisé avec des graphiques Google
dataTable.cols[] list Une liste de descripteurs de colonne pour les dimensions suivies de métriques. L'ordre des dimensions et des métriques est le même que celui spécifié dans la requête via les paramètres metrics et dimensions. Le nombre de colonnes correspond au nombre de dimensions + le nombre de métriques.
dataTable.cols[].id string Un ID permettant de faire référence à une colonne spécifique (au lieu d'utiliser des index de colonne). L'ID de dimension ou de métrique est utilisé pour définir cette valeur.
dataTable.cols[].label string Étiquette de la colonne (qui peut être affichée par une visualisation). L'ID de dimension ou de métrique est utilisé pour définir cette valeur.
dataTable.cols[].type string Type de données de cette colonne.
dataTable.rows[] list Lignes de données Analytics au format Tableau de données, où chaque ligne est un objet contenant une liste de valeurs de cellules pour les dimensions suivies de métriques. L'ordre des dimensions et des métriques est le même que celui spécifié dans la requête. Chaque cellule comporte une liste de N champs, où N = le nombre de dimensions + le nombre de métriques.

Codes d'erreur

L'API Core Reporting renvoie un code d'état HTTP 200 si une requête aboutit. Si une erreur se produit lors du traitement d'une requête, l'API affiche un code d'erreur et une description. Chaque application qui utilise l'API d'analyse doit mettre en œuvre une logique de gestion des erreurs appropriée. Pour en savoir plus sur les codes d'erreur et sur leur gestion, consultez le guide de référence sur les réponses d'erreur.

Essayer

Vous pouvez tester les requêtes adressées à l'API Core Reporting.

  • Pour afficher les combinaisons valides de métriques et de dimensions dans une requête, saisissez des exemples de valeurs pour les paramètres dans l'explorateur de requêtes. Les résultats de l'exemple de requête sont affichés sous forme de tableau avec les valeurs de toutes les métriques et dimensions spécifiées.

  • Pour effectuer une requête sur des données actives et afficher la réponse au format JSON, essayez la méthode analytics.data.ga.get dans l'explorateur des API Google Data.

Sampling

Google Analytics calcule certaines combinaisons de dimensions et de métriques à la volée. Pour renvoyer les données dans un délai raisonnable, Google Analytics ne peut traiter qu'un échantillon.

Vous pouvez spécifier le niveau d'échantillonnage à utiliser pour une requête en définissant le paramètre samplingLevel.

Si une réponse de l'API Core Reporting contient des données échantillonnées, le champ de réponse containsSampledData sera true. En outre, deux propriétés fournissent des informations sur le niveau d'échantillonnage de la requête: sampleSize et sampleSpace. Ces deux valeurs vous permettent de calculer le pourcentage de sessions utilisées pour la requête. Par exemple, si sampleSize correspond à 201,000 et que sampleSpace est 220,000,le rapport est basé sur (201 000 / 220 000) * 100 = 91,36% des sessions.

Consultez la section Échantillonnage pour obtenir une description générale de l'échantillonnage et de son utilisation dans Google Analytics.


Gérer les résultats associés à un volume de données volumineux

Si vous vous attendez à ce que votre requête renvoie un ensemble de résultats volumineux, suivez les instructions ci-dessous pour optimiser votre requête API, éviter les erreurs et minimiser les dépassements de quota. Notez que nous définissons les performances de référence en autorisant jusqu'à 7 dimensions et 10 métriques dans une même requête API. Bien que le traitement de certaines requêtes spécifiant un grand nombre de métriques et de dimensions puisse prendre plus de temps que d'autres, limiter le nombre de métriques demandées peut ne pas suffire à améliorer les performances des requêtes. Utilisez plutôt les techniques suivantes pour optimiser les performances.

Réduire le nombre de dimensions par requête

L'API permet de spécifier jusqu'à sept dimensions dans une requête. Bien souvent, Google Analytics doit calculer les résultats de ces requêtes complexes à la volée. Cela peut s'avérer particulièrement long si le nombre de lignes obtenues est élevé. Par exemple, l'interrogation de mots clés par ville et par heure peut correspondre à des millions de lignes de données. Vous pouvez améliorer les performances en réduisant le nombre de lignes que Google Analytics doit traiter, en limitant le nombre de dimensions dans votre requête.

Division de la requête par plage de dates

Au lieu de paginer les résultats associés à la date d'une longue période, envisagez de former des requêtes distinctes pour une semaine, voire un jour, à la fois. Bien entendu, pour un ensemble de données volumineux, même une requête portant sur les données d'une seule journée peut renvoyer plus de max-results, auquel cas la pagination ne peut pas être évitée. Toutefois, dans tous les cas, si le nombre de lignes correspondantes pour votre requête est supérieur à max-results, le fait de séparer la plage de dates peut réduire le temps total de récupération des résultats. Cette approche peut améliorer les performances pour les requêtes à thread unique et parallèles.

Paging

Parcourir les résultats peut être un moyen utile de diviser de grands ensembles de résultats en fragments gérables. Le champ totalResults indique le nombre de lignes correspondantes, et itemsPerPage indique le nombre maximal de lignes pouvant être renvoyées dans le résultat. Si le ratio totalResults/itemsPerPage est élevé, les requêtes individuelles peuvent prendre plus de temps que nécessaire. Si vous n'avez besoin que d'un nombre limité de lignes, par exemple à des fins d'affichage, il peut être pratique de définir une limite explicite de taille de réponse via le paramètre max-results. Toutefois, si votre application doit traiter un grand nombre de résultats dans son intégralité, il peut être plus efficace de demander le nombre maximal de lignes autorisées.

Utiliser gzip

La compression gzip est un moyen pratique et facile de réduire la bande passante requise pour chaque requête. Bien que la décompression des résultats nécessite un temps CPU supplémentaire, la compression est généralement très avantageuse en termes de coûts de réseau. Pour recevoir une réponse encodée au format gzip, vous devez effectuer deux opérations: définir un en-tête Accept-Encoding et modifier votre user-agent afin d'y inclure la chaîne gzip. Voici un exemple d'en-têtes HTTP correctement mis en forme pour l'activation de la compression gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)