API Reporting sur les entonnoirs multicanaux : Guide de référence

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Ce document fournit des informations de référence complètes sur les requêtes et les réponses de l'API de création de rapports 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 Google Analytics. Chaque rapport se compose de statistiques issues des données que le code de suivi renvoie à Analytics, organisées en tant que dimensions et métriques. En choisissant vos propres combinaisons de dimensions et de métriques, vous pouvez utiliser l'API Reporting pour créer des rapports personnalisés et adaptés à vos propres spécifications.

L'API contient une seule méthode qui demande des 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. Vous devez également spécifier les éléments suivants:

  • Une combinaison de dimensions et de métriques.
  • Une période.
  • Ensemble de paramètres d'option qui contrôlent les données renvoyées

L'API rend la méthode report.get disponible à 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.

Demande

L'API fournit une seule méthode pour demander des données:

analytics.data.mcf.get()

L'API peut également être interrogée 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 d'API qui doit être encodé au format URL.

Toutes les requêtes adressé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 chaque nom de paramètre pour obtenir une description détaillée.

Nom Value Obligatoire Synthèse
ids string oui ID de la table unique au format ga:XXXX, où XXXX est l'ID de la vue (profil) Analytics pour lequel la requête va extraire 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, telles que mcf:totalConversions,mcf:totalConversionValue. Une requête valide doit spécifier au moins une métrique.
dimensions string non Liste de dimensions séparées par une virgule pour votre rapport sur les entonnoirs multicanaux, par exemple mcf:source,mcf:keyword.
sort string non Liste de métriques et de dimensions séparées par une virgule indiquant l'ordre de tri et le sens de tri pour les données renvoyées.
filters string non Filtres de dimensions ou de métriques qui limitent les données renvoyées pour votre requête.
samplingLevel string non Niveau d'échantillonnage souhaité. Valeurs autorisées :
  • DEFAULT : renvoie une réponse avec un échantillon qui équilibre la vitesse et la justesse.
  • FASTER : renvoie une réponse rapide avec un échantillon de taille plus petit.
  • HIGHER_PRECISION : renvoie une réponse plus précise avec une taille d'échantillon importante, mais cela peut ralentir la réponse.
start-index integer non 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 non Nombre maximal de lignes à inclure dans la réponse.

Détails des paramètres de requête

ids

ids=ga:12345
Obligatoire.
ID unique permettant de récupérer les données des entonnoirs multicanaux. Cet ID correspond à la concaténation de l'espace de noms ga: avec l'ID de vue (profil) du rapport. Vous pouvez récupérer l'ID de vue (profil) de votre rapport à l'aide de la méthode analytics.management.profiles.list, qui fournit l'identifiant id dans la ressource de vue (profil) de l'API Management de Google Analytics.

Haut de page


date de début

start-date=2011-10-01
Obligatoire.
Toutes les demandes de données des entonnoirs multicanaux 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 les valeurs relatives en utilisant today, yesterday ou NdaysAgo. Les valeurs doivent correspondre à [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
Le premier start-date valide est 2011-01-01. Aucune limite supérieure ne s'applique à un start-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 7 derniers jours (à partir d'hier) en utilisant des dates relatives:

  &start-date=7daysAgo
  &end-date=yesterday

Haut de page


date de fin

end-date=2011-10-31
Obligatoire.
Toutes les demandes de données des entonnoirs multicanaux 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 les valeurs relatives en utilisant today, yesterday ou NdaysAgo. Les valeurs doivent correspondre à [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
Le premier end-date valide est 2005-01-01. Aucune limite ne s'applique pour les 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 (à partir d'aujourd'hui) en utilisant des dates relatives:

  &start-date=9daysAgo
  &end-date=today

Haut de page


dimensions

dimensions=mcf:source,mcf:keyword
Facultatif.

Le paramètre de dimensions définit les clés des données principales pour votre rapport sur les entonnoirs multicanaux (par exemple, mcf:source ou mcf:medium). Utilisez les dimensions pour segmenter vos métriques de conversion. Par exemple, 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ées par support. Dans ce cas, vous pouvez consulter 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 indiquer un maximum de sept dimensions par requête.
  • Vous ne pouvez pas envoyer de 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 (not set).

Haut de page


métrique

metrics=mcf:totalConversions,mcf:totalConversionValue
Obligatoire.

Statistiques cumulées pour 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 aucun 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:

  • Chaque requête doit fournir au moins une métrique. Une requête ne peut pas être composée uniquement de dimensions.
  • Vous pouvez fournir jusqu'à 10 métriques par requête.

Haut de page


sort

sort=mcf:source,mcf:medium
Facultatif.

Liste de métriques et de dimensions indiquant l'ordre de tri et le sens de tri des données renvoyées.

  • Le ordre de tri est indiqué par l'ordre de gauche à droite des métriques et les dimensions répertoriées.
  • Par défaut, le tri de la direction est croissant et peut être modifié en ordre décroissant à l'aide 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 trie d'abord par mcf:source, puis par mcf:medium, les deux par 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 effectuer une requête avec le paramètre suivant. Il trie d'abord par mcf:medium, puis par mcf:source, dans l'ordre croissant:

sort=mcf:medium,mcf:source

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

  • Ne triez que 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 sur un champ qui n'est indiqué ni dans les paramètres des dimensions, ni dans celui des métriques, une erreur s'affiche.
  • Par défaut, les chaînes sont triées par ordre alphabétique croissant dans les paramètres régionaux en-US.
  • Par défaut, les numéros sont triés par ordre numérique croissant.
  • Par défaut, les dates sont triées dans l'ordre croissant par date.

Haut de page


filtres

filters=mcf:medium%3D%3Dreferral
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 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.

Haut de page


Niveau d'échantillonnage

samplingLevel=DEFAULT
Facultatif.
Utilisez ce paramètre pour définir le niveau d'échantillonnage (c'est-à-dire le nombre de sessions utilisé pour calculer le résultat) pour une requête de rapport. Les valeurs autorisées sont cohérentes avec l'interface Web et incluent les éléments suivants :
  • DEFAULT : renvoie une réponse avec un échantillon qui équilibre la vitesse et la justesse.
  • FASTER : renvoie une réponse rapide avec un échantillon de taille plus petit.
  • HIGHER_PRECISION : renvoie une réponse plus précise avec une taille d'échantillon importante, mais cela peut ralentir la réponse.
Sinon, 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.

Haut de page


résultats max

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, à commencer par le premier. Si max-results n'est pas fourni, la requête renvoie le nombre maximal de lignes par défaut (1 000).

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 de lignes demandées. Elle peut également renvoyer moins de lignes que si elle n'avait pas autant de segments de dimensions 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 avez défini une valeur supérieure pour max-results.

Haut de page


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 des 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 pour la réponse actuelle, comme expliqué dans itemsPerPage.

Format de réponse

JSON
{
  "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
    ]
  ],
}

Haut de page

Champs de réponse

Les propriétés de la structure du corps de la réponse sont définies comme suit:

Nom de propriété Value 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 de métriques analytiques.
query.sort[] list Liste des métriques ou des dimensions avec 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 lignes de départ. 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é 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 est inférieure à max-results ou à 10 000. 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 entraînent un grand nombre de lignes, totalResults peut être supérieur à itemsPerPage. Pour en savoir plus sur totalResults et itemsPerPage pour les requêtes volumineuses, consultez la page Paging.
profileInfo object Informations sur la vue (profil) pour laquelle les données ont été demandées. Les données de vue (profil) sont disponibles via l'API Management de Google Analytics.
profileInfo.profileId string ID de la vue (profil), par exemple 1174.
profileInfo.accountId string ID du compte auquel appartient cette vue (profil), par exemple 30481.
profileInfo.webPropertyId string ID de propriété Web auquel 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 la table (vue) composé de "ga:" suivi de l'ID de la vue (profil).
containsSampledData boolean Vrai 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 disponible dans lequel les échantillons ont été sélectionnés.
columnHeaders[] list En-têtes de colonne qui répertorient 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 et au nombre de métriques.
columnHeaders[].name string Nom de la dimension ou de la métrique.
columnHeaders[].columnType string Type de colonne. METRIC DIMENSION ou MÉTRIQUE.
columnHeaders[].dataType string Type de données. Les en-têtes de colonne de dimension ne comportent que le type de données "STRING" ou "MCF_SEQUENCE". Les en-têtes de colonnes de métriques comportent des types de données pour les valeurs de métriques telles que "INTEGER", "DOUBLE", "CURRENCY", etc.
totalsForAllResults object Nombre total de valeurs 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 identique à celui spécifié dans la requête.
rows[] list

Les lignes de données du rapport, où chaque ligne contient une liste d'objets Mcf.Rows Cette liste interne représente les valeurs des dimensions, suivies des valeurs des métriques, dans le même ordre que celui spécifié dans la requête. Chaque ligne comporte une liste de N champs, où N = le nombre de dimensions + le nombre de métriques.

Un objet Mcf.Rows encapsule un autre objet qui peut être de type primitiveValue ou conversionPathValue. Les valeurs de dimension peuvent être de l'un ou l'autre type, tandis que toutes les valeurs de métriques sont de type primitiveValue.

Une primitiveValue est simplement une chaîne encapsulée dans un objet. Exemple :

{
  "primitiveValue": "2183"
}

Un objet conversionPathValue est un objet enveloppé autour d'un tableau d'objets, chaque objet contenant une chaîne nodeValue et une chaîne interactionType facultative. Exemple :

{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

Haut de page

Codes d'erreur

L'API de création de rapports sur les entonnoirs multicanaux renvoie un code d'état HTTP 200 si la 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 la bonne logique de traitement des erreurs. Pour en savoir plus sur les codes d'erreur et sur la façon de les gérer, consultez le guide de référence sur les réponses d'erreur.

Haut de page

Essayer

Utilisez l'explorateur d'API ci-dessous pour appeler cette méthode sur des données en direct, puis observez la réponse.

Haut de page

Échantillonnage

Google Analytics calcule instantanément certaines combinaisons de dimensions et de métriques. Pour renvoyer les données dans un délai raisonnable, Google Analytics ne peut traiter qu'un échantillon des données.

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 Reporting de MCF contient des données échantillonnées, le champ de la 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 permettent de calculer le pourcentage de sessions utilisées pour la requête. Par exemple, si sampleSize est 201,000 et sampleSpace est 220,000,le rapport est basé sur (201 000 / 220 000) * 100 = 91,36 % des sessions.

Pour obtenir une description générale de l'échantillonnage et de son utilisation dans Google Analytics, consultez la page Échantillonnage.

Haut de page

Gérer les résultats de données volumineux

Si vous pensez que votre requête renverra un ensemble de résultats volumineux, suivez les consignes ci-dessous pour optimiser votre requête API, éviter les erreurs et limiter les dépassements de quota. Notez que nous définissons un benchmark des performances en autorisant un maximum de sept dimensions et 10 métriques par requête API. Même si certaines requêtes spécifiant un grand nombre de métriques et de dimensions peuvent prendre plus de temps que d'autres, limiter le nombre de métriques demandées n'est pas suffisant pour améliorer les performances des requêtes. Pour des performances optimales, vous pouvez utiliser les techniques suivantes.

Réduire les dimensions par requête

L'API permet de spécifier jusqu'à sept dimensions par 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 obtenues est élevé. Par exemple, l'interrogation 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.

Diviser la requête par plage de dates

Plutôt que de parcourir les résultats clés d'une longue plage de dates, pensez à former des requêtes distinctes pour une semaine, voire un jour, à la fois. Bien sûr, pour un ensemble de données volumineux, une requête portant sur une seule journée de données 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 séparer 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 monothread et parallèles.

Paging

Parcourir les résultats peut s'avérer utile pour diviser des ensembles de résultats volumineux en segments 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 pratique de définir une limite explicite de taille des réponses 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

Un moyen simple et pratique de réduire la bande passante requise pour chaque requête consiste à activer la compression gzip. Même si la décompression des résultats nécessite un 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 qu'il contienne la chaîne gzip. Voici un exemple d'en-têtes HTTP correctement formatés pour activer la compression gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)