/seo-google

name: seo-google
description: Direct access to Google's own SEO data via Search Console (Search Analytics, URL Inspection, Sitemaps), PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3, GA4 organic traffic, YouTube video search, Google NLP entity/sentiment analysis, Knowledge Graph entity verification, Web Risk safety, and Google Ads Keyword Planner. Bridges crawl-based analysis (the rest of this catalogue) with Google's real-time field data — actual Chrome user metrics, real indexation status, real search performance, real organic traffic. Use when the user asks "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", "Lighthouse scores", "youtube SEO", "knowledge graph", "keyword planner", or "real google data".

> Example output: [examples/seo-google-quickstart-20260514/README.md](../../examples/seo-google-quickstart-20260514/README.md)

Google SEO APIs

Direct access to Google's own SEO data. Bridges the gap between crawl-based analysis (the rest of the catalogue) 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 the `setup` command for step-by-step instructions, or read `references/auth-setup.md` directly.

> **Adapted from [`AgriciDaniel/claude-seo`](https://github.com/AgriciDaniel/claude-seo)'s `seo-google` skill** (MIT). Scripts, references, and command surface mirror the upstream implementation. Config path namespaced to `~/.config/seo-skills/` for clean coexistence with the original.

Prerequisites

• **Required:** Python 3.10+ and the Google API client libraries. Install via `bash extensions/google/install.sh`.
• **Required:** at minimum a Google API key (Tier 0). For full coverage, also a Google Cloud service account (Tier 1+) and optionally a GA4 property ID (Tier 2) and Google Ads developer token (Tier 3).
• Config file: `~/.config/seo-skills/google-api.json`.

Before executing any command, check credentials:

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

Config file shape (`~/.config/seo-skills/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`, `entity`, `safety` | | **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`, `ga4-referrals`, `ga4-channel-mix`, `ga4-properties` | | **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 | |---------|-------------|------| | `setup` | Check/configure API credentials | -- | | `pagespeed <url>` | PSI Lighthouse + CrUX field data | 0 | | `crux <url>` | CrUX field data only (p75 metrics) | 0 | | `crux-history <url>` | 25-week CWV trend analysis | 0 | | `gsc <property>` | Search Console: clicks, impressions, CTR, position | 1 | | `inspect <url>` | URL Inspection: index status, canonical, crawl info | 1 | | `inspect-batch <file>` | Batch URL Inspection from file | 1 | | `sitemaps <property>` | GSC sitemap status | 1 | | `index <url>` | Submit URL to Indexing API | 1 | | `index-batch <file>` | Batch submit up to 200 URLs | 1 | | `ga4 [property-id]` | GA4 organic traffic report | 2 | | `ga4-pages [property-id]` | Top organic landing pages | 2 | | `ga4-referrals [property-id]` | Referral sessions by source — AI assistants by default | 2 | | `ga4-channel-mix [property-id]` | Sessions split by channel group (Direct / Organic / Referral / Paid …) | 2 | | `ga4-properties` | List every GA4 account + property the service account can read | 2 | | `youtube <query>` | YouTube video search (views, likes, duration) | 0 | | `youtube-video <id>` | YouTube video details + top comments | 0 | | `nlp <url-or-text>` | NLP entity extraction + sentiment + classification | 0 | | `entities <url-or-text>` | Entity analysis only (for E-E-A-T) | 0 | | `keywords <seed>` | Keyword ideas from Google Ads Keyword Planner | 3 | | `volume <keywords>` | Search volume lookup from Keyword Planner | 3 | | `entity <query>` | Knowledge Graph entity check | 0 | | `safety <url>` | Web Risk URL safety check | 0 | | `quotas` | Show rate limits for all APIs | -- | | `report <type>` | Generate a PDF/HTML/XLSX report from collected JSON | -- |

---

PageSpeed + CrUX

`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.

`crux <url>`

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

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

`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

`gsc <property>`

Search Analyt