Ce guide pour les développeurs utilise la version 4 de l'API Analytics Reporting. Pour en savoir plus sur l'API, consultez la documentation de référence de l'API.
Rapports
L'API Analytics Reporting v4 fournit la méthode batchGet pour accéder à la ressource Reports.
Les sections suivantes décrivent la structure du corps de la requête pour batchGet et celle du corps de la réponse de batchGet.
Corps de la requête
Pour utiliser l'API Analytics Reporting v4 pour demander des données, vous devez créer un objet ReportRequest, qui comporte les conditions minimales suivantes:
- Un ID de vue valide pour le champ viewId
- Au moins une entrée valide dans le champ dateRanges.
- Au moins une entrée valide dans le champ Métriques
Pour trouver un ID de vue, interrogez la méthode Récapitulatifs de compte ou utilisez l'explorateur de compte.
Si aucune plage de dates n'est spécifiée, la plage de dates par défaut est : {"startDate": "7daysAgo", "endDate": "yesterday"}.
Voici un exemple de requête avec les champs obligatoires:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
La méthode batchGet accepte un maximum de cinq objets ReportRequest. Toutes les requêtes doivent avoir les mêmes dateRange, viewId, segments, samplingLevel et cohortGroup.
Corps de la réponse
Le corps de la réponse de la requête API est un tableau d'objets Report. La structure du rapport est définie dans l'objet ColumnHeader, qui décrit les dimensions, les métriques et leurs types de données dans le rapport. Les valeurs des dimensions et des métriques sont spécifiées dans le champ data.
Voici un exemple de réponse pour l'exemple de requête ci-dessus:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
Métriques
Les métriques sont des mesures quantitatives. Chaque requête nécessite au moins un objet Metric.
Dans l'exemple suivant, la métrique Sessions est fournie à la méthode batchGet pour obtenir le nombre total de sessions dans la plage de dates spécifiée:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Vous pouvez utiliser l'explorateur de dimensions et de métriques ou l'API Metadata pour obtenir la liste des dimensions et métriques disponibles.
Filtrage
Lorsque vous envoyez une requête batchGet, vous pouvez lui demander de ne renvoyer que des métriques répondant à des critères spécifiques. Pour filtrer les métriques, spécifiez une ou plusieurs MetricFilterClauses dans le corps de la requête, puis définissez une ou plusieurs MetricFilters dans chaque MetricFilterClause.
Dans chaque MetricFilter, spécifiez les valeurs suivantes:
metricNamenotoperatorcomparisonValue
Laissez {metricName} représenter la métrique, {operator} le operator et {comparisonValue} le comparisonValue. Le filtre fonctionne ensuite comme suit:
if {metricName} {operator} {comparisonValue}
return the metric
Si vous spécifiez true pour not, le filtre fonctionne comme suit:
if {metricName} {operator} {comparisonValue}
do not return the metric
Dans l'exemple suivant, batchGet ne renvoie que les pages vues dont la valeur est supérieure à 2:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
Expressions
Une expression de métrique est une expression mathématique que vous définissez sur des métriques existantes. Elle fonctionne comme des métriques calculées dynamiques. Vous pouvez définir un alias pour représenter l'expression de métrique, par exemple:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
commandes
Pour trier les résultats en fonction d'une valeur de métrique:
- Indiquez son nom ou son alias dans le champ
fieldName. - Spécifiez l'ordre de tri (
ASCENDINGouDESCENDING) dans le champsortOrder.
Dans l'exemple suivant, batchGet renvoie les métriques triées d'abord par sessions, puis par pages vues par ordre décroissant:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
Dimensions
Les dimensions représentent les caractéristiques de vos utilisateurs, ainsi que de leurs sessions et actions.
La dimension "Ville", par exemple, décrit une caractéristique des sessions et
indique la ville (par exemple ; Paris ou New York) d'où provient chaque session.
Dans une requête batchGet, vous pouvez spécifier zéro ou plusieurs objets de dimension, par exemple:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
Filtrage
Lorsque vous envoyez une requête batchGet, vous pouvez lui demander de ne renvoyer que des dimensions qui répondent à des critères spécifiques. Pour filtrer les dimensions, spécifiez un ou plusieurs DimensionsFilterClauses dans le corps de la requête, puis définissez un ou plusieurs DimensionsFilters dans chaque DimensionsFilterClause.
Dans chaque DimensionsFilters, spécifiez les valeurs suivantes:
dimensionNamenotoperatorexpressionscaseSensitive
Laissez {dimensionName} représenter la dimension, {operator} le operator et {expressions} le expressions. Le filtre fonctionne ensuite comme suit:
if {dimensionName} {operator} {expressions}
return the dimension
Si vous spécifiez true pour not, le filtre fonctionne comme suit:
if {dimensionName} {operator} {expressions}
do not return the dimension
Dans l'exemple suivant, batchGet renvoie les pages vues et les sessions dans un navigateur Chrome:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
commandes
Pour trier les résultats par valeur de dimension:
- Indiquez son nom dans le champ
fieldName. - Spécifiez l'ordre de tri (
ASCENDINGouDESCENDING) dans le champsortOrder.
Par exemple, l'élément batchGet suivant renvoie les dimensions triées par pays, puis par navigateur:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
Buckets d'histogrammes
Pour les dimensions avec des valeurs entières, il est plus facile de comprendre leurs caractéristiques en segmentant leurs valeurs en plages. Utilisez le champ histogramBuckets pour définir les plages des buckets correspondants et spécifier HISTOGRAM_BUCKET comme type de commande, par exemple:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
Plusieurs plages de dates
L'API Google Analytics Reporting v4 vous permet d'obtenir des données sur plusieurs plages de dates dans une seule requête. Si votre requête spécifie une ou deux plages de dates, les données sont renvoyées dans l'objet dateRangeValue, par exemple:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
Ordre delta
Lorsque vous demandez des valeurs de métrique dans deux plages de dates, vous pouvez trier les résultats en fonction de la différence entre les valeurs de la métrique dans les plages de dates. Exemple:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
Comportement de la dimension "Date"
Si vous demandez une dimension liée à la date ou l'heure, l'objet DateRangeValue ne contient que les valeurs correspondant aux dates comprises dans les plages respectives. Toutes les autres valeurs situées en dehors des plages de dates spécifiées sont définies sur 0.
Par exemple, considérons une requête pour la dimension ga:date et la métrique ga:sessions sur deux plages de dates: janvier et février.
Dans la réponse pour les données demandées en janvier, les valeurs en février seront 0. Dans la réponse pour les données demandées en février, les valeurs en janvier seront 0.
Rapport de janvier
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Rapport de février
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Segments
Pour demander un sous-ensemble de vos données Analytics, utilisez les segments. Par exemple, vous pouvez définir les utilisateurs d'un pays ou d'une ville spécifique dans un segment, et ceux qui visitent une partie spécifique de votre site dans un autre. Les filtres ne renvoient que les lignes qui répondent à une condition, tandis que les segments renvoient un sous-ensemble d'utilisateurs, de sessions ou d'événements remplissant les conditions contenant les segments.
Lorsque vous effectuez une requête avec des segments, vérifiez les points suivants:
- Chaque ReportRequest d'une méthode
batchGetdoit contenir des définitions de segment identiques. - Ajoutez
ga:segmentà la liste des dimensions.
Exemple :
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
Pour voir d'autres exemples de requêtes avec des segments, consultez la section Exemples.
ID du segment
Utilisez le champ segmentId pour demander des segments.
Vous ne pouvez pas utiliser à la fois un segmentId et un dynamicSegment pour demander des segments.
Exemple :
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
Échantillonnage
L'échantillonnage peut avoir une incidence sur les résultats de vos données. C'est une raison courante pour laquelle les valeurs renvoyées par l'API ne correspondent pas à l'interface Web. Utilisez le champ samplingLevel pour définir la taille d'échantillon souhaitée.
- Définissez la valeur sur
SMALLpour obtenir une réponse rapide avec une taille d'échantillonnage plus petite. - Définissez la valeur sur
LARGEpour une réponse plus précise, mais plus lente. - définissez la valeur sur
DEFAULTpour une réponse qui équilibre la vitesse et la justesse.
Exemple :
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
Si un rapport contient des données échantillonnées, la version 4 de l'API Analytics Reporting renvoie les champs samplesReadCounts et samplingSpaceSizes.
Si les résultats ne sont pas échantillonnés, ces champs ne seront pas définis.
Vous trouverez ci-dessous un exemple de réponse contenant des données échantillonnées à partir d'une requête comportant deux plages de dates. Les résultats ont été calculés à partir de près de 500 000 échantillons d'une taille d'espace d'échantillonnage d'environ 15 millions de sessions:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Pagination
L'API Analytics v4 utilise les champs pageToken et pageSize pour paginer les résultats de réponse qui s'étendent sur plusieurs pages. Vous obtenez pageToken du paramètre nextPageToken dans la réponse à la requête reports.batchGet:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Étape suivante
Maintenant que vous avez vu les bases de la création d'un rapport, découvrez les fonctionnalités avancées de l'API v4.