/blog-google

name: blog-google
description: >
  Google API integration for blog performance: PageSpeed Insights, CrUX Core Web
  Vitals with 25-week history, Search Console performance, URL Inspection, Indexing
  API, GA4 organic traffic, NLP entity analysis for E-E-A-T, YouTube video search
  for embedding, and Google Ads Keyword Planner. Progressive feature availability
  based on credential tier (API key, OAuth/service account, GA4, Ads). Shares
  config with claude-seo at ~/.config/claude-seo/google-api.json. Use when user
  says "google data", "page speed", "core web vitals", "search console",
  "indexation", "GA4", "keyword research", "nlp entities", "blog performance",
  "youtube search", "google api setup".
user-invokable: true
argument-hint: "[setup|pagespeed|crux|crux-history|gsc|inspect|index|ga4|nlp|youtube|keywords|report|quotas] [url|property|query]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.1.1"
  category: blog

Blog Google: Google API Data for Blog Performance

Direct access to Google's SEO APIs for blog performance analysis. Provides real Chrome user metrics, indexation status, search performance, entity analysis, YouTube video discovery, keyword volumes, and PDF/HTML performance reports.

All APIs are free at normal usage levels. Setup requires a Google Cloud project with an API key and/or service account.

Prerequisites

**Always check credentials before running any command:**

python3 skills/blog-google/scripts/run.py google_auth --check --json

**Config file:** `~/.config/claude-seo/google-api.json` (shared with claude-seo)

{
  "api_key": "AIzaSy...",
  "oauth_client_path": "/path/to/client_secret.json",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789",
  "ads_developer_token": "...",
  "ads_customer_id": "123-456-7890",
  "ads_login_customer_id": "123-456-7890"
}

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`, `index` | | **2** (Full) | + `ga4_property_id` configured | Tier 1 + `ga4` | | **3** (Ads) | + `ads_developer_token` + `ads_customer_id` | Tier 2 + `keywords` |

Always communicate the detected tier before running commands.

Quick Reference

| Command | What it does | Tier | |---------|-------------|------| | `/blog google setup` | Check/configure API credentials |: | | `/blog google pagespeed <url>` | PSI Lighthouse + CrUX field data | 0 | | `/blog google crux <url>` | CrUX field data only (p75 metrics) | 0 | | `/blog google crux-history <url>` | 25-week CWV trend analysis | 0 | | `/blog google youtube <query>` | YouTube video search (views, likes, duration) | 0 | | `/blog google nlp <url-or-text>` | NLP entity extraction + sentiment | 0 | | `/blog google gsc <property>` | Search Console: clicks, impressions, CTR, position | 1 | | `/blog google inspect <url>` | URL Inspection: index status, canonical | 1 | | `/blog google index <url>` | Submit URL to Indexing API | 1 | | `/blog google ga4 [property-id]` | GA4 organic traffic report | 2 | | `/blog google keywords <seed>` | Keyword ideas from Google Ads Keyword Planner | 3 | | `/blog google report <type>` | PDF/HTML performance report |: | | `/blog google quotas` | Show rate limits for all APIs |: |

---

PageSpeed + CrUX

`/blog google pagespeed <url>`

Combined Lighthouse lab data + CrUX field data for a published blog post.

**Script:** `python3 skills/blog-google/scripts/run.py pagespeed_check <url> --json` **Reference:** `references/api-reference.md`

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.

`/blog google crux <url>`

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

**Script:** `python3 skills/blog-google/scripts/run.py pagespeed_check <url> --crux-only --json`

`/blog google crux-history <url>`

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

**Script:** `python3 skills/blog-google/scripts/run.py crux_history <url> --json`

---

Search Console

`/blog google gsc <property>`

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

**Script:** `python3 skills/blog-google/scripts/run.py gsc_query --property <property> --json` **Default:** 28 days, dimensions=query,page, type=web, limit=1000.

Includes quick-win detection: queries at position 4-10 with high impressions.

The dedicated Search Console generative-AI reports are a gradual, subset rollout in the Search Console UI. They have separate Search and Discover views; the Search view covers AI Overviews and AI Mode. Do not promise clicks, queries, or API retrieval from these dedicated views. Until Google documents an API, report that capability as `SKIPPED` or unavailable and point the user to the UI.

Search Console platform properties for Instagram, TikTok, X, and YouTube are also rolling out gradually. Their UI can expose Search and Discover performance, but `/blog google gsc` must not claim to retrieve these platform reports through the current API.

`/blog google inspect <url>`

URL Inspection: real indexation status from Google.

**Script:** `python3 skills/blog-google/scripts/run.py gsc_inspect <url> --json`

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

After a canonicalization fix, Google may retain the URL in a duplicate cluster for up to two weeks. If the implementation is now correct and the fix is within that window, report `PENDING_REEVALUATION` rather than an immediate failure. Search Console's Request Indexing feature is quota-limited; reserv