Google Analytics 4 Reporting API: how to connect

A Google Cloud project and API activation

Configuration starts with a project in the Google Cloud console. The project acts as a container for the settings and services associated with the API. If you already have a Google Cloud project, you can use it. Make sure the correct project is selected in the top navigation bar; otherwise, your configuration will be saved in the wrong project.

Next, enable the Google Analytics Data API. Open the navigation menu in the top-left corner of the Google Cloud console and go to APIs & Services → Library. Find the API and click Enable. If you skip this step, API requests will fail, so enabling the service is essential.

A service account and credentials

The next part of the setup is a service account. This is a special technical account that acts on behalf of an application and lets it communicate with the API without an interactive sign-in using a personal Google account. To create one, open the navigation menu in the Google Cloud console, go to IAM & Admin → Service Accounts and add a new account. Give it a unique identifier, such as ga4-api-client.

Use permissions appropriate to the application. Reading GA4 reports does not require granting the service account the Google Cloud project Owner role. Access to Analytics data is configured separately in GA4, as described below.

Generate a JSON key for the service account. Go to IAM & Admin → Service Accounts, then click the email address of the account you want to use. Open the Keys tab, select Add key → Create new key and choose JSON.

A file containing the credentials needed to communicate with the API will be downloaded. Treat it like a password and store it securely: do not publish it or commit it to a code repository. If the key is lost or exposed, revoke it in the Google Cloud console and generate a replacement.

Granting access in GA4

The service account cannot access Google Analytics data until you add it as a user in GA4. Sign in to analytics.google.com and click the gear icon in the bottom-left corner to open Admin. You can manage access at account or property level. To limit access to the property you need, open Property access management.

Add a new user using the service account’s email address, which is generated in a format such as [email protected]. You must have the appropriate administrative permissions in Google Analytics to add a user.

Different roles are available when adding the account. For reading reports through the Data API, the Viewer role is sufficient. Administrator access is unnecessary for this purpose. If the service account has not been added to GA4, or it lacks the required permissions, an API request may fail with 403: insufficient permissions.

Using the correct property identifier

GA4 exposes several identifiers, but API requests require the Property ID. You can find it in analytics.google.com: open Admin using the gear icon, then go to Property settings → Property details. Look for the Property ID field.

Use this numeric identifier in API requests. A different identifier, such as the Measurement ID in the format G-XXXXXXX, is not a substitute for the Property ID and will cause the request to fail.

An example request in Python

You can verify the connection using the example from Google’s documentation. The code uses the google-analytics-data library. Authentication uses the GOOGLE_APPLICATION_CREDENTIALS environment variable, which must point to the .json key file downloaded when you created the service account key.

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

# Path to the JSON file containing the service account key
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = 'google-key-file.json'

def sample_run_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a simple report on a GA4 property."""
    client = BetaAnalyticsDataClient()

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

    response = client.run_report(request)

    print("Report result:")
    for row in response.rows:
        print(row.dimension_values[0].value, row.metric_values[0].value)