Ce document constitue la documentation de référence complète sur les requêtes et les réponses de l'API Reporting sur les entonnoirs multicanaux.
Introduction
L'API de création de rapports sur les entonnoirs multicanaux vous permet de demander des données de rapport sur les entonnoirs multicanaux de Google Analytics. Chaque rapport est composé de statistiques issues des données que le code de suivi renvoie à Analytics. Ces statistiques sont organisées sous forme de dimensions et de métriques. Si vous choisissez vos propres combinaisons de dimensions et de métriques, vous pouvez utiliser l'API Reporting pour créer des rapports personnalisés adaptés à vos besoins.
L'API contient une seule méthode qui demande les données de rapport: report.get. Avec cette méthode, vous fournissez l'ID de table correspondant à la vue (profil) pour laquelle vous souhaitez récupérer des données. En outre, vous spécifiez les éléments suivants:
- Une combinaison de dimensions et de métriques.
- Une période.
- Un ensemble de paramètres d'option qui contrôlent les données renvoyées
L'API rend la méthode report.get disponible sur un point de terminaison REST : https://www.googleapis.com/analytics/v3/data/mcf. La section suivante présente un exemple de requête et décrit chacun des paramètres.
Requête
L'API fournit une méthode unique pour demander des données:
analytics.data.mcf.get()
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/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Chaque paramètre de requête d'URL spécifie un paramètre de requête API qui doit être encodé au format URL.
Toutes les requêtes envoyées à l'API de création de rapports sur les entonnoirs multicanaux doivent être autorisées, de préférence via OAuth 2.0.
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 de création de rapports sur les entonnoirs multicanaux. 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 mcf:totalConversions,mcf:totalConversionValue.
Pour être valide, une requête doit spécifier au moins une métrique. |
dimensions |
string |
no | Liste de dimensions séparées par une virgule pour votre rapport sur les entonnoirs multicanaux,
par exemple mcf:source,mcf:keyword. |
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. |
samplingLevel |
string |
no | Niveau d'échantillonnage souhaité. Valeurs autorisées :
|
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. |
Détails des paramètres de requête
ids
ids=ga:12345
ga: avec l'ID de la vue (profil) du rapport. Pour récupérer l'ID de la vue (profil) de votre rapport, utilisez la méthode analytics.management.profiles.list, qui fournit le id dans la ressource Vue (profil) de l'
API Google Analytics Management.
date de début
start-date=2011-10-01
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 2011-01-01.
Il n'existe pas de limite supérieure pour un start-date.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=2011-10-31
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=mcf:source,mcf:keyword
Le paramètre de dimensions définit les données principales clés pour votre rapport sur les entonnoirs multicanaux, telles que mcf:source ou mcf:medium.
Utilisez les dimensions pour segmenter vos métriques de conversion. Par exemple, même si vous pouvez demander le nombre total de conversions sur votre site, il peut être plus intéressant de demander le nombre de conversions segmenté par support.
Dans ce cas, vous verrez le nombre de conversions générées par les résultats naturels, les sites référents, les e-mails, 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.
Valeurs non disponibles
Lorsque la valeur de la dimension ne peut pas être déterminée, Analytics utilise la chaîne spéciale (non définie).
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
Statistiques cumulées sur l'activité des utilisateurs sur votre site, telles que le nombre total de conversions ou la valeur de conversion totale.
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 la valeur de conversion totale globale. Toutefois, lorsque des dimensions sont demandées, les valeurs sont segmentées par valeur de dimension.
Par exemple, mcf:totalConversions demandé avec mcf:source renvoie le nombre total de conversions par source.
Lorsque vous demandez des métriques, gardez à l'esprit les points suivants:
- Toute requête doit fournir au moins une métrique. Une requête ne peut pas comporter uniquement des dimensions.
- Vous pouvez fournir jusqu'à 10 métriques par requête.
sort
sort=mcf:source,mcf:medium
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 "Quelles sont mes principales sources de conversion et par quels supports ?".
vous pouvez effectuer une requête avec le paramètre suivant. Il effectue un tri d'abord par mcf:source, puis par mcf:medium, les deux dans l'ordre croissant:
sort=mcf:source,mcf:medium
Pour répondre à la question "Quels sont mes principaux supports de conversion et à partir de quelles sources ?", vous pouvez créer une requête avec le paramètre suivant. Il effectue un tri d'abord par mcf:medium, puis par mcf:source, les deux dans l'ordre croissant:
sort=mcf:medium,mcf:source
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
dimensionsoumetrics. 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=mcf: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 mcf:totalConversions et mcf:source pour la vue (profil) 12134, où la dimension mcf:medium correspond à la chaîne referral:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Pour en savoir plus, consultez la documentation de référence de l'API Core Reporting.
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é.max-results
max-results=100
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 de création de rapports sur les entonnoirs multicanaux 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 mcf:medium. Par conséquent, lorsque vous segmentez uniquement par support, vous ne pouvez pas obtenir plus de 300 lignes, même si vous définissez max-results sur une valeur supérieure.
Réponse
Si la requête aboutit, la requête renvoie un corps de réponse avec la structure JSON 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.
Format de réponse
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
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#mcfData". |
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.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.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
Index de départ des lignes. La valeur par défaut est 1. |
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.
|
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 de la propriété Web à laquelle appartient cette vue (profil), par exemple 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 colonne des dimensions ne possèdent que le type de données "STRING" ou "MCF_SEQUENCE".
Les en-têtes des colonnes de métriques comportent des types de données pour les valeurs de métriques telles que "INTEGER", "DOUBLE", "CURRENCY", etc. |
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 de rapport, où chaque ligne contient une liste d' Un objet Un
{
"primitiveValue": "2183"
}
Un
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
Codes d'erreur
Si la requête aboutit, l'API de création de rapports sur les entonnoirs multicanaux renvoie un code d'état HTTP 200. 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
Utilisez l'explorateur d'API ci-dessous pour appeler cette méthode sur des données en direct, puis observez la réponse.
É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 de création de rapports sur les entonnoirs multicanaux contient des données échantillonnées, le champ de réponse containsSampledData indiquera 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)