/seo-google

name: seo-google
description: >
  Google SEO APIs: Search Console (Search Analytics, URL Inspection, Sitemaps),
  PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3,
  and GA4 organic traffic. Provides real Google field data for Core Web Vitals,
  indexation status, search performance, and organic traffic trends. Use when
  user says "search console", "GSC", "PageSpeed", "CrUX", "field data",
  "indexing API", "GA4 organic", "URL inspection", "google api setup",
  "real CWV data", "impressions", "clicks", "CTR", "position data",
  "LCP", "INP", "CLS", "FCP", "TTFB", or "Lighthouse scores".
user-invokable: true
argument-hint: "[command] [url|property]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "1.9.6"
  category: seo

Google SEO APIs

Shared Data Cache

**Step 0 -- Check shared data cache:**

Before gathering, check `.seo-cache/` for reusable context from related SEO skills. Reference: `../seo/references/shared-data-cache.md` for schemas and dependency map.

Check these cache files when present:

• `.seo-cache/site-meta.json` for domain, business type, industry, and crawl context
• `.seo-cache/audit-scores.json` for prior full-audit priorities
• `.seo-cache/pages/{url-slug}/page-analysis.json` for page-level context when a URL is provided

• If found: parse and use clearly valid fields (note "Using cached [X] from [date]")
• If missing, corrupt, or irrelevant: continue with fresh evidence
• If the user says "refresh" or "re-run": ignore cache reads and overwrite on write

Direct access to Google's own SEO data. Bridges the gap between crawl-based analysis (existing codex-seo skills) and Google's real-time field data: actual Chrome user metrics, real indexation status, search performance, and organic traffic.

All APIs are free. Setup requires a Google Cloud project with API key and/or service account -- run `/seo google setup` for step-by-step instructions.

Prerequisites

Before executing any command, check credentials:

python scripts/google_auth.py --check --json

Config file: `~/.config/codex-seo/google-api.json`

{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "AIzaSy...",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

If missing, read `references/auth-setup.md` and walk the user through setup.

Credential Tiers

| Tier | Detection | Available Commands | |------|-----------|-------------------| | **0** (API Key) | `api_key` present | `pagespeed`, `crux`, `crux-history`, `youtube`, `nlp` | | **1** (OAuth/SA) | + OAuth token or service account | Tier 0 + `gsc`, `inspect`, `sitemaps`, `index` | | **2** (Full) | + `ga4_property_id` configured | Tier 1 + `ga4`, `ga4-pages` | | **3** (Ads) | + `ads_developer_token` + `ads_customer_id` | Tier 2 + `keywords`, `volume` |

Always communicate the detected tier before running commands.

Quick Reference

| Command | What it does | Tier | |---------|-------------|------| | `/seo google setup` | Check/configure API credentials | -- | | `/seo google pagespeed <url>` | PSI Lighthouse + CrUX field data | 0 | | `/seo google crux <url>` | CrUX field data only (p75 metrics) | 0 | | `/seo google crux-history <url>` | 25-week CWV trend analysis | 0 | | `/seo google gsc <property>` | Search Console: clicks, impressions, CTR, position | 1 | | `/seo google inspect <url>` | URL Inspection: index status, canonical, crawl info | 1 | | `/seo google inspect-batch <file>` | Batch URL Inspection from file | 1 | | `/seo google sitemaps <property>` | GSC sitemap status | 1 | | `/seo google index <url>` | Submit URL to Indexing API | 1 | | `/seo google index-batch <file>` | Batch submit up to 200 URLs | 1 | | `/seo google ga4 [property-id]` | GA4 organic traffic report | 2 | | `/seo google ga4-pages [property-id]` | Top organic landing pages | 2 | | `/seo google youtube <query>` | YouTube video search (views, likes, duration) | 0 | | `/seo google youtube-video <id>` | YouTube video details + top comments | 0 | | `/seo google nlp <url-or-text>` | NLP entity extraction + sentiment + classification | 0 | | `/seo google entities <url-or-text>` | Entity analysis only (for E-E-A-T) | 0 | | `/seo google keywords <seed>` | Keyword ideas from Google Ads Keyword Planner | 3 | | `/seo google volume <keywords>` | Search volume lookup from Keyword Planner | 3 | | `/seo google entity <query>` | Knowledge Graph entity check | 0 | | `/seo google safety <url>` | Web Risk URL safety check | 0 | | `/seo google quotas` | Show rate limits for all APIs | -- |

---

PageSpeed + CrUX

`/seo google pagespeed <url>`

Combined Lighthouse lab data + CrUX field data.

**Script:** `python scripts/pagespeed_check.py <url> --json` **Reference:** `references/pagespeed-crux-api.md` **Default:** Both mobile + desktop strategies, all Lighthouse categories.

Output merges lab scores (point-in-time Lighthouse) with field data (28-day Chrome user metrics). CrUX tries URL-level first, falls back to origin-level.

`/seo google crux <url>`

CrUX field data only (no Lighthouse run). Faster.

**Script:** `python scripts/pagespeed_check.py <url> --crux-only --json`

`/seo google crux-history <url>`

25-week CrUX History trends. Shows whether CWV metrics are improving, stable, or degrading.

**Script:** `python scripts/crux_history.py <url> --json` **Reference:** `references/pagespeed-crux-api.md`

Output includes per-metric trend direction, percentage change, and weekly p75 values.

---

Search Console

`/seo google gsc <property>`

Search Analytics: clicks, impressions, CTR, position for last 28 days.

**Script:** `python scripts/gsc_query.py --property <property> --json` **Reference:** `references/search-console-api.md` **Default:** 28 days, dimensions=query,page, type=web, limit=1000.

Includes quick-win detection: queries at position 4-10 with high impressions.

`/seo google inspect <url>`

URL Inspection: real indexation status