GA4 Analytics Toolkit
Setup
Install dependencies:
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="<your-service-account-private-key>"
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:
import { siteOverview, searchConsoleOverview } from './scripts/src/index.js';
const overview = await siteOverview('30d');
Or run directly with tsx:
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
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
- Specify date ranges — "last 7 days" or "last 90 days" gives different insights than the default 30 days
- Request summaries — After pulling data, ask for a markdown summary with tables and insights
- Compare periods — Use
compareDateRanges()to spot trends (this month vs last month) - Check real-time data —
liveSnapshot()shows who's on the site right now - Combine GA4 + Search Console — Traffic data plus search query data gives the full picture