Google Analytics 4 Analysis

Google Analytics 4 Analysis

Pull GA4 data via the Data API and turn it into actionable, prioritized recommendations. Scripts are TypeScript (run with Bun or npx tsx).

When to use

• "Give me a daily SEO report for this property" → daily-report.ts (the out-of-the-box default)
• "Review our Google Analytics performance for the last 30 days"
• "How is organic search doing?" / "Which landing pages pull organic traffic?"
• "What are our top traffic sources?"
• "Which pages have the highest bounce rates?"
• "Compare this month vs last month"
• "Why is mobile converting worse than desktop?"

When NOT to use

• Real-time / streaming analytics — this uses the batch reporting API
• Editing GA config, audiences, or events — read-only by design
• Anything needing PII / individual-user data — GA4 returns aggregates only

Setup

1. Credentials (env vars)

export GOOGLE_ANALYTICS_PROPERTY_ID="YOUR_PROPERTY_ID_HERE"   # numeric, not the G- id
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

Or copy .env.example → .env (Bun auto-loads .env; under tsx, export the vars instead). Full service-account walkthrough is inside .env.example.

Never commit the JSON key or .env. Store the key outside the repo; grant the service account only the Viewer role on the GA4 property.

2. Install the one dependency

cd skills/google-analytics/scripts
bun install            # or: npm install

The only runtime dep is @google-analytics/data (official Google client, fully typed).

Scripts

daily-report.ts — SEO daily report (out-of-the-box default) ⭐

Point it at one property and get a complete, opinionated organic-search report — zero config beyond credentials. This is the SEO-expert default template.

bun run daily-report.ts --property 123456789      # one property → one report
bun run daily-report.ts                            # uses GOOGLE_ANALYTICS_PROPERTY_ID
bun run daily-report.ts --format json --output today.json

Default template (in order): Organic KPIs (rolling 28d vs prior 28d — the Search-Console 4-week-block convention that removes day-of-week skew) · daily anomaly check (yesterday vs same weekday last week, flags drops ≥ 25%) · organic trend sparkline · top organic landing pages (the SEO money view) · by search engine · by country · by device (mobile-first) · auto-generated prioritized recommendations. Everything is filtered to sessionDefaultChannelGroup = "Organic Search".

Flags: --property <id>, --days <n> (default 28), --channel <name> (default "Organic Search"), --anomaly-threshold <pct> (default 25), --format md|json (default md), --output FILE, --help. Writes seo-daily-<date>.md by default.

It auto-detects whether the property uses GA4's conversions or the newer keyEvents metric, and any single failing sub-query degrades gracefully instead of aborting the report.

GA4 limitation: GA4 has no keyword / impression / CTR / average-position data — that lives in Google Search Console (a different API). This report covers the organic behavior GA4 owns; pair with GSC for the query side.

ga-client.ts — raw report query

Thin wrapper over runReport. Any metrics × dimensions combo.

# Last 30 days of sessions + users (JSON)
bun run ga-client.ts --days 30 --metrics sessions,users

# Top pages by views, table output
bun run ga-client.ts --days 7 --metrics screenPageViews \
  --dimensions pagePath --order-by screenPageViews --limit 20 --format table

# Specific window, filtered by country
bun run ga-client.ts --start 2026-01-01 --end 2026-01-31 \
  --metrics sessions,bounceRate --dimensions country --filter "country:United States"

Flags: --days N | --start --end (YYYY-MM-DD or NdaysAgo/yesterday), --metrics (required, comma-sep), --dimensions, --limit (default 10), --order-by (prefix - desc / + asc), --filter "field:value", --format json|table, --output FILE.

analyze.ts — higher-level analysis + recommendations

Pre-built analyses that return metrics plus prioritized recommendations.

bun run analyze.ts --analysis-type seo      --days 28   # organic-only KPIs + top landing pages
bun run analyze.ts --analysis-type overview --days 30   # current vs previous period
bun run analyze.ts --analysis-type sources  --days 30   # traffic sources + optimizations
bun run analyze.ts --analysis-type content  --days 30   # high-bounce pages + diagnosis (all channels)
bun run analyze.ts --analysis-type devices  --days 30   # mobile vs desktop gap (all channels)

--output FILE writes JSON to disk instead of stdout. --channel <name> overrides the organic channel group for the seo cut.

Which report do I actually need? For SEO, reach for daily-report.ts first and --analysis-type seo for a quick organic snapshot. overview / sources are useful general cuts. content and devices are all-channel (not organic-only) and content keys off bounceRate (a de-emphasized GA4 metric) — keep them for general GA use, but for SEO the daily report's organic-filtered device/landing cuts supersede them.

No Bun? Swap bun run X.ts → npx tsx X.ts everywhere (and export the env vars, since tsx won't read .env).