Google SEO APIs

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

seogeo google-auth --check --json

Config file: ~/.config/seo-geo-skill/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

Always communicate the detected tier before running commands.

Quick Reference

PageSpeed + CrUX

/seo google pagespeed <url>

Combined Lighthouse lab data + CrUX field data.

Script: seogeo pagespeed <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: seogeo pagespeed <url> --crux-only --json

/seo google crux-history <url>

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

Script: seogeo crux-history <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: seogeo gsc-query --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. The totals block comes from a separate dimensionless aggregate query because query-level rows can omit anonymized low-volume traffic. Treat totals as site-wide only when totals_complete is true. --limit caps total returned dimension rows, not the size of every pagination request.

AI surfaces in GSC (2026):

• Generative AI performance report (launched 2026-06-03), a dedicated view of AI Overviews + AI Mode visibility. Impressions only (no clicks/CTR/position/query); dimensions Pages/Countries/Devices/Dates (Pacific Time); 1,000-row limit; newest data preliminary; a separate Discover gen-AI report also exists. Rolling out to a subset of properties.
• AI Mode already rolls into standard Performance totals (Web search type), clicks (external-link clicks in AI Mode) and impressions are counted in the normal report, so you cannot cleanly split "classic" vs "AI" traffic from totals. Use the Generative AI report for impressions-only AI visibility.
• Data-reliability caveat: a GSC logging error made impressions, CTR, and average position unreliable from 2025-05-13 to 2026-04-27 (clicks unaffected; fixed forward-only, no backfill). Treat impression/CTR/position trends spanning that window with caution; expect an apparent impressions drop after the fix.

/seo google inspect <url>

URL Inspection: real indexation status from Google.

Script: seogeo gsc-inspect <url> --json

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

/seo google inspect-batch <file>

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

Script: seogeo gsc-inspect --batch <file> --json

/seo google sitemaps <property>

List submitted sitemaps with status, errors, warnings. Sitemap contents report submitted counts only; URL Inspection API is the indexation truth for whether specific URLs are indexed.

Script: seogeo gsc-sitemaps --property <property> --json

Indexing API

/seo google index <url>

Notify Google of a URL update.

Script: seogeo indexing-notify <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.

/seo google index-batch <file>

Batch submit URLs from a file. Tracks quota usage.

Script: seogeo indexing-notify --batch <file> --json

GA4 Traffic

/seo google ga4 [property-id]

Organic traffic report: daily sessions, users, pageviews, bounce rate, engagement.

Script: seogeo ga4-report --property <id> --json Reference: references/ga4-data-api.md Default: 28 days, filtered to Organic Search channel group.

GA4 "AI Assistants" channel (live ~2026-05-13): GA4 added a native AI Assistants Default Channel Group. Sessions referred by a recognized AI assistant get medium=ai-assistant. Google's recognized sources are ChatGPT, Gemini, Claude, Deepseek, Copilot, Grok and the channel excludes Google AI Overviews / AI Mode. Verify Perplexity separately if needed; unsupported sources may stay in Referral, and most AI sessions arrive referrer-less and fall into Direct, so this channel undercounts AI traffic. Forward-only, no backfill.

/seo google ga4-pages [property-id]

Top organic landing pages ranked by sessions.

Script: seogeo ga4-report --property <id> --report top-pages --json

YouTube (Video SEO)

Some third-party studies report a 0.737 correlation between YouTube mentions and AI visibility. Treat it as a methodology-dependent signal. Free, API key only.

/seo google youtube <query>

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

Script: seogeo youtube-search search "<query>" --json Reference: references/youtube-api.md Quota: 100 units per search (10,000 units/day free).

/seo google youtube-video <video_id>

Detailed video info + tags + top 10 comments.

Script: seogeo youtube-search video <video_id> --json Quota: 2 units (video details + comments).

NLP Content Analysis

Google NLP entity/sentiment output for internal content-quality checks. Do not treat it as Google E-E-A-T scoring.

/seo google nlp <url-or-text>

Full NLP analysis: entities, sentiment, content classification.

Script: seogeo nlp-analyze --url <url> --json or --text "..." Reference: references/nlp-api.md Free tier: 5,000 units/month. Requires billing enabled on GCP project.

/seo google entities <url-or-text>

Entity extraction only (faster, less quota).

Script: seogeo nlp-analyze --url <url> --features entities --json

Keyword Research (Google Ads)

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

/seo google keywords <seed>

Generate keyword ideas from seed terms.

Script: seogeo keyword-planner ideas "<seed>" --json Reference: references/keyword-planner-api.md Requires: Ads developer token + customer ID in config (Tier 3).

/seo google volume <keywords>

Search volume for specific keywords (comma-separated).

Script: seogeo keyword-planner volume "<kw1>,<kw2>" --json

Supplementary

/seo google entity <query>

Knowledge Graph entity check. Verifies brand presence.

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

/seo google safety <url>

Web Risk API check for malware/social engineering flags.

Reference: references/supplementary-apis.md

/seo google quotas

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

Reports

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

/seo google report <type>

Generate a professional PDF report with charts and analytics.

Script: seogeo google-report --type <type> --data <json> --domain <domain> --format pdf

Workflow:

1. Run data collection commands (pagespeed, gsc, inspect-batch, etc.)
2. Save JSON output to file: seogeo pagespeed <url> --json > data.json
3. Generate report: seogeo google-report --type cwv-audit --data data.json --domain <domain>

Convention: After completing analysis, suggest: "Generate a report? Use /seo google report <type>"

Rate Limits

Cross-Skill Integration

• seo-audit: Spawns seo-google agent for live CWV + indexation data (conditional)
• seo-technical: Uses seogeo pagespeed for real CWV field data
• seo-performance: CrUX field data supplements Lighthouse lab data
• seo-sitemap: GSC sitemap status shows submitted counts, errors, and warnings; use URL Inspection for indexation truth
• seo-content: GSC query data informs keyword targeting
• seo-geo: Use GSC Generative AI performance reports and AI Overviews/AI Mode/Discover gen-AI include/exclude controls where available

Output Format

• CWV metrics: traffic-light rating (Good / Needs Improvement / Poor)
• Performance reports: tables with sortable columns
• Always include data freshness note
• Save reports as GOOGLE-API-REPORT-{domain}.md
• Markdown/LLM templates in assets/templates/: cwv-audit-report.md, gsc-performance-report.md, indexation-status-report.md; distinct from seogeo google-report's PDF pipeline

Technical Notes

• INP replaced FID on March 12, 2024. Never reference FID.
• CLS values from CrUX are string-encoded (e.g., "0.05"). Scripts handle parsing.
• CrUX 404 = insufficient traffic, not an auth error.
• Search Analytics data has 2-3 day lag.
• round_trip_time replaced effectiveConnectionType in CrUX (Feb 2025).
• Custom Search JSON API is closed to new customers (2025).

Error Handling

Tooling

# What is configured
seogeo google-auth --check --json
seogeo google-auth --tier
seogeo google-auth --setup

# Search Console
seogeo gsc-sites --json
seogeo gsc-query --property https://example.com/ --dimensions query --days 28 --json
seogeo gsc-query --property https://example.com/ --dimensions page,query --limit 500 --json
seogeo gsc-sitemaps --property https://example.com/ --json
seogeo gsc-inspect https://example.com/page --property https://example.com/ --json
seogeo gsc-inspect --batch urls.txt --property https://example.com/ --json

# Performance
seogeo pagespeed https://example.com --strategy both --json
seogeo crux-history https://example.com --form-factor PHONE --json
seogeo lcp-subparts https://example.com --json

# Indexing API
seogeo indexing-notify https://example.com/new-page --type URL_UPDATED --json
seogeo indexing-notify --batch urls.txt --json
seogeo indexing-notify --status https://example.com/page --json

# Analytics and content
seogeo ga4-report --property 123456789 --report organic --days 28 --json
seogeo ga4-report --property 123456789 --report top-pages --json
seogeo nlp-analyze --url https://example.com/post --features entities,categories --json
seogeo youtube-search search "core web vitals" --limit 10 --json
seogeo keyword-planner ideas "coffee subscription" --country US --json

# Deliverable
seogeo google-report --type full --data audit-data.json \
  --domain example.com --format pdf

Two credential tiers, and they unlock different things:

Run google-auth --check before promising data. If a service is not configured, say which credential is missing and what it would unlock — do not silently fall back to a weaker source and present it as equivalent.

Search Console data lags roughly two days, so the default window ends there rather than today. Anything more recent is incomplete, not zero.