What Is the GA4 Data API? Examples and Use Cases

Ga4 data api

RESTful HTTP interface to programmatically access GA4 analytics data for custom dashboards, automation, and BI integration.

Understanding the GA4 Data API

• Definition and purpose

  The GA4 Data API provides programmatic access to your GA4 property’s analytics data, enabling custom queries for metrics and dimensions beyond the GA4 UI.

• Key use cases

  Common scenarios where the Data API adds value: building custom dashboards, automating periodic reports, and ingesting data into analytics warehouses.

  • Custom dashboards:

    Feed real-time or scheduled analytics data into bespoke BI tools to visualize metrics your way.

  • Automated reporting:

    Create scripts that pull data automatically at set intervals and distribute reports via email or internal portals.

  • Data warehouse ingestion:

    Load granular event and user data into BigQuery or other databases for advanced analytics and machine learning.

Key Features and Capabilities

• Real-time and historical data access

  Query both real-time and past events, dimensions, and metrics programmatically for in-depth analysis.

• Cohort and funnel analysis

  Use API parameters to define cohorts and funnels, facilitating user segmentation and behavior flow analysis.

• Custom dimensions and metrics

  Retrieve custom dimensions and metrics defined in your GA4 property, enabling tailored data collection.

• Pagination, filtering, and sorting

  Control data volume and ordering with page tokens, dimension filters, metric filters, and sort options.

Authentication and Setup

• Enabling the api

  Activate the GA4 Data API in the Google Cloud Console under APIs & Services for your project.

• Oauth 2.0 and service accounts

  Authenticate using OAuth 2.0 for user-level access or service accounts for server-to-server requests.

• Setting permissions

  Grant the appropriate Analytics Viewer role to your service account or OAuth client to read data from the GA4 property.

Making API Requests

• Endpoint structure

  Requests are sent to https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runReport endpoint with a JSON payload.

• Request parameters

  Specify dimensions, metrics, date ranges, filters, and pagination in the request body to customize your report.

• Parsing responses

  The API returns JSON with rows of dimension and metric values; parse and map these to your analytics models.

• Error handling and quotas

  Implement retries for rate-limit errors and respect daily quotas to avoid 429 responses or denied requests.

Example: Dual Tracking with GA4 and Plainsignal

• Adding plainsignal snippet

  Insert the following PlainSignal tracking code into your HTML to collect privacy-focused analytics.

  • Plainsignal tracking code:

    <link rel="preconnect" href="//eu.plainsignal.com/" crossorigin />
    <script defer data-do="yourwebsitedomain.com" data-id="0GQV1xmtzQQ" data-api="//eu.plainsignal.com" src="//cdn.plainsignal.com/PlainSignal-min.js"></script>
    

• Adding ga4 gtag.js snippet

  Add the standard GA4 gtag.js code to enable GA4 tracking on your site.

  • Ga4 gtag.js code:

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'GA_MEASUREMENT_ID');
    </script>
    

• Fetching data with the ga4 data api

  Use the following Python snippet to request a report from the GA4 Data API.

  • Python example:

    from google.analytics.data_v1beta import BetaAnalyticsDataClient
    from google.analytics.data_v1beta.types import RunReportRequest
    
    client = BetaAnalyticsDataClient()
    request = RunReportRequest(
        property='properties/123456789',
        dimensions=[{'name': 'city'}],
        metrics=[{'name': 'activeUsers'}],
        date_ranges=[{'start_date': '7daysAgo', 'end_date': 'today'}]
    )
    response = client.run_report(request)
    for row in response.rows:
        print({dim.value: met.value for dim, met in zip(row.dimension_values, row.metric_values)})
    

Best Practices and Considerations

• Optimize query granularity

  Request only the dimensions and metrics you need to reduce payload size and speed up responses.

• Handle sampling and guards

  Be aware that high-cardinality queries may be sampled; adjust your filters to minimize sampling.

• Respect rate limits

  Implement exponential backoff for 429 errors and monitor quota usage in the Google Cloud Console.

• Secure credentials

  Keep service account keys safe, rotate them periodically, and use principle of least privilege.

Related terms