SEO Google

Example output: 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'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

Always communicate the detected tier before running commands.

Quick Reference

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

Filtering: --device {desktop,mobile,tablet}, --country <ISO3>, --page <url-or-substring> (defaults to contains match; pass --page-match equals for exact-URL match). Combine for per-URL query analysis: --page /blog/best-ai-seo-tools/ --dimensions query.

AI Overview / AI Mode: --ai-overview (or --ai-mode) filters results to queries where Google rendered an AI Overview / AI Mode SERP that included one of your URLs. This is Google's first-party answer to "are we cited in AI Overview?" — clicks, impressions, CTR, and avg position straight from GSC. Combine with --dimensions query,page to see which queries+pages earned AI Overview presence, or with --page /post/ to scope to one URL. For other appearance types (RICH_RESULT, REVIEW_SNIPPET, etc.) use --search-appearance <value>.

inspect <url>

URL Inspection: real indexation status from Google.

Script: python scripts/gsc_inspect.py <url> --json

Returns: verdict (PASS/FAIL), coverage state, robots.txt status, indexing state, page fetch state, canonical selection, mobile usability, rich results.

inspect-batch <file>

Batch inspection from a file (one URL per line). Rate limited to 2,000/day per site.

Script: python scripts/gsc_inspect.py --batch <file> --json

sitemaps <property>

List submitted sitemaps with status, errors, warnings.

Script: python scripts/gsc_query.py sitemaps --property <property> --json

Indexing API

index <url>

Notify Google of a URL update.

Script: python scripts/indexing_notify.py <url> --json Reference: references/indexing-api.md

The Indexing API is officially for JobPosting and BroadcastEvent/VideoObject pages. Always inform the user of this restriction. Daily quota: 200 publish requests.

index-batch <file>

Batch submit URLs from a file. Tracks quota usage.

Script: python scripts/indexing_notify.py --batch <file> --json

GA4 Traffic

All GA4 reports accept an optional --page <path-or-url> flag to scope the report to a single landing page (EXACT match against GA4's landingPage dimension; full URLs are auto-stripped to path). Use it whenever the question is "how is this post performing?" rather than site-wide.

--report organic and --report top-pages accept --channel <name|all>: defaults to organic (Organic Search), pass all to drop the channel filter (required for whole-page weekly trends across all traffic sources), or any GA4 default channel group verbatim — Direct, Referral, Paid Search, Organic Social, etc.

ga4 [property-id]

Daily-time-series traffic report: sessions, users, pageviews, bounce rate, engagement.

Script: python scripts/ga4_report.py --property <id> --json Reference: references/ga4-data-api.md Default: 28 days, filtered to Organic Search channel group. Pass --channel all for unfiltered traffic.

The all-channels variant is what answers "how is this post growing week over week?" when most of the traffic is Direct or Referral rather than Organic — the canonical case for AI-cited content. Example: --report organic --page /blog/best-ai-seo-tools/ --channel all --days 99.

ga4-pages [property-id]

Top landing pages ranked by sessions for the chosen channel (default Organic Search; use --channel all for site-wide top pages across every source).

Script: python scripts/ga4_report.py --property <id> --report top-pages --json

ga4-referrals [property-id]

Referral sessions broken down by sessionSource. Defaults to a curated AI-assistant hostname list — OpenAI (chatgpt.com, chat.openai.com), Anthropic (claude.ai), Google (gemini.google.com, bard.google.com), Microsoft (copilot.microsoft.com), Perplexity (perplexity.ai), Alibaba/Qwen (chat.qwen.ai, qwen.com, tongyi.aliyun.com), Mistral (chat.mistral.ai), DeepSeek (chat.deepseek.com), xAI/Grok (grok.com, x.ai), plus you.com / phind.com / poe.com — so the "how much traffic do AI assistants actually send us?" question is one command. Use this as a reality check against AI-visibility data from seo-ai-search-share-of-voice and seo-geo — referral volume measures users sharing your links in AI chats, not whether the AI proactively cites you.

Script: python scripts/ga4_report.py --property <id> --report referrals --json

Source modes (--sources):

• ai (default) — curated AI-assistant hostname list
• all — every source in the Referral channel group
• chatgpt.com,perplexity.ai,... — explicit comma-separated list

Combine with --page to answer "how much AI traffic did THIS specific post get?": --report referrals --page /blog/best-ai-seo-tools/.

ga4-channel-mix [property-id]

Sessions broken down by sessionDefaultChannelGroup (Direct / Organic Search / Referral / Paid Search / Organic Social / …). No channel filter — this is the diagnostic view for "where does traffic to this page actually come from?". Each row includes a share_of_sessions percentage so the mix is visible at a glance.

Script: python scripts/ga4_report.py --property <id> --report channel-mix --json

This is the report that answers questions like "is this post mostly winning on organic, or is the traffic coming from somewhere else?". AI-assistant traffic frequently lands in Direct (uncredited) rather than Referral, so a high Direct share on a recent content-heavy page is itself an AI-visibility signal — pair with ga4-referrals for a fuller picture.

Per-page diagnosis: --report channel-mix --page /blog/best-ai-seo-tools/ --days 90.