/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", or "real CWV data".
user-invocable: true
argument-hint: "[command] [url|property]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.6.0"
  category: seo

Google SEO APIs

Direct access to Google's own SEO data. Bridges the gap between crawl-based analysis (existing claude-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:

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run google_auth.py --check --json

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

{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "<GOOGLE_API_KEY>",
  "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:** `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run pagespeed_check.py <url> --json` **Reference:** `references/pagespeed-crux-api.md` (Core Web Vitals thresholds: `references/crux-history-api.md`) **Report the Lighthouse build** from the output's `lighthouse_version` field instead of assuming the latest release. **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:** `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run 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:** `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run crux_history.py <url> --json` **Reference:** `references/crux-history-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:** `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run gsc_query.py --property <property> --json` **Site URL or host instead of a property** (every site audit): `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run gsc_query.py --domain <audited-domain> --json` **Which flag:** a GSC property (`sc-domain:example.com`, or a URL-prefix property the user named as such) goes to `--property`; a site URL or host goes to `--domain`, which looks up that site's property and refuses another site's. Never pass a property to `--domain` or leave either flag empty. With neither flag the script names the default property on stderr, or exits if a `sites` mapping is configured (`references/auth-setup.md`). **Reference:** `references/search-console-api.md` **Default:** 28 days, dimensions=query,page, type=web, limit=1000.

For EU sites, read `references/dma-consent-mode-v2.md` before interpreting CTR or GA4 drops: