{"id":2047,"library":"google-analytics-data","title":"Google Analytics Data API Client Library","description":"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.","status":"active","version":"0.21.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-analytics-data","tags":["google-cloud","analytics","data-api","ga4","gcp"],"install":[{"cmd":"pip install google-analytics-data","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"This is the primary client for the GA4 Data API v1beta.","symbol":"BetaAnalyticsDataClient","correct":"from google.analytics.data_v1beta import BetaAnalyticsDataClient"},{"note":"Type hints for request objects are available in the .types submodule.","symbol":"RunReportRequest","correct":"from google.analytics.data_v1beta.types import RunReportRequest"}],"quickstart":{"code":"import os\nfrom google.analytics.data_v1beta import BetaAnalyticsDataClient\nfrom google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest\n\n# Replace with your Google Analytics 4 property ID.\n# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set\n# to the path of your service account key file.\nPROPERTY_ID = os.environ.get(\"GA4_PROPERTY_ID\", \"YOUR-GA4-PROPERTY-ID\")\n\ndef run_simple_report(property_id):\n    \"\"\"Runs a simple report on a Google Analytics 4 property.\"\"\"\n    client = BetaAnalyticsDataClient()\n\n    request = RunReportRequest(\n        property=f\"properties/{property_id}\",\n        dimensions=[Dimension(name=\"city\")],\n        metrics=[Metric(name=\"activeUsers\")],\n        date_ranges=[DateRange(start_date=\"7daysAgo\", end_date=\"today\")],\n    )\n\n    response = client.run_report(request)\n\n    print(f\"Report result for property: {response.property_header.property_id}\")\n    print(\"Row count: {}\".format(len(response.rows)))\n\n    print(\"\\nReport data:\")\n    for row in response.rows:\n        print(f\"{row.dimension_values[0].value}: {row.metric_values[0].value}\")\n\nif __name__ == \"__main__\":\n    if PROPERTY_ID == \"YOUR-GA4-PROPERTY-ID\":\n        print(\"Please set the 'GA4_PROPERTY_ID' environment variable or update the script.\")\n        print(\"Also ensure 'GOOGLE_APPLICATION_CREDENTIALS' is set for authentication.\")\n    else:\n        run_simple_report(PROPERTY_ID)\n","lang":"python","description":"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."},"warnings":[{"fix":"Review the official changelog and update your resource paths to `properties/{property}/audienceLists/{audience_list}` and `properties/{property}` respectively.","message":"Version 0.20.0 (January 8, 2026) introduced breaking changes to resource pattern values for `analyticsdata.googleapis.com/AudienceList` and `analyticsadmin.googleapis.com/Property`.","severity":"breaking","affected_versions":"0.20.0 and later"},{"fix":"Consult the official Google Analytics Data API changelog regarding schema changes to understand valid dimension-metric combinations.","message":"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.","severity":"breaking","affected_versions":"All versions of the client library interacting with the API after 2022-12-01"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to 3.9 or a newer supported version.","message":"This client library requires Python 3.9 or newer. Older Python versions are not supported for the latest library releases.","severity":"gotcha","affected_versions":"<0.21.0 required >=3.7, 0.21.0 and later require >=3.9"},{"fix":"Exercise caution when handling or persisting logs. Do not depend on the immutability of logging events.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}