blog-google

What this skill does

# 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:**
```bash
python3 skills/blog-google/scripts/run.py google_auth --check --json
```

**Config file:** `~/.config/claude-seo/google-api.json` (shared with claude-seo)
```json
{
  "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"
}
```

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.

### `/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.

For batch inspection: `python3 skills/blog-google/scripts/run.py gsc_inspect --batch <file> --json`

---

## Indexing API

### `/blog google index <url>`

Notify Google of a URL update. Submit new blog posts for faster indexation.

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

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

For batch: `python3 skills/blog-google/scripts/run.py indexing_notify --batch <file> --json`

---

## GA4 Traffic

### `/blog google ga4 [property-id]`

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

**Script:** `python3 skills/blog-google/scripts/run.py ga4_report --property <id> --json`
**Default:** 28 days, filtered to Organic Search channel group.

For top landing pages: `python3 skills/blog-google/scripts/run.py ga4_report --property <id> --report top-pages --json`

---

## YouTube (Video Discovery)

YouTube mentions have the strongest AI visibility correlation (0.737, Ahrefs 75K brands).
Free, API key only. Used by blog-write and blog-rewrite for video embedding.

### `/blog google youtube <query>`

Search YouTube for videos relevant to a blog topic.

**Script:** `python3 skills/blog-google/scripts/run.py youtube_search search "<query>" --json`
**Quota:** 100 units per search (10,000 units/day free).

Returns: title, channel, views, likes, duration, description, tags.

For video details + comments: `python3 skills/blog-google/scripts/run.py youtube_search video <video_id> --json`

---

## NLP Content Analysis

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

### `/blog google nlp <url-or-text>`

Full NLP analysis: entities, sentiment, content classification.

**Script:** `python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --json`
**Free tier:** 5,000 units/month. Requires billing enabled on GCP project.

For entity extraction only: `python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --features entities --json`

---

## Keyword Research (Google Ads)

Gold-standard keyword volume data. Requires Google Ads account (Tier 3).

### `/blog google keywords <seed>`

Generate keyword ideas from seed terms for blog topic research.

**Script:** `python3 skills/blog-google/scripts/run.py keyword_planner ideas "<seed>" --json`

For volume lookup: `python3 skills/blog-google/scripts/run.py keyword_planner volume "<kw1>,<kw2>" --json`

---

## Reports

### `/blog google report <type>`

Generate a professional PDF/HTML report with charts.

**Script:** `python3 skills/blog-google/scripts/run.py google_report --type <type> --data <json> --domain <domain> --format pdf`

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

**Note:** PDF generation requires system libraries: `sudo apt install libpango1.0-dev libcairo2-dev`.
Falls back to HTML if weasyprint is unavailable.

---

## 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 (50 for 360) | 200K Core Tokens/day (2M for 360) | Service Account |
| YouTube Data |: | 10,000 units/day | API Key |
| NLP API |: | 5,000 units/month | API Key (bi