GA4 Analytics

# 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 [email protected] 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](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