Créer un rapport

Ceci est le guide du développeur de 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.

Remarque:Cette API n'est pas compatible avec les propriétés Google Analytics 4 (GA4). Veuillez utiliser l'API Google Analytics Data afin d'accéder aux nouvelles fonctionnalités de reporting pour les propriétés GA4.

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:

• 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 metrics.

Pour trouver un ID de vue, interrogez la méthode des récapitulatifs de compte ou utilisez l'explorateur de compte. 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:

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 é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"
                        ]
                    }
                ]
            }
        }
    ]
}

Remarque :Lors de l'analyse du corps de la réponse, si un champ booléen est absent, vous pouvez supposer que sa valeur est false. Seuls les champs booléens avec une valeur true sont affichés dans la réponse. Par exemple, le champ isDataGolden figure dans la réponse si sa valeur est true.

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 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 des métriques disponibles.

Filtrage

Lorsque vous envoyez une requête batchGet, vous pouvez lui demander de ne renvoyer que des 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, puis définissez un ou plusieurs MetricFilters dans chaque MetricFilterClause. Dans chaque élément MetricFilter, spécifiez les valeurs des éléments suivants:

• metricName
• not
• operator
• comparisonValue

Soit {metricName}, la métrique, {operator} le operator, et {comparisonValue} le 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"
        }
      ]
    }
  ]
}

Remarque :Vous pouvez également spécifier les types de mise en forme des expressions de métriques que vous avez définies.

Classement

Pour trier les résultats en fonction d'une valeur de métrique:

• Saisissez son nom ou son alias dans le champ fieldName.
• Spécifiez l'ordre de tri (ASCENDING ou DESCENDING) via le champ sortOrder.

Dans l'exemple suivant, batchGet renvoie les métriques triées d'abord par session, 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 ne renvoyer que des 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:

• dimensionName
• not
• operator
• expressions
• caseSensitive

Soit {dimensionName}, la dimension, {operator} le operator et {expressions} le 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:

• Saisissez son nom dans le champ fieldName.
• Spécifiez l'ordre de tri (ASCENDING ou DESCENDING) via le champ sortOrder.

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 répartissant leurs valeurs dans des plages. Utilisez le champ histogramBuckets pour définir les plages des buckets obtenus 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"
        }
      ]
    }
  ]
}

Remarque :Consultez la page Request Composer pour obtenir une application de démonstration qui utilise certaines de ces fonctionnalités.

Plusieurs plages de dates

La version 4 de l'API Reporting de Google Analytics 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 trier les résultats en fonction de la différence entre les valeurs de la métrique dans les plages de dates, 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"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

Comportement des dimensions 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 dans 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 concernant 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 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 partie 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 envoyez une demande avec des segments, vérifiez les points suivants:

• Chaque ReportRequest dans une méthode batchGet doit 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"}]
    }
  ]
}

Remarque :Le champ segmentId est également compatible avec la syntaxe des segments dans la version 3 de l'API Core Reporting. Pour en savoir plus, consultez le guide de migration.

Sampling

Remarque :Pour les comptes Analytics 360, envisagez d'utiliser la fonctionnalité Quota basé sur les ressources afin d'exploiter des seuils d'échantillonnage plus élevés lorsque vous utilisez l'API Analytics Reporting.

L'échantillonnage peut avoir une incidence sur les résultats de vos données. C'est aussi souvent pour cela que 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 SMALL pour obtenir une réponse rapide avec une taille d'échantillon plus petite.
• définissez la valeur sur LARGE pour obtenir une réponse plus précise, mais plus lente.
• définissez la valeur sur DEFAULT pour 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"
    }
  ]
}

Remarque :Chaque ReportRequest dans une méthode batchGet doit contenir la même définition samplingLevel.

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 échantillons 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'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 Reporting v4 utilise les champs pageToken et pageSize pour paginer les résultats de réponse 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",
  }]
}

Remarque :Techniquement, nextPageToken peut être une chaîne arbitraire, mais dans la plupart des cas, il s'agit d'un index de ligne basé sur zéro. Pour assurer une pagination appropriée, utilisez la valeur nextPageToken pour le champ pageToken.

Étape suivante

Maintenant que vous connaissez les bases de la création d'un rapport, découvrez les fonctionnalités avancées de l'API v4.