GA4 Analytics Toolkit

Setup

Install dependencies:

bash
cd scripts && npm install

Configure credentials by creating a .env file in the project root:

GA4_PROPERTY_ID=123456789
GA4_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com
GA4_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
SEARCH_CONSOLE_SITE_URL=https://your-domain.com
GA4_DEFAULT_DATE_RANGE=30d

Prerequisites: A Google Cloud project with the Analytics Data API, Search Console API, and Indexing API enabled. A service account with access to your GA4 property and Search Console.

Quick Start

| User says | Function to call | |-----------|-----------------| | "Show me site traffic for the last 30 days" | siteOverview("30d") | | "What are my top search queries?" | searchConsoleOverview("30d") | | "Who's on the site right now?" | liveSnapshot() | | "Reindex these URLs" | reindexUrls(["https://example.com/page1", ...]) | | "Compare this month vs last month" | compareDateRanges({startDate: "30daysAgo", endDate: "today"}, {startDate: "60daysAgo", endDate: "31daysAgo"}) | | "What pages get the most traffic?" | contentPerformance("30d") |

Execute functions by importing from scripts/src/index.ts:

typescript
import { siteOverview, searchConsoleOverview } from './scripts/src/index.js';

const overview = await siteOverview('30d');

Or run directly with tsx:

bash
npx tsx scripts/src/index.ts

Workflow Pattern

Every analysis follows three phases:

1. Analyze

Run API functions. Each call hits the Google APIs and returns structured data.

2. Auto-Save

All results automatically save as timestamped JSON files to results/{category}/. File naming pattern: YYYYMMDD_HHMMSS__operation__extra_info.json

3. Summarize

After analysis, read the saved JSON files and create a markdown summary in results/summaries/ with data tables, trends, and recommendations.

High-Level Functions

GA4 Analytics

| Function | Purpose | What it gathers | |----------|---------|----------------| | siteOverview(dateRange?) | Comprehensive site snapshot | Page views, traffic sources, demographics, events | | trafficAnalysis(dateRange?) | Traffic deep-dive | Sources, sessions by source/medium, new vs returning | | contentPerformance(dateRange?) | Top pages analysis | Page views, landing pages, exit pages | | userBehavior(dateRange?) | Engagement patterns | Demographics, events, daily engagement metrics | | compareDateRanges(range1, range2) | Period comparison | Side-by-side metrics for two date ranges | | liveSnapshot() | Real-time data | Active users, current pages, current events |

Search Console

| Function | Purpose | What it gathers | |----------|---------|----------------| | searchConsoleOverview(dateRange?) | SEO snapshot | Top queries, pages, device, country breakdown | | keywordAnalysis(dateRange?) | Keyword deep-dive | Queries with device breakdown | | seoPagePerformance(dateRange?) | Page SEO metrics | Top pages by clicks, country breakdown |

Indexing

| Function | Purpose | |----------|---------| | reindexUrls(urls) | Request re-indexing for multiple URLs | | checkIndexStatus(urls) | Check if URLs are indexed |

Utility

| Function | Purpose | |----------|---------| | getAvailableFields() | List all available GA4 dimensions and metrics |

Individual API Functions

For granular control, import specific functions from the API modules. See references/api-reference.md for the complete list of 30+ API functions with parameters, types, and examples.

Date Ranges

All functions accept flexible date range formats:

| Format | Example | Description | |--------|---------|-------------| | Shorthand | "7d", "30d", "90d" | Days ago to today | | Explicit | {startDate: "2024-01-01", endDate: "2024-01-31"} | Specific dates | | GA4 relative | {startDate: "30daysAgo", endDate: "today"} | GA4 relative format |

Default is "30d" (configurable via GA4_DEFAULT_DATE_RANGE in .env).

Results Storage

Results auto-save to results/ with this structure:

results/
├── reports/          # GA4 standard reports
├── realtime/         # Real-time snapshots
├── searchconsole/    # Search Console data
├── indexing/         # Indexing API results
└── summaries/        # Human-readable markdown summaries

Managing Results

typescript
import { listResults, loadResult, getLatestResult } from './scripts/src/index.js';

// List recent results
const files = listResults('reports', 10);

// Load a specific result
const data = loadResult(files[0]);

// Get most recent result for an operation
const latest = getLatestResult('reports', 'site_overview');

Common Dimensions and Metrics

Dimensions

pagePath, pageTitle, sessionSource, sessionMedium, country, deviceCategory, browser, date, eventName, landingPage, newVsReturning

Metrics

screenPageViews, activeUsers, sessions, newUsers, bounceRate, averageSessionDuration, engagementRate, conversions, totalRevenue, eventCount

Tips

1. Specify date ranges — "last 7 days" or "last 90 days" gives different insights than the default 30 days
2. Request summaries — After pulling data, ask for a markdown summary with tables and insights
3. Compare periods — Use compareDateRanges() to spot trends (this month vs last month)
4. Check real-time data — liveSnapshot() shows who's on the site right now
5. Combine GA4 + Search Console — Traffic data plus search query data gives the full picture