[google-analytics] initial commit for garf-google-analytics

Author: AndreyMarkinPPC

libs/garf_community/google/analytics/README.md

@@ -0,0 +1,54 @@
+# `garf` for Google Analytics API
+
+[![PyPI](https://img.shields.io/pypi/v/garf-google-analytics?logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/garf-google-analytics)
+[![Downloads PyPI](https://img.shields.io/pypi/dw/garf-google-analytics?logo=pypi)](https://pypi.org/project/garf-google-analytics/)
+
+`garf-google-analytics` simplifies fetching data from Google Analytics API using SQL-like queries.
+
+## Prerequisites
+
+* [Google Analytics API](https://console.cloud.google.com/apis/library/analytics.googleapis.com) enabled.
+
+## Installation
+
+`pip install garf-google-analytics`
+
+## Usage
+
+### Run as a library
+```
+import garf_google_analytics
+from garf_io import writer
+
+# Fetch report
+fetched_report = (
+  garf_google_analytics.GoogleAnalyticsApiReportFetcher()
+  .fetch(query, query="<YOUR_QUERY_HERE">, property_id=PROPERTY_ID)
+)
+
+# Write report to console
+console_writer = writer.create_writer('console')
+console_writer.write(fetched_report, 'output')
+```
+
+### Run via CLI
+
+> Install `garf-executors` package to run queries via CLI (`pip install garf-executors`).
+
+```
+garf <PATH_TO_QUERIES> --source google-analytics \
+  --output <OUTPUT_TYPE> \
+  --source.<SOURCE_PARAMETER=VALUE>
+```
+
+where:
+
+* `<PATH_TO_QUERIES>` - local or remove files containing queries
+* `<OUTPUT_TYPE>` - output supported by [`garf-io` library](../garf_io/README.md).
+* `<SOURCE_PARAMETER=VALUE` - key-value pairs to refine fetching, check [available source parameters](#available-source-parameters).
+
+## Available source parameters
+
+| name | values| comments |
+|----- | ----- | -------- |
+| `property_id`   | Property to get data to | Multiple properties are supported, should be comma-separated|

libs/garf_community/google/analytics/garf_google_analytics/__init__.py

@@ -0,0 +1,23 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from garf_google_analytics.api_clients import GoogleAnalyticsApiClient
+from garf_google_analytics.report_fetcher import GoogleAnalyticsApiReportFetcher
+
+__all__ = [
+  'GoogleAnalyticsApiClient',
+  'GoogleAnalyticsApiReportFetcher',
+]
+
+__version__ = '0.0.1'

libs/garf_community/google/analytics/garf_google_analytics/api_clients.py

@@ -0,0 +1,63 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Creates API client for Google Analytics API."""
+
+from collections import defaultdict
+
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import (
+  DateRange,
+  Dimension,
+  Metric,
+  RunReportRequest,
+)
+from typing_extensions import override
+
+from garf_core import api_clients, query_editor
+
+
+class GoogleAnalyticsApiClient(api_clients.BaseClient):
+  def __init__(self) -> None:
+    """Initializes GoogleAnalyticsApiClient."""
+    self._client = None
+
+  @property
+  def client(self):
+    if self._client:
+      return self._client_
+    return BetaAnalyticsDataClient()
+
+  @override
+  def get_response(
+    self, request: query_editor.BaseQueryElements, **kwargs: str
+  ) -> api_clients.GarfApiResponse:
+    property_id = kwargs.get('property_id')
+    request = RunReportRequest(
+      property=f'properties/{property_id}',
+      dimensions=[Dimension(name='country')],
+      metrics=[Metric(name='activeUsers')],
+      date_ranges=[DateRange(start_date='2020-09-01', end_date='2025-09-15')],
+    )
+    response = self.client.run_report(request)
+    results = []
+    dimension_headers = [header.name for header in response.dimension_headers]
+    metric_headers = [header.name for header in response.metric_headers]
+    for row in response.rows:
+      response_row: dict[str, dict[str, str]] = defaultdict(dict)
+      for header, value in zip(row.dimension_values, dimension_headers):
+        response_row[header] = value.value
+      for header, value in zip(row.metric_values, metric_headers):
+        response_row[header] = value.value
+      results.append(response_row)
+    return api_clients.GarfApiResponse(results=results)

libs/garf_community/google/analytics/garf_google_analytics/query_editor.py

@@ -0,0 +1,20 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Defines Google Analytics API specific query parser."""
+
+from garf_core import query_editor
+
+
+class GoogleAnalyticsApiQuery(query_editor.QuerySpecification):
+  """Query to Google Analytics API."""

libs/garf_community/google/analytics/garf_google_analytics/report_fetcher.py

@@ -0,0 +1,34 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines report fetcher for Google Analytics API."""
+
+from garf_core import parsers, report_fetcher
+from garf_google_analytics import GoogleAnalyticsApiClient, query_editor
+
+
+class GoogleAnalyticsApiReportFetcher(report_fetcher.ApiReportFetcher):
+  """Defines report fetcher."""
+
+  def __init__(
+    self,
+    api_client: GoogleAnalyticsApiClient = GoogleAnalyticsApiClient(),
+    parser: parsers.DictParser = parsers.DictParser,
+    query_spec: query_editor.GoogleAnalyticsApiQuery = (
+      query_editor.GoogleAnalyticsApiQuery
+    ),
+    **kwargs: str,
+  ) -> None:
+    """Initializes GoogleAnalyticsApiReportFetcher."""
+    super().__init__(api_client, parser, query_spec, **kwargs)

libs/garf_community/google/analytics/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "garf-google-analytics"
+dependencies = [
+  "garf-core",
+  "garf-io",
+  "google-analytics-data",
+]
+authors = [
+  {name = "Google Inc. (gTech gPS CSE team)", email = "no-reply@google.com"},
+]
+license = {text = "Apache 2.0"}
+requires-python = ">=3.8"
+description = "Garf implementation for Google Analytics API"
+readme = "README.md"
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Programming Language :: Python"
+]
+
+dynamic=["version"]
+
+[tool.setuptools.dynamic]
+version = {attr = "garf_google_analytics.__version__"}
+
+[project.entry-points.garf]
+google-analytics = "garf_google_analytics.report_fetcher"
+
+[options.extras_require]
+test =  [
+  "pytest",
+  "pytest-cov",
+  "python-dotenv",
+]