Google Analytics API Getting Started (2026)

Getting started overview

Integrating with the Google Analytics API involves a sequence of steps designed to ensure secure and authorized access to your analytics data. This guide focuses on the Google Analytics Data API (GA4), which provides access to Google Analytics 4 property data developers.google.com/analytics/devguides/reporting/data/v1. The process typically begins with setting up a Google Cloud project, enabling the necessary APIs, and then configuring OAuth 2.0 credentials for authentication.

Once credentials are established, developers can make programmatic requests to retrieve detailed reports on website and application usage. This allows for custom data analysis, integration with other business intelligence tools, and automation of reporting workflows. The API supports various dimensions and metrics, enabling granular control over the data returned. Understanding the event-based data model of Google Analytics 4 is fundamental for constructing effective API queries Google Analytics 4 API concepts.

The following table outlines the key steps to get started with the Google Analytics Data API:

Create an account and get keys

Before you can make API calls, you need to set up a Google Cloud Project and obtain the necessary OAuth 2.0 credentials. These credentials act as your application's identity when requesting access to a user's Google Analytics data OAuth 2.0 authorization framework.

1. Access the Google Cloud Console: Navigate to the Google Cloud Console. If you don't have a project, create a new one. This project will house all your API configurations and credentials.
2. Enable the Google Analytics Data API: In the Google Cloud Console, search for "Google Analytics Data API" in the API Library. Click on the API and then click "Enable." This step links the API to your project Google Cloud API Dashboard.
3. Configure the OAuth Consent Screen: Before creating credentials, you need to configure your OAuth consent screen. This screen is what users will see when they grant your application permission to access their Google Analytics data. Go to APIs & Services > OAuth consent screen.
   • Choose "External" user type for most applications and click "Create."
   • Fill in required fields such as Application name, User support email, and Developer contact information.
   • Add scopes. For accessing Google Analytics 4 data, common scopes include https://www.googleapis.com/auth/analytics.readonly or https://www.googleapis.com/auth/analytics, depending on your application's needs for read-only or read/write access respectively Google Analytics Data API authorization guide.
   • Save and publish your application if you intend for it to be publicly accessible. For testing, it can remain in "Testing" status.
4. Create OAuth 2.0 Client ID Credentials: Go to APIs & Services > Credentials.
   • Click "Create Credentials" and select "OAuth client ID."
   • Choose the application type that best suits your needs (e.g., "Web application" for server-side applications, "Desktop app" for local applications).
   • For web applications, input authorized redirect URIs (e.g., http://localhost:8080/oauth2callback for development). For desktop apps, no redirect URIs are typically needed.
   • After creation, you will receive a Client ID and Client Secret. Download these credentials as a JSON file, as you will need them for authenticating your API requests. Keep your Client Secret secure and do not expose it in client-side code.

Your first request

Once you have your OAuth 2.0 Client ID and Client Secret, you can proceed to make your first API request to retrieve Google Analytics 4 data. This example will use Python, but the principles apply across other supported languages like Java, Node.js, PHP, Ruby, and C# Google Analytics Data API client libraries.

1. Install the Google Client Library

First, install the Google API Python client library:

pip install google-api-python-client google-auth-oauthlib google-auth-httplib2

2. Authenticate and Authorize

The most common method for a desktop or local application involves a browser-based authorization flow. For web applications, you would typically handle the redirect and token exchange on your server.

import os

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest
from google_auth_oauthlib.flow import InstalledAppFlow
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials

# Scopes required for the Analytics Data API.
SCOPES = ['https://www.googleapis.com/auth/analytics.readonly']

# Path to your downloaded client_secret.json file.
CLIENT_SECRET_FILE = 'path/to/your/client_secret.json'

# The ID of your Google Analytics 4 property.
PROPERTY_ID = 'YOUR_GA4_PROPERTY_ID'

def get_credentials():
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                CLIENT_SECRET_FILE, SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open('token.json', 'w') as token:
            token.write(creds.to_json())
    return creds

def run_simple_report(property_id):
    credentials = get_credentials()
    client = BetaAnalyticsDataClient(credentials=credentials)

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

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

if __name__ == '__main__':
    # Replace with your actual GA4 Property ID
    # e.g., '123456789'
    run_simple_report(PROPERTY_ID)

3. Execute the Code

Replace 'path/to/your/client_secret.json' with the actual path to the JSON file you downloaded from Google Cloud Console. Also, replace 'YOUR_GA4_PROPERTY_ID' with your specific Google Analytics 4 property ID Python quickstart for Google Analytics Data API.

When you run the script for the first time, it will open a browser window, prompt you to log in to your Google account, and ask for permission for your application to access your Google Analytics data. After granting permission, the script will proceed to fetch and print a report of active users by city from your GA4 property.

Common next steps

After successfully making your first API call, consider these common next steps to further integrate and optimize your use of the Google Analytics Data API:

1. Explore More Dimensions and Metrics: The Google Analytics Data API offers a wide array of dimensions (e.g., eventName, pagePath) and metrics (e.g., eventCount, conversions). Consult the Google Analytics Data API schema documentation to discover additional data points relevant to your analysis.
2. Implement Filters and Segments: To refine your reports, learn how to apply dimension filters and metric filters to narrow down data based on specific criteria. For more advanced analysis, explore the capabilities of creating segments within your API requests to analyze subsets of your user base RunReport method documentation.
3. Handle Pagination: For large datasets, results are often paginated. Understand how to use the offset and limit parameters in your RunReportRequest to retrieve all available data efficiently.
4. Automate Reporting: Integrate your API calls into scheduled scripts or applications to automate the generation and delivery of custom analytics reports, reducing manual effort.
5. Error Handling and Rate Limits: Implement robust error handling in your application to gracefully manage API errors. Be aware of and respect the API's rate limits to prevent your application from being throttled Google Analytics Data API quotas and limits.
6. Explore Realtime Reporting: If your application requires up-to-the-minute data, investigate the Realtime Reporting API, which provides access to data about current user activity on your property.
7. Integrate with Other Google Cloud Services: Consider integrating with other Google Cloud services like BigQuery for advanced data warehousing and analysis, or Cloud Functions for serverless execution of your reporting logic.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for the Google Analytics Data API:

• Invalid Credentials:
  • Issue: "invalid_client" or "unauthorized_client" error.
  • Solution: Double-check that your client_secret.json file is correct and accessible. Ensure you are using the correct Client ID and Client Secret generated for the appropriate application type (e.g., web application vs. desktop app). Verify that the OAuth consent screen is configured correctly and, for web applications, your Authorized Redirect URIs match precisely Google authorization guide.
• Permission Denied (403 Error):
  • Issue: "User does not have sufficient permissions for this property."
  • Solution: Ensure the Google account used during the OAuth flow has at least 'Viewer' access to the Google Analytics 4 property you are trying to query. Verify that the correct scopes (e.g., https://www.googleapis.com/auth/analytics.readonly) are included in your OAuth request. Also, confirm that the Google Analytics Data API is explicitly enabled in your Google Cloud project Google Cloud API Library for Analytics Data API.
• Incorrect Property ID:
  • Issue: "Property not found" or similar errors.
  • Solution: Verify that the PROPERTY_ID in your code is the correct numeric ID of your Google Analytics 4 property. This is different from the GA4 Measurement ID (G-XXXXXXXXXX). The property ID can usually be found in the Admin section of your Google Analytics UI under Property Settings Find your GA4 Property ID.
• Invalid Date Range or Dimension/Metric:
  • Issue: "Cannot combine dimensions and metrics..." or "Invalid DateRange".
  • Solution: Refer to the API's schema documentation to ensure you are requesting valid combinations of dimensions and metrics. Check the formatting of your date ranges (e.g., "30daysAgo", "today").
• Rate Limit Exceeded (429 Error):
  • Issue: "Quota exceeded for quota metric 'requests' and limit 'requests_per_day' of service 'analyticsdata.googleapis.com'."
  • Solution: This indicates you've hit an API usage limit. Implement exponential backoff in your retry logic. Review the Google Analytics Data API quotas and limits to understand the restrictions and plan your requests accordingly.
• Client Library Installation Issues:
  • Issue: ImportError or ModuleNotFoundError.
  • Solution: Ensure all required client library packages are correctly installed (e.g., google-api-python-client, google-auth-oauthlib, google-auth-httplib2 for Python). Check your Python environment and package manager (pip).