How to Set Up Google Analytics as a Claude Code Skill

C:\Users\YourName\Downloads\your-project-name-abc123.json

pip install google-analytics-data

pip3 install google-analytics-data

---
name: google-analytics
description: Query Google Analytics 4 data. Use when the user asks about website traffic, page views, sessions, user counts, conversions, top pages, traffic sources, or any analytics/metrics questions. Trigger on keywords like "analytics", "traffic", "visitors", "page views", "sessions", "GA4", "bounce rate", "conversions", "top pages", "referrals".
---

# Google Analytics 4 Skill

Query GA4 property data using the Google Analytics Data API v1.

## Setup

- **Credentials**: Service account JSON key at `YOUR_CREDENTIALS_PATH_HERE`
- **Property ID**: `YOUR_PROPERTY_ID_HERE`
- **Python dependency**: `google-analytics-data` (install if needed: `pip install google-analytics-data`)

## How to Use

Run the query script from this skill's directory:

~~~bash
python PATH_TO_SKILL/ga_query.py --report <report_type> [options]
~~~

## Available Reports

### 1. `overview` - High-level summary
~~~bash
python ga_query.py --report overview --days 30
~~~
Returns: total users, sessions, page views, avg session duration, bounce rate, new vs returning users.

### 2. `pages` - Top pages by views
~~~bash
python ga_query.py --report pages --days 30 --limit 20
~~~
Returns: page path, title, views, users, avg engagement time.

### 3. `sources` - Traffic sources
~~~bash
python ga_query.py --report sources --days 30 --limit 20
~~~
Returns: source, medium, sessions, users, conversions.

### 4. `countries` - Geographic breakdown
~~~bash
python ga_query.py --report countries --days 30 --limit 20
~~~
Returns: country, sessions, users, engagement rate.

### 5. `devices` - Device category breakdown
~~~bash
python ga_query.py --report devices --days 30
~~~
Returns: device category (desktop/mobile/tablet), sessions, users.

### 6. `daily` - Day-by-day trend
~~~bash
python ga_query.py --report daily --days 30
~~~
Returns: date, users, sessions, page views per day.

### 7. `realtime` - Active users right now
~~~bash
python ga_query.py --report realtime
~~~
Returns: active users in last 30 minutes by source.

### 8. `custom` - Custom query (advanced)
~~~bash
python ga_query.py --report custom --metrics "sessions,totalUsers" --dimensions "city" --days 7 --limit 10
~~~
Pass any valid GA4 API metric/dimension names as comma-separated values.

## Common Options

| Option | Default | Description |
|--------|---------|-------------|
| `--days` | `30` | Lookback period in days |
| `--limit` | `10` | Max rows returned |
| `--start` | — | Explicit start date (YYYY-MM-DD), overrides --days |
| `--end` | — | Explicit end date (YYYY-MM-DD), defaults to today |
| `--output` | `table` | Output format: `table`, `json`, or `csv` |

## GA4 Metric and Dimension Reference (for custom queries)

**Common Metrics**: totalUsers, newUsers, sessions, screenPageViews, averageSessionDuration, bounceRate, engagementRate, conversions, eventCount, activeUsers

**Common Dimensions**: date, pagePath, pageTitle, sessionSource, sessionMedium, country, city, deviceCategory, browser, operatingSystem, landingPage, sessionDefaultChannelGroup

#!/usr/bin/env python3
"""
Google Analytics 4 Data API query tool.
Queries GA4 property data using a service account.
"""

import argparse
import json
import sys
import os
from datetime import datetime, timedelta

# ============================================================
# CONFIGURATION - UPDATE THESE TWO VALUES
# ============================================================
CREDENTIALS_PATH = r"C:\Users\YourName\path\to\your-credentials.json"
PROPERTY_ID = "000000000"
# ============================================================

def get_client():
    """Create and return a GA4 BetaAnalyticsDataClient."""
    os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = CREDENTIALS_PATH
    from google.analytics.data_v1beta import BetaAnalyticsDataClient
    return BetaAnalyticsDataClient()


def build_request(metrics, dimensions, days=30, start=None, end=None, limit=10, order_by_metric=None, desc=True):
    """Build a RunReportRequest."""
    from google.analytics.data_v1beta.types import (
        RunReportRequest, Metric, Dimension, DateRange, OrderBy
    )

    end_date = end or datetime.now().strftime("%Y-%m-%d")
    if start:
        start_date = start
    else:
        start_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")

    request = RunReportRequest(
        property=f"properties/{PROPERTY_ID}",
        metrics=[Metric(name=m.strip()) for m in metrics],
        dimensions=[Dimension(name=d.strip()) for d in dimensions] if dimensions else [],
        date_ranges=[DateRange(start_date=start_date, end_date=end_date)],
        limit=limit,
    )

    if order_by_metric:
        request.order_bys = [
            OrderBy(
                metric=OrderBy.MetricOrderBy(metric_name=order_by_metric),
                desc=desc,
            )
        ]

    return request


def format_response(response, output="table"):
    """Format the API response into the desired output format."""
    headers = [h.name for h in response.dimension_headers] + [h.name for h in response.metric_headers]
    rows = []
    for row in response.rows:
        values = [dv.value for dv in row.dimension_values] + [mv.value for mv in row.metric_values]
        rows.append(values)

    if output == "json":
        result = []
        for row in rows:
            result.append(dict(zip(headers, row)))
        return json.dumps(result, indent=2)

    elif output == "csv":
        lines = [",".join(headers)]
        for row in rows:
            lines.append(",".join(row))
        return "\n".join(lines)

    else:  # table
        col_widths = [len(h) for h in headers]
        for row in rows:
            for i, val in enumerate(row):
                col_widths[i] = max(col_widths[i], len(str(val)))

        separator = "+" + "+".join("-" * (w + 2) for w in col_widths) + "+"
        header_row = "|" + "|".join(f" {h:<{col_widths[i]}} " for i, h in enumerate(headers)) + "|"

        lines = [separator, header_row, separator]
        for row in rows:
            line = "|" + "|".join(f" {str(v):<{col_widths[i]}} " for i, v in enumerate(row)) + "|"
            lines.append(line)
        lines.append(separator)

        if response.row_count:
            lines.append(f"\nTotal rows: {response.row_count}")

        return "\n".join(lines)


def report_overview(client, args):
    """High-level site overview."""
    request = build_request(
        metrics=["totalUsers", "newUsers", "sessions", "screenPageViews",
                 "averageSessionDuration", "engagementRate", "bounceRate"],
        dimensions=[],
        days=args.days, start=args.start, end=args.end, limit=1,
    )
    response = client.run_report(request)
    return format_response(response, args.output)


def report_pages(client, args):
    """Top pages by views."""
    request = build_request(
        metrics=["screenPageViews", "totalUsers", "averageSessionDuration"],
        dimensions=["pagePath", "pageTitle"],
        days=args.days, start=args.start, end=args.end, limit=args.limit,
        order_by_metric="screenPageViews",
    )
    response = client.run_report(request)
    return format_response(response, args.output)


def report_sources(client, args):
    """Traffic sources."""
    request = build_request(
        metrics=["sessions", "totalUsers", "engagementRate", "conversions"],
        dimensions=["sessionSource", "sessionMedium"],
        days=args.days, start=args.start, end=args.end, limit=args.limit,
        order_by_metric="sessions",
    )
    response = client.run_report(request)
    return format_response(response, args.output)


def report_countries(client, args):
    """Geographic breakdown."""
    request = build_request(
        metrics=["sessions", "totalUsers", "engagementRate"],
        dimensions=["country"],
        days=args.days, start=args.start, end=args.end, limit=args.limit,
        order_by_metric="sessions",
    )
    response = client.run_report(request)
    return format_response(response, args.output)


def report_devices(client, args):
    """Device category breakdown."""
    request = build_request(
        metrics=["sessions", "totalUsers", "engagementRate"],
        dimensions=["deviceCategory"],
        days=args.days, start=args.start, end=args.end, limit=args.limit,
        order_by_metric="sessions",
    )
    response = client.run_report(request)
    return format_response(response, args.output)


def report_daily(client, args):
    """Day-by-day trend."""
    request = build_request(
        metrics=["totalUsers", "sessions", "screenPageViews"],
        dimensions=["date"],
        days=args.days, start=args.start, end=args.end, limit=args.days or 30,
    )
    from google.analytics.data_v1beta.types import OrderBy
    request.order_bys = [
        OrderBy(dimension=OrderBy.DimensionOrderBy(dimension_name="date"), desc=False)
    ]
    response = client.run_report(request)
    return format_response(response, args.output)


def report_realtime(client, args):
    """Realtime active users."""
    from google.analytics.data_v1beta.types import (
        RunRealtimeReportRequest, Metric, Dimension
    )
    request = RunRealtimeReportRequest(
        property=f"properties/{PROPERTY_ID}",
        metrics=[Metric(name="activeUsers")],
        dimensions=[Dimension(name="unifiedScreenName")],
        limit=args.limit,
    )
    response = client.run_realtime_report(request)

    headers = [h.name for h in response.dimension_headers] + [h.name for h in response.metric_headers]
    rows = []
    for row in response.rows:
        values = [dv.value for dv in row.dimension_values] + [mv.value for mv in row.metric_values]
        rows.append(values)

    if not rows:
        return "No active users right now."

    if args.output == "json":
        result = [dict(zip(headers, row)) for row in rows]
        return json.dumps(result, indent=2)
    elif args.output == "csv":
        lines = [",".join(headers)]
        for row in rows:
            lines.append(",".join(row))
        return "\n".join(lines)
    else:
        col_widths = [len(h) for h in headers]
        for row in rows:
            for i, val in enumerate(row):
                col_widths[i] = max(col_widths[i], len(str(val)))
        separator = "+" + "+".join("-" * (w + 2) for w in col_widths) + "+"
        header_row = "|" + "|".join(f" {h:<{col_widths[i]}} " for i, h in enumerate(headers)) + "|"
        lines = [separator, header_row, separator]
        for row in rows:
            line = "|" + "|".join(f" {str(v):<{col_widths[i]}} " for i, v in enumerate(row)) + "|"
            lines.append(line)
        lines.append(separator)
        return "\n".join(lines)


def report_custom(client, args):
    """Custom query with user-specified metrics and dimensions."""
    if not args.metrics:
        return "Error: --metrics required for custom report (comma-separated)"

    metrics = [m.strip() for m in args.metrics.split(",")]
    dimensions = [d.strip() for d in args.dimensions.split(",")] if args.dimensions else []

    request = build_request(
        metrics=metrics,
        dimensions=dimensions,
        days=args.days, start=args.start, end=args.end, limit=args.limit,
        order_by_metric=metrics[0],
    )
    response = client.run_report(request)
    return format_response(response, args.output)


REPORTS = {
    "overview": report_overview,
    "pages": report_pages,
    "sources": report_sources,
    "countries": report_countries,
    "devices": report_devices,
    "daily": report_daily,
    "realtime": report_realtime,
    "custom": report_custom,
}


def main():
    parser = argparse.ArgumentParser(description="Query Google Analytics 4 data")
    parser.add_argument("--report", required=True, choices=REPORTS.keys(), help="Report type")
    parser.add_argument("--days", type=int, default=30, help="Lookback period in days (default: 30)")
    parser.add_argument("--start", help="Start date (YYYY-MM-DD), overrides --days")
    parser.add_argument("--end", help="End date (YYYY-MM-DD), defaults to today")
    parser.add_argument("--limit", type=int, default=10, help="Max rows (default: 10)")
    parser.add_argument("--output", choices=["table", "json", "csv"], default="table", help="Output format")
    parser.add_argument("--metrics", help="Comma-separated metrics (for custom report)")
    parser.add_argument("--dimensions", help="Comma-separated dimensions (for custom report)")

    args = parser.parse_args()

    try:
        client = get_client()
        result = REPORTS[args.report](client, args)
        print(result)
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

google-analytics-data>=0.18.0

.claude/
  skills/
    google-analytics/
      SKILL.md
      ga_query.py
      requirements.txt

C:\Users\YourName\.claude\skills\google-analytics\SKILL.md
C:\Users\YourName\.claude\skills\google-analytics\ga_query.py
C:\Users\YourName\.claude\skills\google-analytics\requirements.txt

   cd C:\Users\YourName\.claude\skills\google-analytics

   python ga_query.py --report overview --days 7