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.
Présentation
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 :
|
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
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
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)
.
start-date
valide le plus ancien est 2005-01-01
.
Il n'existe pas de limite supérieure pour une date de début.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
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)
.
end-date
valide le plus ancien est 2005-01-01
. Il n'existe pas de limite supérieure pour une propriété end-date
. 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
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
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
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
oumetrics
. 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
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.
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 |
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
\,
- point-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.
- Longueur maximale de 128 caractères : les expressions régulières de plus de 128 caractères génèrent un code d'état
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
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
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.
DEFAULT
sera utilisé.inclure-les-lignes-vides
include-empty-rows=true
start-index
start-index=10
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
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.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
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 objetData Table
peut être utilisé directement avec les visualisations Google Charts.
champs
fields=rows,columnHeaders(name,dataType)
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. Utiliseza/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 champsname
etdataType
du tableaucolumnHeaders
. Vous pouvez également spécifier un sous-champ unique, oùfields=columnHeader(name)
équivaut àfields=columnHeader/name
.
prettyPrint
prettyPrint=false
Renvoie la réponse dans un format lisible si la valeur est true
.
Valeur par défaut : false
.
quotaUser
quotaUser=4kh4r2h4
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.
{
"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é 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 . |
selfLink |
string |
Lien vers cette page de résultats pour cette requête de données. |
previousLink |
string |
Lien vers la page de résultats précédente pour cette requête de données. |
nextLink |
string |
Lien vers la page de résultats suivante pour cette requête de données. |
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. |
{
"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 . |
selfLink |
string |
Lien vers cette page de résultats pour cette requête de données. |
previousLink |
string |
Lien vers la page de résultats précédente pour cette requête de données. |
nextLink |
string |
Lien vers la page de résultats suivante pour cette requête de données. |
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)