Seo Google

> 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'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 | PSI Lighthouse + CrUX field data | 0 | | crux | CrUX field data only (p75 metrics) | 0 | | crux-history | 25-week CWV trend analysis | 0 | | gsc | Search Console: clicks, impressions, CTR, position | 1 | | inspect | URL Inspection: index status, canonical, crawl info | 1 | | inspect-batch | Batch URL Inspection from file | 1 | | sitemaps | GSC sitemap status | 1 | | index | Submit URL to Indexing API | 1 | | index-batch | 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 | YouTube video search (views, likes, duration) | 0 | | youtube-video | YouTube video details + top comments | 0 | | nlp | NLP entity extraction + sentiment + classification | 0 | | entities | Entity analysis only (for E-E-A-T) | 0 | | keywords | Keyword ideas from Google Ads Keyword Planner | 3 | | volume | Search volume lookup from Keyword Planner | 3 | | entity | Knowledge Graph entity check | 0 | | safety | Web Risk URL safety check | 0 | | quotas | Show rate limits for all APIs | -- | | report | Generate a PDF/HTML/XLSX report from collected JSON | -- |

---

PageSpeed + CrUX

pagespeed

Combined Lighthouse lab data + CrUX field data.

Script: python scripts/pagespeed_check.py --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

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

Script: python scripts/pagespeed_check.py --crux-only --json

crux-history

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

Script: python scripts/crux_history.py --json Reference: references/pagespeed-crux-api.md

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

---

Search Console

gsc

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

Script: python scripts/gsc_query.py --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 , --page (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 .

inspect

URL Inspection: real indexation status from Google.

Script: python scripts/gsc_inspect.py --json

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

inspect-batch

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

Script: python scripts/gsc_inspect.py --batch --json

sitemaps

List submitted sitemaps with status, errors, warnings.

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

---

Indexing API

index

Notify Google of a URL update.

Script: python scripts/indexing_notify.py --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

Batch submit URLs from a file. Tracks quota usage.

Script: python scripts/indexing_notify.py --batch --json

---

GA4 Traffic

All GA4 reports accept an optional --page 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 : 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 --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 --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 --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 --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.

ga4-properties

Enumerates every GA4 account and property the service account can read. Use this before running ga4 / ga4-pages / ga4-referrals / ga4-channel-mix when the client has multiple GA4 properties (typical: separate marketing-site and app properties, or per-region properties) and you need to know which property_id to query. Output groups properties by parent account; the property_id field is the numeric value to pass as --property.

Script: python scripts/ga4_admin.py properties --json

Requires the Google Analytics Admin API to be enabled in your Cloud project (separate from the Data API) and the service account to have Viewer access on at least one property.

---

YouTube (Video SEO)

YouTube mentions have the strongest AI visibility correlation (0.737). Free, API key only.

youtube

Search YouTube for videos. Returns title, channel, views, likes, duration.

Script: python scripts/youtube_search.py search "" --json Reference: references/youtube-api.md Quota: 100 units per search (10,000 units/day free).

youtube-video

Detailed video info + tags + top 10 comments.

Script: python scripts/youtube_search.py video --json Quota: 2 units (video details + comments).

---

NLP Content Analysis

Google's own entity/sentiment analysis. Enhances E-E-A-T scoring.

nlp

Full NLP analysis: entities, sentiment, content classification.

Script: python scripts/nlp_analyze.py --url --json or --text "..." Reference: references/nlp-api.md Free tier: 5,000 units/month. Requires billing enabled on GCP project.

entities

Entity extraction only (faster, less quota).

Script: python scripts/nlp_analyze.py --url --features entities --json

---

Keyword Research (Google Ads)

Gold-standard keyword volume data. Requires Google Ads account.

keywords

Generate keyword ideas from seed terms.

Script: python scripts/keyword_planner.py ideas "" --json Reference: references/keyword-planner-api.md Requires: Ads developer token + customer ID in config (Tier 3).

volume

Search volume for specific keywords (comma-separated).

Script: python scripts/keyword_planner.py volume "," --json

---

Supplementary

entity

Knowledge Graph entity check. Verifies brand presence.

Reference: references/supplementary-apis.md Uses Knowledge Graph Search API with API key.

safety

Web Risk API check for malware/social engineering flags.

Reference: references/supplementary-apis.md

quotas

Display rate limits table. Read references/rate-limits-quotas.md.

---

Reports

After any analysis command, offer to generate a PDF/HTML/XLSX report.

report

Generate a professional PDF/HTML/XLSX report with charts and analytics.

Script: python scripts/google_report.py --type --data --domain --format pdf

| Type | Input | Output | |------|-------|--------| | cwv-audit | PSI + CrUX + CrUX History data | Core Web Vitals audit with gauges, timelines, distributions | | gsc-performance | GSC query data | Search Console report with query tables, quick wins | | indexation | Batch inspection data | Indexation status with coverage donut chart | | full | All data combined | Comprehensive Google SEO report (all sections) |

Workflow:

1. Run data collection commands (pagespeed, gsc, inspect-batch, etc.)
2. Save JSON output to file: python scripts/pagespeed_check.py --json > data.json
3. Generate report: python scripts/google_report.py --type cwv-audit --data data.json --domain

Convention: After completing analysis, suggest: "Generate a report? Use report ."

---

Rate Limits

| API | Per-Minute | Per-Day | Auth | |-----|-----------|---------|------| | PSI v5 | 240 QPM | 25,000 QPD | API Key | | CrUX + History | 150 QPM (shared) | Unlimited | API Key | | GSC Search Analytics | 1,200 QPM/site | 30M QPD | Service Account | | GSC URL Inspection | 600 QPM | 2,000 QPD/site | Service Account | | Indexing API | 380 RPM | 200 publish/day | Service Account | | GA4 Data API | 10 concurrent | ~25K tokens/day | Service Account |

Cross-Skill Integration

• seo-technical-audit — uses pagespeed_check.py for real CWV field data; uses inspect to confirm indexation status flagged by DataForSEO's audit.
• seo-page — replaces estimated traffic with real GSC query,page data via gsc; confirms indexation via inspect.
• seo-drift — adds crux-history (25-week trend) and GSC delta tracking to baseline/compare snapshots.
• seo-sitemap — sitemaps command shows which sitemaps Google has actually consumed and their error/warning counts (vs DataForSEO's audit which only crawls).
• seo-content-audit — nlp enhances E-E-A-T entity/sentiment scoring on the page being audited; gsc confirms whether the page is earning impressions for its target keywords.
• seo-geo — gsc --ai-overview --page answers "did this URL appear in AI Overview, and what did it earn?" with Google's own data, complementing the DataForSEO AIO citation pull. Pair gsc --ai-overview --dimensions query,page with the GEO recommendations to confirm wins/losses URL-by-URL.
• seo-ai-search-share-of-voice — pair ga4-referrals (downstream traffic from chatgpt.com/perplexity.ai/

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: amirjahfar1
• Source: amirjahfar1/automate-seo-with-claude
• License: MIT
• Homepage: https://nextbrainsolutions.com/

Install and usage instructions live in the source repository linked above.