# Google SEO APIs Human Guide ## What This Is For 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. It gives the agent a clearer input/output frame for search and SEO workflows: what context to ask for, what decisions to make, and what usable artifact to return. Use this as a human-readable version of the Google SEO APIs agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions. ## When To Use This - Use this when you need a repeatable process for Google SEO APIs. - Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt. - Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact. ## When Not To Use This - Do not use this when you only need a quick factual answer. - Do not use this when the work depends on private data you cannot share with the assistant. - Do not use this as a replacement for legal, compliance, financial, or medical review. ## What You Need Before Starting - The goal or business outcome you want. - The audience, customer segment, or market context. - Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance. - Constraints such as tone, length, channel, deadline, region, or approval requirements. - A clear definition of what a good final answer should look like. ## Step-By-Step Workflow 1. State the job clearly: "Use the Google SEO APIs guide to help me with..." 2. Add context: audience, goal, offer, channel, source material, and constraints. 3. Ask the assistant to identify missing inputs before producing the final output. 4. Have the assistant follow the skill-specific guidance below. 5. Review the result against the final checklist and ask for revisions where needed. ## Skill-Specific Guidance - Run data collection commands (pagespeed, gsc, inspect-batch, etc.) - Save JSON output to file: `claude-seo run pagespeed_check.py --json > data.json` - Generate report: `claude-seo run google_report.py --type cwv-audit --data data.json --domain ` - **seo-audit**: Spawns `seo-google` agent for live CWV + indexation data (conditional) - **seo-technical**: Uses pagespeed_check.py 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 - CWV metrics: traffic-light rating (Good / Needs Improvement / Poor) - Performance reports: tables with sortable columns - Always include data freshness note ## Decision Points And Nuance The original skill emphasizes: Prerequisites, Credential Tiers, Quick Reference, PageSpeed + CrUX, `/seo google pagespeed `, `/seo google crux `, `/seo google crux-history `, Search Console, `/seo google gsc `, `/seo google inspect `. Use these questions to steer the work: - What is the intended audience or buyer? - What source material must be preserved? - What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion? - What examples represent the desired quality bar? - What should the assistant avoid? ## Common Mistakes - List submitted sitemaps with status, errors, warnings. Sitemap contents report - Google NLP entity/sentiment output for internal content-quality checks. Do not treat it as Google E-E-A-T scoring. - **seo-sitemap**: GSC sitemap status shows submitted counts, errors, and warnings; use URL Inspection for indexation truth - INP replaced FID on March 12, 2024. Never reference FID. - | Indexing API quota exceeded | Report 200/day limit. Suggest prioritizing most important URLs. | - **Do not lecture the user on cookie consent UX** — that's a legal - Required GA4 / Consent Mode setup the audit should check for - Softening cookieless-attribution warnings ## Copy-And-Paste Prompt ```text Use the Google SEO APIs human guide. My goal: [Describe the business outcome] Audience: [Describe who this is for] Context and source material: [Paste notes, examples, links, or existing copy] Constraints: [Tone, length, channel, timeline, must-include items, must-avoid items] Before producing the final output, ask me for any missing information that would materially improve the result. ``` ## Final Checklist - [ ] The output matches the original goal. - [ ] The audience and context are reflected in the answer. - [ ] Important constraints and source material were preserved. - [ ] The assistant made the relevant decisions explicit. - [ ] The final artifact is ready to use, review, or hand to the next person. ## Source This guide was generated from the agricidaniel/claude-seo skill entry for `seo-google`. ## Source Skill Notes These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic. # 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: ```bash claude-seo run google_auth.py --check --json ``` Config file: `~/.config/claude-seo/google-api.json` ```json { "service_account_path": "/path/to/service_account.json", "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 ` | PSI Lighthouse + CrUX field data | 0 | | `/seo google crux ` | CrUX field data only (p75 metrics) | 0 | | `/seo google crux-history ` | 25-week CWV trend analysis | 0 | | `/seo google gsc ` | Search Console: clicks, impressions, CTR, position | 1 | | `/seo google inspect ` | URL Inspection: index status, canonical, crawl info | 1 | | `/seo google inspect-batch ` | Batch URL Inspection from file | 1 | | `/seo google sitemaps ` | GSC sitemap status | 1 | | `/seo google index ` | Submit URL to Indexing API | 1 | | `/seo google index-batch ` | 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 ` | YouTube video search (views, likes, duration) | 0 | | `/seo google youtube-video ` | YouTube video details + top comments | 0 | | `/seo google nlp ` | NLP entity extraction + sentiment + classification | 0 | | `/seo google entities ` | Entity analysis only (for E-E-A-T) | 0 | | `/seo google keywords ` | Keyword ideas from Google Ads Keyword Planner | 3 | | `/seo google volume ` | Search volume lookup from Keyword Planner | 3 | | `/seo google entity ` | Knowledge Graph entity check | 0 | | `/seo google safety ` | Web Risk URL safety check | 0 | | `/seo google quotas` | Show rate limits for all APIs | -- | --- ## PageSpeed + CrUX ### `/seo google pagespeed ` Combined Lighthouse lab data + CrUX field data. **Script:** `claude-seo run 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.