Skip to content

thatrebeccarae/claude-marketing / skills/google-analytics

google-analytics

Verified

Analyze Google Analytics data, review website performance metrics, identify traffic patterns, and suggest data-driven improvements. Use when the user asks about analytics, website metrics, traffic analysis, conversion rates, user behavior, or performance optimization.

FileKindSize
.env.exampleother1.1 KB
EXAMPLES.mdmarkdown13.5 KB
LICENSEother1.0 KB
REFERENCE.mdmarkdown8.6 KB
SKILL.mdskill md5.0 KB
requirements.txtmanifest152 B
scripts/analyze.pyexecutablescript16.0 KB
scripts/ga_client.pyexecutablescript11.6 KB

scripts/ga_client.py

View on GitHub
#!/usr/bin/env python3
"""
Google Analytics 4 Data API Client

Fetches analytics data from Google Analytics 4 using the Data API.
Authentication uses service account credentials from environment variables.

Usage:
    python ga_client.py --days 30 --metrics sessions,users
    python ga_client.py --start 2026-01-01 --end 2026-01-31 --dimensions country
    python ga_client.py --days 7 --metrics sessions --dimensions pagePath --limit 10

Environment Variables:
    GOOGLE_ANALYTICS_PROPERTY_ID: GA4 property ID (required)
    GOOGLE_APPLICATION_CREDENTIALS: Path to service account JSON (required)
"""

import os
import sys
import json
import argparse
from datetime import datetime, timedelta
from typing import List, Dict, Optional

try:
    from google.analytics.data_v1beta import BetaAnalyticsDataClient
    from google.analytics.data_v1beta.types import (
        DateRange,
        Dimension,
        Metric,
        RunReportRequest,
        OrderBy,
        FilterExpression,
        Filter,
    )
    from dotenv import load_dotenv
except ImportError as e:
    print("Error: Required packages not installed.", file=sys.stderr)
    print("Install with: pip install google-analytics-data python-dotenv", file=sys.stderr)
    sys.exit(1)


def _safe_output_path(path: str) -> str:
    """Validate output path does not escape working directory."""
    resolved = os.path.realpath(path)
    cwd = os.path.realpath(os.getcwd())
    if not resolved.startswith(cwd + os.sep) and resolved != cwd:
        raise ValueError(f"Output path must be within working directory: {cwd}")
    return resolved


class GoogleAnalyticsClient:
    """Client for interacting with Google Analytics 4 Data API."""

    def __init__(self):
        """Initialize the client with credentials from environment."""
        load_dotenv()  # Load from .env file if present

        self.property_id = os.environ.get("GOOGLE_ANALYTICS_PROPERTY_ID")
        if not self.property_id:
            raise ValueError(
                "GOOGLE_ANALYTICS_PROPERTY_ID environment variable not set. "
                "Find your property ID in GA4: Admin > Property Settings"
            )

        credentials_path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
        if not credentials_path:
            raise ValueError(
                "GOOGLE_APPLICATION_CREDENTIALS environment variable not set. "
                "Set it to the path of your service account JSON file."
            )

        if not os.path.exists(credentials_path):
            raise FileNotFoundError(
                f"Service account file not found: {credentials_path}"
            )

        try:
            self.client = BetaAnalyticsDataClient()
        except Exception as e:
            raise RuntimeError(
                "Failed to initialize Google Analytics client. Verify your service account has access to the GA4 property."
            )

    def run_report(
        self,
        start_date: str,
        end_date: str,
        metrics: List[str],
        dimensions: Optional[List[str]] = None,
        limit: int = 10,
        order_by: Optional[str] = None,
        filter_expression: Optional[str] = None,
    ) -> Dict:
        """
        Run a report query against Google Analytics.

        Args:
            start_date: Start date (YYYY-MM-DD or 'NdaysAgo')
            end_date: End date (YYYY-MM-DD or 'today'/'yesterday')
            metrics: List of metric names (e.g., ['sessions', 'users'])
            dimensions: List of dimension names (e.g., ['country', 'city'])
            limit: Maximum number of rows to return
            order_by: Metric or dimension to sort by
            filter_expression: Filter to apply (dimension_name:value)

        Returns:
            Dictionary with report data and metadata
        """
        # Build request
        request = RunReportRequest(
            property=f"properties/{self.property_id}",
            date_ranges=[DateRange(start_date=start_date, end_date=end_date)],
            metrics=[Metric(name=m) for m in metrics],
            dimensions=[Dimension(name=d) for d in (dimensions or [])],
            limit=limit,
        )

        # Add ordering
        if order_by:
            desc = True
            if order_by.startswith("+"):
                desc = False
                order_by = order_by[1:]
            elif order_by.startswith("-"):
                order_by = order_by[1:]

            # Check if it's a metric or dimension
            if order_by in metrics:
                request.order_bys = [
                    OrderBy(metric=OrderBy.MetricOrderBy(metric_name=order_by), desc=desc)
                ]
            elif dimensions and order_by in dimensions:
                request.order_bys = [
                    OrderBy(
                        dimension=OrderBy.DimensionOrderBy(dimension_name=order_by),
                        desc=desc,
                    )
                ]

        # Add filter
        if filter_expression and ":" in filter_expression:
            field_name, value = filter_expression.split(":", 1)
            request.dimension_filter = FilterExpression(
                filter=Filter(
                    field_name=field_name,
                    string_filter=Filter.StringFilter(value=value),
                )
            )

        try:
            response = self.client.run_report(request)
        except Exception as e:
            raise RuntimeError("Failed to run report. Check property ID and service account permissions.")

        # Parse response
        return self._parse_response(response)

    def _parse_response(self, response) -> Dict:
        """Parse API response into a structured dictionary."""
        result = {
            "dimension_headers": [h.name for h in response.dimension_headers],
            "metric_headers": [
                {"name": h.name, "type": h.type_.name} for h in response.metric_headers
            ],
            "rows": [],
            "row_count": response.row_count,
            "metadata": {},
        }

        # Add totals if present
        if response.totals:
            result["totals"] = [
                {"value": v.value} for v in response.totals[0].metric_values
            ]

        # Parse rows
        for row in response.rows:
            parsed_row = {
                "dimensions": {},
                "metrics": {},
            }

            # Dimension values
            for i, value in enumerate(row.dimension_values):
                dim_name = result["dimension_headers"][i]
                parsed_row["dimensions"][dim_name] = value.value

            # Metric values
            for i, value in enumerate(row.metric_values):
                metric_info = result["metric_headers"][i]
                metric_name = metric_info["name"]
                parsed_row["metrics"][metric_name] = value.value

            result["rows"].append(parsed_row)

        return result


def parse_date_range(days: Optional[int], start: Optional[str], end: Optional[str]):
    """Parse date range arguments into start and end dates."""
    if days:
        return f"{days}daysAgo", "yesterday"
    elif start and end:
        return start, end
    else:
        # Default to last 7 days
        return "7daysAgo", "yesterday"


def main():
    parser = argparse.ArgumentParser(
        description="Fetch Google Analytics 4 data",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Last 30 days of sessions and users
  python ga_client.py --days 30 --metrics sessions,users

  # Specific date range with dimensions
  python ga_client.py --start 2026-01-01 --end 2026-01-31 \\
      --metrics sessions,bounceRate --dimensions country,city

  # Top pages by views
  python ga_client.py --days 7 --metrics screenPageViews \\
      --dimensions pagePath --order-by screenPageViews --limit 20

  # Filter by country
  python ga_client.py --days 30 --metrics sessions \\
      --dimensions country --filter "country:United States"
        """,
    )

    # Date range arguments
    date_group = parser.add_mutually_exclusive_group()
    date_group.add_argument(
        "--days", type=int, help="Number of days to look back (e.g., 30)"
    )
    date_group.add_argument(
        "--start", help="Start date (YYYY-MM-DD or 'NdaysAgo')"
    )
    parser.add_argument("--end", help="End date (YYYY-MM-DD or 'today'/'yesterday')")

    # Query arguments
    parser.add_argument(
        "--metrics",
        required=True,
        help="Comma-separated list of metrics (e.g., sessions,users,bounceRate)",
    )
    parser.add_argument(
        "--dimensions",
        help="Comma-separated list of dimensions (e.g., country,city,deviceCategory)",
    )
    parser.add_argument(
        "--limit", type=int, default=10, help="Maximum rows to return (default: 10)"
    )
    parser.add_argument(
        "--order-by",
        help="Metric or dimension to sort by (prefix with - for desc, + for asc)",
    )
    parser.add_argument(
        "--filter", help="Filter expression (e.g., 'country:United States')"
    )

    # Output arguments
    parser.add_argument(
        "--format",
        choices=["json", "table"],
        default="json",
        help="Output format (default: json)",
    )
    parser.add_argument(
        "--output", help="Output file path (default: stdout)"
    )

    args = parser.parse_args()

    try:
        # Initialize client
        client = GoogleAnalyticsClient()

        # Parse date range
        start_date, end_date = parse_date_range(args.days, args.start, args.end)

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

        # Run report
        result = client.run_report(
            start_date=start_date,
            end_date=end_date,
            metrics=metrics,
            dimensions=dimensions,
            limit=args.limit,
            order_by=args.order_by,
            filter_expression=args.filter,
        )

        # Format output
        if args.format == "json":
            output = json.dumps(result, indent=2)
        else:  # table format
            output = format_as_table(result)

        # Write output
        if args.output:
            safe_path = _safe_output_path(args.output)
            with open(safe_path, "w", encoding="utf-8") as f:
                f.write(output)
            print(f"Report saved to {args.output}", file=sys.stderr)
        else:
            print(output)

    except ValueError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    except Exception:
        print("Error: Failed to run report. Check credentials and property ID.", file=sys.stderr)
        sys.exit(1)


def format_as_table(result: Dict) -> str:
    """Format result as a human-readable table."""
    lines = []

    # Header
    headers = result["dimension_headers"] + [m["name"] for m in result["metric_headers"]]
    lines.append(" | ".join(headers))
    lines.append("-" * (len(" | ".join(headers))))

    # Rows
    for row in result["rows"]:
        values = []
        for dim in result["dimension_headers"]:
            values.append(row["dimensions"].get(dim, ""))
        for metric in result["metric_headers"]:
            values.append(row["metrics"].get(metric["name"], ""))
        lines.append(" | ".join(values))

    # Totals
    if "totals" in result:
        lines.append("-" * (len(" | ".join(headers))))
        total_values = ["TOTAL"] + [""] * (len(result["dimension_headers"]) - 1)
        total_values += [t["value"] for t in result["totals"]]
        lines.append(" | ".join(total_values))

    lines.append("")
    lines.append(f"Total rows: {result['row_count']}")

    return "\n".join(lines)


if __name__ == "__main__":
    main()
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall