{"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":"python","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,"search_vec":"'4':24 'access':18 'activ':30 'analyt':2,9,23,52 'api':4,11,55 'break':47 'chang':48 'client':5,12 'cloud':51 'data':3,10,20,54 'data-api':53 'ecosystem':36 'featur':44 'frequent':38 'ga4':25,56 'gcp':57 'googl':1,8,22,50 'google-cloud':49 'googleapis/google-cloud-python':35 'includ':42 'librari':6,13,32 'maintain':31 'may':41 'method':16 'new':43 'occasion':46 'programmat':15 'properti':26 'provid':14 'report':19 'updat':39 'within':33","created_at":"2026-04-09T18:41:15.014050+00:00","updated_at":"2026-04-16T15:18:25.264693+00:00","problems":[{"fix":"Install the library using `pip install google-analytics-data` or ensure the correct virtual environment is activated.","cause":"The `google-analytics-data` library or its specific sub-modules are not installed, or the Python environment where the code is executed cannot access them.","error":"ModuleNotFoundError: No module named 'google.analytics.data_v1beta'"},{"fix":"Re-authenticate to obtain a new, valid refresh token; for service accounts, ensure the key file is valid and not expired, and if necessary, generate a new service account key.","cause":"This error signifies an authentication failure, commonly due to an expired refresh token, an incorrect JSON Web Token (JWT) signature, or exceeding the OAuth 2.0 client's refresh token limit.","error":"invalid_grant"},{"fix":"Implement exponential backoff for retrying API calls, reduce the volume or complexity of requests, or consider upgrading to Google Analytics 360 for increased quota limits if your project requires higher usage.","cause":"The application has surpassed the allowable number of requests to the Google Analytics Data API within a specified time period (e.g., hourly or daily), triggering the API's rate limits.","error":"Quota exceeded"},{"fix":"Upgrade the `google-auth` library to its latest version using `pip install --upgrade google-auth` to resolve the attribute discrepancy.","cause":"This issue typically occurs due to an incompatibility between the installed `google-analytics-data` library and an older version of the `google-auth` library, which is a dependency.","error":"AttributeError: 'Credentials' object has no attribute 'universe_domain'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.23.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/googleapis/google-cloud-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/google-analytics-data/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}