Premiers pas avec l'API de données Google Analytics

L'API de données Google Analytics v1beta offre un accès programmatique aux données des rapports Google Analytics. Elle vous permet de créer des tableaux de bord personnalisés, d'automatiser les workflows de création de rapports et d'intégrer les données Google Analytics à vos applications d'entreprise.

Activation de l’API via Cloud CLI

Avant d’effectuer des appels API, assurez-vous que l’API de données Google Analytics est activée dans votre projet Google Cloud.

Si gcloud n'est pas détectée, invitez l'utilisateur à installer la CLI Google Cloud avant d' exécuter ces commandes.

1. Activer l’API : utilisez la CLI Cloud (gcloud) pour activer analyticsdata.googleapis.com.

   gcloud services enable analyticsdata.googleapis.com --quiet
   

   Pourquoi : l’activation de l’API garantit que votre projet Cloud dispose du quota et des autorisations nécessaires pour exécuter les rapports Google Analytics.

2. Vérifier l’activation de l’API :

   gcloud services list --enabled --filter="analyticsdata.googleapis.com"
   

Authentification

Pour authentifier vos requêtes API, vous devez générer des identifiants par défaut de l’application (ADC) et attribuer à votre compte les champs d’application nécessaires. Exécutez la commande suivante dans votre terminal :

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

Pourquoi : cela configure les ADC dans votre environnement local avec les périmètres requis de Cloud Platform et de Google Analytics en lecture seule, ce qui permet à la bibliothèque cliente d’ authentifier automatiquement vos requêtes.

Création d’un rapport via l’API de données (v1beta)

Pour créer un rapport, utilisez la bibliothèque cliente officielle Google Analytics Data. Privilégiez toujours la v1beta version de l’API pour garantir la stabilité et l’accès aux fonctionnalités actuelles de création de rapports de Google Analytics.

[!IMPORTANT] Directive obligatoire relative à l’agent : lorsque l’utilisateur sélectionne ou nécessite un langage de programmation spécifique, consultez le guide de référence correspondant à la configuration de la bibliothèque cliente figurant references/ liste ci-dessous.

Bibliothèques client prises en charge

Python

Si vous devez installer ou configurer la bibliothèque cliente de l’API de données Google Analytics pour Python, consultez le guide de configuration :

• Référence d'installation Python (paquet : google-analytics-data)

Java

Si vous devez installer ou configurer la bibliothèque cliente de l'API de données Google Analytics pour Java, consultez le guide de configuration :

• Référence d'installation Java (artefact : com.google.cloud:google-cloud-analytics-data)

PHP

Si vous devez installer ou configurer la bibliothèque cliente de l’API de données Google Analytics pour PHP, consultez le guide de configuration :

• Référence d'installation PHP (paquet : google/analytics-data)

Node.js

Si vous devez installer ou configurer la bibliothèque cliente de l'API de données Google Analytics pour Node.js, consultez le guide de configuration :

• Référence d'installation pour Node.js (package : @google-analytics/data)

Go

Si vous devez installer ou configurer la bibliothèque cliente de l'API de données Google Analytics pour Go, consultez le guide de configuration :

• Référence d'installation pour Go (paquet : cloud.google.com/go/analytics/data/apiv1beta)

.NET

Si vous devez installer ou configurer la bibliothèque cliente de l'API de données Google Analytics pour .NET / C#, consultez le guide de configuration :

• Référence d’installation .NET (package : Google.Analytics.Data.V1Beta)

Ruby

Si vous devez installer ou configurer la bibliothèque cliente de l'API de données Google Analytics pour Ruby, consultez le guide de configuration :

• Référence d'installation pour Ruby (Gem : google-analytics-data-v1beta)

[!REMARQUE] Ressources supplémentaires : pour découvrir d’autres exemples d’appel de l’API Data avec Java, PHP, Node.js, .NET, Python et REST, ainsi que des conseils sur l’ authentification à l’aide d’un compte de service, consultez le guide officiel « Démarrage rapide de l’API Data ».

Guide de démarrage rapide pour Python

1. Installer la bibliothèque cliente :

   pip install google-analytics-data
   

   Si pip n'est pas disponible, invitez l'utilisateur à l'installer pip avant d’installer la bibliothèque cliente.

2. Lancer une requête de rapport : Vous trouverez ci-dessous un exemple complet illustrant comment interroger une propriété Google Analytics pour obtenir le nombre d’utilisateurs actifs et de sessions, regroupés par ville et par date. Remplacez YOUR-PROPERTY-ID par l'ID réel de votre propriété Google Analytics (par exemple, 1234567).

   from google.analytics.data_v1beta import BetaAnalyticsDataClient
   from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest
   
   def sample_run_report(property_id: str):
       # Initialize the client.
       # Assumes Application Default Credentials (ADC) are configured in your environment.
       client = BetaAnalyticsDataClient()
   
       request = RunReportRequest(
           property=f"properties/{property_id}",
           dimensions=[
               Dimension(name="city"),
               Dimension(name="date")
           ],
           metrics=[
               Metric(name="activeUsers"),
               Metric(name="sessions")
           ],
           date_ranges=[
               DateRange(start_date="2026-05-01", end_date="today")
           ],
       )
   
       response = client.run_report(request)
   
       print(f"Report result for property {property_id}:")
       for row in response.rows:
           print(
               f"City: {row.dimension_values[0].value}, "
               f"Date: {row.dimension_values[1].value}, "
               f"Active Users: {row.metric_values[0].value}, "
               f"Sessions: {row.metric_values[1].value}"
           )
   
   if __name__ == "__main__":
       sample_run_report("YOUR-PROPERTY-ID")
   

   Pourquoi : l’utilisation de BetaAnalyticsDataClient et RunReportRequest garantit la compatibilité avec le point de terminaison v1beta et une validation des requêtes fortement typée .

Schéma des métriques et des dimensions

Lors de la construction de votre RunReportRequest, vous devez utiliser des noms d’API valides pour les dimensions et les métriques. Reportez-vous à la documentation officielle du schéma de l’API de données pour obtenir la liste complète et faisant autorité des champs disponibles.

Dimensions couramment utilisées

Les dimensions représentent les attributs catégoriels de vos données.

• city: La ville de l'utilisateur.
• country: Le pays de l'utilisateur.
• date: La date de l'événement, au format AAAAMMJJ.
• deviceCategory: La catégorie d'appareil mobile (par exemple, ordinateur de bureau, mobile, tablette).
• eventName: Le nom de l'événement déclenché.
• pageTitle: Le titre de la page web.

Indicateurs couramment utilisés

Les indicateurs représentent des mesures quantitatives.

• activeUsers: Le nombre d'utilisateurs actifs.
• eventCount: Le nombre total d’événements.
• sessions: Le nombre total de sessions.
• screenPageViews: Le nombre d'écrans d'application ou de pages web consultés.
• totalRevenue: Le chiffre d'affaires total provenant des achats, des abonnements et de la publicité.

Vérification de la compatibilité des métriques et des dimensions

Certaines dimensions et mesures ne peuvent pas être interrogées conjointement dans une même requête de rapport . Si vous rencontrez une INVALID_ARGUMENT erreur liée à des champs incompatibles , vérifiez vos combinaisons de champs. Pour un accès programmatique au schéma de l’API de données , utilisez getMetadata(). Pour vérifier par programmation la compatibilité de combinaisons spécifiques de dimensions et de métriques avant d’exécuter un rapport, utilisez la checkCompatibility() méthode.

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import CheckCompatibilityRequest, Compatibility, Dimension, Metric

def sample_check_compatibility(property_id: str):
    client = BetaAnalyticsDataClient()

    # Define the dimensions and metrics you want to query together.
    # For example, checking if 'itemDescription' (an e-commerce dimension)
    # is compatible with 'activeUsers' and 'totalRevenue'.
    request = CheckCompatibilityRequest(
        property=f"properties/{property_id}",
        dimensions=[
            Dimension(name="itemDescription"),
            Dimension(name="date")
        ],
        metrics=[
            Metric(name="activeUsers"),
            Metric(name="totalRevenue")
        ],
    )
    response = client.check_compatibility(request)

    print(f"Compatibility check for property {property_id}:")
    for dim in response.dimension_compatibilities:
        is_compatible = dim.compatibility == Compatibility.COMPATIBLE
        print(f"Dimension '{dim.dimension_metadata.api_name}' is compatible: {is_compatible}")

    for metric in response.metric_compatibilities:
        is_compatible = metric.compatibility == Compatibility.COMPATIBLE
        print(f"Metric '{metric.metric_metadata.api_name}' is compatible: {is_compatible}")

if __name__ == "__main__":
    sample_check_compatibility("YOUR-PROPERTY-ID")