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
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](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