Il s'agit du guide du développeur pour l'API Reporting Analytics version 4. Pour une description détaillée de 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 la structure du corps de la réponse de batchGet.
Corps de la requête
Pour demander des données à l'aide de l'API Analytics Reporting v4, vous devez créer un objet ReportRequest, qui répond aux exigences minimales suivantes:
- 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 metrics.
Pour trouver un ID de vue, interrogez la méthode des récapitulatifs du compte ou utilisez l'explorateur de comptes.
Si aucune plage de dates n'est indiquée, la plage de dates par défaut est : {"startDate": "7daysAgo", "endDate": "yesterday"}.
Voici un exemple de requête avec les champs obligatoires 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 comporter les mêmes éléments 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 et les métriques, ainsi que 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 à 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 au cours de la période 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 des métriques disponibles.
Filtrage
Lorsque vous envoyez une requête batchGet, vous pouvez lui demander de renvoyer uniquement les métriques qui répondent à des critères spécifiques. Pour filtrer les métriques, spécifiez une ou plusieurs MetricFilterClauses dans le corps de la requête et, dans chaque MetricFilterClause, définissez un ou plusieurs MetricFilters.
Dans chaque élément MetricFilter, spécifiez les valeurs des éléments suivants:
metricNamenotoperatorcomparisonValue
Soit {metricName} représente la métrique, {operator} la operator et {comparisonValue} la comparisonValue. Le filtre fonctionne alors 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"
}
]
}
]
}
Classement
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) via le champsortOrder.
Dans l'exemple suivant, batchGet renvoie les métriques triées d'abord par sessions, puis par pages vues dans l'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 ("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 demande batchGet, vous pouvez lui demander de renvoyer uniquement les dimensions qui répondent à des critères spécifiques. Pour filtrer des dimensions, spécifiez une ou plusieurs DimensionsFilterClauses dans le corps de la requête, puis définissez un ou plusieurs DimensionsFilters dans chaque DimensionsFilterClause.
Dans chaque élément DimensionsFilters, spécifiez les valeurs des éléments suivants:
dimensionNamenotoperatorexpressionscaseSensitive
Soit {dimensionName} représente la dimension, {operator} la operator et {expressions} la expressions. Le filtre fonctionne alors 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"]
}
]
}
]
}
]
}
Classement
Pour trier les résultats en fonction d'une 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 comportant des valeurs entières, il est plus facile de comprendre leurs caractéristiques en regroupant leurs valeurs dans des plages. Utilisez le champ histogramBuckets pour définir les plages des buckets résultants et spécifiez 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
La version 4 de l'API Google Analytics Reporting vous permet d'obtenir des données pour plusieurs plages de dates à l'aide d'une seule requête. Que 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étriques dans deux plages de dates, vous pouvez classer 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 de date
Si vous demandez une dimension liée à une date ou une heure, l'objet DateRangeValue ne contiendra que les valeurs pour les dates comprises dans les plages respectives. Toutes les autres valeurs qui ne sont pas dans les plages de dates spécifiées seront 0.
Prenons l'exemple d'une requête pour la dimension ga:date et la métrique ga:sessions pour deux plages de dates: janvier et février.
Dans la réponse contenant les données demandées du mois de janvier, les valeurs de janvier seront 0. Dans la réponse concernant les données demandées en février, les valeurs de 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 des segments. Par exemple, vous pouvez définir les utilisateurs d'un pays ou d'une ville spécifique dans un segment, et ceux qui consultent une section spécifique de votre site dans un autre. Les filtres renvoient uniquement les lignes qui remplissent une condition, tandis que les segments renvoient un sous-ensemble d'utilisateurs, de sessions ou d'événements qui remplissent les conditions contenant les segments.
Lorsque vous effectuez une demande avec des segments, vérifiez les points suivants:
- Chaque ReportRequest d'une méthode
batchGetdoit contenir des définitions de segment identiques. - Vous 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 découvrir 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. Il s'agit d'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'échantillon plus petite. - Définissez la valeur sur
LARGEpour obtenir une réponse plus précise, mais plus lente. - Définissez la valeur sur
DEFAULTpour obtenir une réponse qui équilibre la vitesse et la précision.
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 échantillons de données, la version 4 de l'API Analytics Reporting affiche 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 un échantillon de données provenant d'une requête portant sur deux plages de dates. Les résultats ont été calculés à partir de près de 500 000 échantillons d'un espace d'échantillonnage d'environ 15 millions de sessions:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Pagination
L'API Analytics Reporting v4 utilise les champs pageToken et pageSize pour paginer les résultats des réponses qui s'étendent sur plusieurs pages. Vous obtenez pageToken à partir 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 couvert les bases de la création d'un rapport, découvrez les fonctionnalités avancées de l'API v4.