Google Analytics Data API Client Library

0.21.0 · active · verified Thu Apr 09

The Google Analytics Data API client library provides programmatic methods to access report data in Google Analytics 4 (GA4) properties. It is an actively maintained library within the `googleapis/google-cloud-python` ecosystem, with frequent updates that may include new features and occasional breaking changes.

Warnings

breaking Version 0.20.0 (January 8, 2026) introduced breaking changes to resource pattern values for `analyticsdata.googleapis.com/AudienceList` and `analyticsadmin.googleapis.com/Property`.
Fix: Review the official changelog and update your resource paths to `properties/{property}/audienceLists/{audience_list}` and `properties/{property}` respectively.
breaking A significant schema compatibility change for the underlying Data API occurred on December 1, 2022. This impacts how certain dimensions and metrics can be combined, specifically making item-scoped dimensions incompatible with event-scoped metrics, and attribution dimensions with some event-scoped metrics.
Fix: Consult the official Google Analytics Data API changelog regarding schema changes to understand valid dimension-metric combinations.
gotcha Authentication is critical and a common setup point. You must enable the Analytics Data API in your Google Cloud project and set up a service account. The client library typically uses the `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account JSON key file for authentication.
Fix: Follow the official Google Cloud authentication guides for client libraries. Create a service account, download its JSON key, and set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. Ensure the service account has 'Viewer' or appropriate access to the GA4 property.
gotcha This client library requires Python 3.9 or newer. Older Python versions are not supported for the latest library releases.
Fix: Upgrade your Python environment to 3.9 or a newer supported version.
gotcha Logs from this library may contain sensitive information. Google may also refine the occurrence, level, and content of log messages without flagging them as breaking changes.
Fix: Exercise caution when handling or persisting logs. Do not depend on the immutability of logging events.

Install

pip install google-analytics-data Install stable version

Imports

BetaAnalyticsDataClient
```
from google.analytics.data_v1beta import BetaAnalyticsDataClient
```
This is the primary client for the GA4 Data API v1beta.
RunReportRequest
```
from google.analytics.data_v1beta.types import RunReportRequest
```
Type hints for request objects are available in the .types submodule.

Quickstart

This quickstart demonstrates how to authenticate using a service account (via `GOOGLE_APPLICATION_CREDENTIALS` environment variable) and run a basic report on a Google Analytics 4 property to get active users by city for the last 7 days. You need to enable the Analytics Data API and configure a service account with appropriate permissions.

import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest

# Replace with your Google Analytics 4 property ID.
# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set
# to the path of your service account key file.
PROPERTY_ID = os.environ.get("GA4_PROPERTY_ID", "YOUR-GA4-PROPERTY-ID")

def run_simple_report(property_id):
    """Runs a simple report on a Google Analytics 4 property."""
    client = BetaAnalyticsDataClient()

    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[Dimension(name="city")],
        metrics=[Metric(name="activeUsers")],
        date_ranges=[DateRange(start_date="7daysAgo", end_date="today")],
    )

    response = client.run_report(request)

    print(f"Report result for property: {response.property_header.property_id}")
    print("Row count: {}".format(len(response.rows)))

    print("\nReport data:")
    for row in response.rows:
        print(f"{row.dimension_values[0].value}: {row.metric_values[0].value}")

if __name__ == "__main__":
    if PROPERTY_ID == "YOUR-GA4-PROPERTY-ID":
        print("Please set the 'GA4_PROPERTY_ID' environment variable or update the script.")
        print("Also ensure 'GOOGLE_APPLICATION_CREDENTIALS' is set for authentication.")
    else:
        run_simple_report(PROPERTY_ID)

view raw JSON →