API Core Reporting – Guide de référence

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

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 dispose d'interfaces propres à chaque langage pour définir les paramètres de requête.

Vous pouvez également interroger l'API 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 principale de création de rapports. 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 laquelle 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 NdaysAgo où N 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 NdaysAgo où N 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 no Liste de dimensions séparées par une virgule pour vos données Analytics (par exemple, ga:browser,ga:city).
sort string no 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 no Filtres de dimensions ou de métriques qui limitent les données renvoyées pour votre requête.
segment string no Segmente les données renvoyées pour votre requête.
samplingLevel string no 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 en utilisant une taille d'échantillon importante, mais cela peut ralentir la réponse.
include-empty-rows boolean no La valeur par défaut est "true". Si cette valeur est définie sur "false", les lignes dans lesquelles toutes les valeurs de métriques sont égales à zéro sont omises de la réponse.
start-index integer no 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 no Nombre maximal de lignes à inclure dans la réponse.
output string no 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 no Sélecteur permettant de spécifier un sous-ensemble de champs à inclure dans la réponse.
prettyPrint string no Renvoie une réponse avec des indentations et des sauts de ligne. Valeur par défaut : false.
userIp string no Spécifie l'adresse IP de l'utilisateur final pour le compte duquel l'appel d'API est effectué. Utilisé pour plafonner l'utilisation par adresse IP.
quotaUser string no Alternative à l'adresse userIp lorsque l'adresse IP de l'utilisateur est inconnue.
access_token string no Un moyen possible de fournir un jeton OAuth 2.0.
callback string no 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 no Utilisé pour l'autorisation OAuth 1.0a afin de spécifier votre application pour obtenir un 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 à des valeurs 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).
Le start-date valide le plus ancien est 2005-01-01. Il n'existe pas 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 à des valeurs 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).
Le end-date valide le plus ancien est 2005-01-01. Il n'existe pas de limite supérieure pour une propriété 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) en utilisant 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, 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 par navigateur. Dans ce cas, vous verrez le nombre de pages vues dans Firefox, Internet Explorer, Chrome, etc.

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

  • Vous pouvez fournir jusqu'à sept dimensions par 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 un outil de combinaison valide dans la documentation de référence sur les dimensions et les métriques pour savoir 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, telles que les clics ou les pages vues. Si une requête ne comporte pas de paramètre dimensions, les métriques renvoyées fournissent des valeurs agrégées pour la plage de dates 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, tenez compte des 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 à 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 de tri est défini par défaut dans l'ordre croissant et peut être modifié pour passer à l'ordre décroissant en utilisant le préfixe du 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 effectuer une requête avec le paramètre suivant. Il effectue un tri d'abord par ga:country, puis par ga:browser, les deux dans l'ordre croissant:

sort=ga:country,ga:browser

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

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

  • Triez uniquement les 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 dimensions, ni dans les paramètres de métriques, vous obtenez une erreur.
  • Par défaut, les chaînes sont triées par ordre alphabétique croissant pour 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 dans l'ordre croissant par date.

filtres

filters=ga:medium%3D%3Dreferral
  1. Syntaxe du filtre
  2. Opérateurs de filtrage
  3. Expressions de filtre
  4. Combiner des filtres
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 à filtrer, suivie 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 qui sont incluses (ou non) dans le résultat. Chaque ligne de résultat est testée par rapport au filtre: si le filtre correspond, la ligne est conservée. Si ce n'est pas le cas, elle est supprimée.

  • Encodage d'URL: les bibliothèques clientes de l'API Google encodent automatiquement les opérateurs de filtrage.
  • Filtrage des dimensions: le filtrage se produit avant le regroupement de toute dimension, afin que les métriques renvoyées représentent le total des dimensions pertinentes. Dans l'exemple ci-dessus, le nombre de pages vues ne correspond qu'aux pages vues où le navigateur Firefox est utilisé.
  • Filtrage des métriques: le filtrage des métriques a lieu après l'agrégation de celles-ci.
  • Combinaisons valides: vous pouvez appliquer un filtre 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 le filtre soient des combinaisons valides. Par exemple, vous pouvez lancer une requête sur 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 à utiliser pour le filtrage. Par exemple, ga:pageviews filtre 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 filtrage pour les dimensions et six opérateurs de filtrage pour les métriques. Les opérateurs doivent être encodés au format URL pour ê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 nécessitant un encodage d'URL, car l'explorateur de requêtes 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 Affiche les résultats où le temps passé sur la page est exactement de 10 secondes:
filters=ga:timeOnPage%3D%3D10
!= Est différent(e) de !%3D Renvoie les résultats où le temps passé sur la page n'est pas de 10 secondes:
filters=ga:timeOnPage!%3D10
> Supérieur à %3E Affiche les résultats pour lesquels le temps passé sur la page est strictement supérieur à 10 secondes:
filters=ga:timeOnPage%3E10
< Moins de %3C Affiche les résultats dans lesquels le temps passé sur la page est strictement inférieur à 10 secondes:
filters=ga:timeOnPage%3C10
>= Supérieur ou égal à %3E%3D Affiche les résultats pour lesquels le temps passé sur la page est de 10 secondes ou plus:
filters=ga:timeOnPage%3E%3D10
<= Inférieur ou égal à %3C%3D Afficher les résultats où le temps passé sur la page est inférieur ou égal à dix secondes:
filters=ga:timeOnPage%3C%3D10

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

Expressions de filtre

Il existe deux 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 à celle des expressions régulières Perl et comporte les règles supplémentaires suivantes :
    • Longueur maximale de 128 caractères : les expressions régulières de plus de 128 caractères génèrent un code d'état 400 Bad Request renvoyé 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 une 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 la France ET le navigateur est Firefox:
ga:country==United%20States;ga:browser==Firefox

Le pays est défini sur "É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 de développement des segments.

Pour obtenir une présentation des concepts liés aux segments, consultez la documentation de référence sur les caractéristiques des segments et la section 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ées pour calculer le résultat) d'une requête de rapport. Les valeurs autorisées sont cohérentes avec l'interface Web et incluent :
  • 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 en utilisant une taille d'échantillon importante, mais cela peut ralentir la réponse.
Si vous ne renseignez pas ce champ, 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-les-lignes-vides

include-empty-rows=true
Facultatif.
La valeur par défaut est "true". Si cette valeur est définie sur "false", les lignes dont toutes les valeurs de métriques sont égales à zéro 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 de métriques sont égales à zéro. Cela peut être utile lorsque vous effectuez une requête pour laquelle le nombre de lignes valides est bien 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 lorsque totalResults dépasse 10 000 et que vous souhaitez récupérer les lignes indexées à 10 001 et au-delà.

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 maximum 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é. Il 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 existe 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, qui contient 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 vous n'en fournissez pas, 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 des champs 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.
  • Utilisez a/b pour sélectionner un champ b imbriqué dans le champ a. Utilisez a/b/c pour sélectionner un champ c imbriqué dans le champ b.
  • Incluez 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 des 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 ne doit pas dépasser 40 caractères.

Cette valeur remplace userIp si les deux sont fournis.

Réponse

Si la requête aboutit, la 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" désigne l'ensemble des lignes correspondant à la requête, tandis que le terme "réponse" désigne 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 la 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 la 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 cette valeur est définie sur "false", les lignes dans lesquelles toutes les valeurs de métriques sont égales à zéro sont 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épart.
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 valeur la plus faible. 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 sur les vues (profils) sont disponibles via l'API Google Analytics Management.
profileInfo.profileId string ID de la vue (de 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 à laquelle 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'échantillonnage disponible à partir duquel les échantillons ont été sélectionnés.
columnHeaders[] list En-têtes de colonne répertoriant les noms des dimensions suivis des noms des 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 de colonnes de métriques comportent 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 Metadata 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 indiqué 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 la 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 cette valeur est définie sur "false", les lignes dans lesquelles toutes les valeurs de métriques sont égales à zéro sont 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épart.
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 valeur la plus faible. 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 sur les vues (profils) sont disponibles via l'API Google Analytics Management.
profileInfo.profileId string ID de la vue (de 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 à laquelle 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'échantillonnage disponible à partir duquel les échantillons ont été sélectionnés.
columnHeaders[] list En-têtes de colonne répertoriant les noms des dimensions suivis des noms des 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 de colonnes de métriques comportent 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 Metadata 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 qui peut être utilisé avec des graphiques Google
dataTable.cols[] list 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 indiqué 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 renvoie 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 la manière de les gérer, consultez le Guide de référence sur les réponses d'erreur.

Essayer

Vous pouvez tester des 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 des valeurs pour toutes les métriques et dimensions spécifiées.

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

Échantillonnage

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 sampleSpace à 220,000,le rapport est basé sur (201 000 / 220 000) x 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 des résultats de grands volumes de données

Si vous pensez que votre requête renverra 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 des performances de référence en autorisant au maximum 7 dimensions et 10 métriques par requête API. Bien que certaines requêtes spécifiant un grand nombre de métriques et de dimensions puissent prendre plus de temps que d'autres, limiter le nombre de métriques demandées ne sera peut-être pas suffisant pour améliorer les performances des requêtes. À la place, vous pouvez utiliser les techniques suivantes pour optimiser les performances.

Réduire les dimensions par requête

L'API permet de spécifier jusqu'à sept dimensions dans une requête. Souvent, Google Analytics doit calculer les résultats de ces requêtes complexes à la volée. Cela peut prendre beaucoup de temps si le nombre de lignes résultantes est élevé. Par exemple, une requête 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

Plutôt que de parcourir les résultats associés à une date spécifique sur 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. Dans ce 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 décomposer la plage de dates peut réduire le temps total nécessaire à la récupération des résultats. Cette approche peut améliorer les performances des requêtes à thread unique et parallèles.

Paging

Il peut être utile de parcourir les résultats pour 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 entre totalResults et 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 utile 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 du 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 pour 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)