# Seo Google

> Acceso directo a los datos SEO de Google: Search Console, PageSpeed Insights, CrUX, Indexing API, GA4, YouTube, NLP, Knowledge Graph, Web Risk y Keyword Planner — datos reales de Chrome e indexación, no estimaciones.

Fuente: https://skillsagentes.com/skills/seranking/seo-skills/seo-google
Markdown: https://skillsagentes.com/skills/seranking/seo-skills/seo-google.md

Repositorio: https://github.com/seranking/seo-skills
Autor: seranking
Licencia: MIT
Actualizado: hace 4 meses
Coste de contexto: 224 tok instalada, 4.8k tok al activarse, 17.8k tok con todos los archivos del bundle
Bundle: 15 archivos, 69 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add seranking/seo-skills --skill seo-google --agent claude-code
# Cursor
npx -y skills add seranking/seo-skills --skill seo-google --agent cursor
# Codex
npx -y skills add seranking/seo-skills --skill seo-google --agent codex
# Gemini CLI
npx -y skills add seranking/seo-skills --skill seo-google --agent gemini
# Windsurf
npx -y skills add seranking/seo-skills --skill seo-google --agent windsurf
# Cline
npx -y skills add seranking/seo-skills --skill seo-google --agent cline
```

## Qué hace

- Consulta directamente las APIs de Google: Search Console, PageSpeed Insights v5, CrUX (con histórico de 25 semanas), Indexing API v3, GA4, YouTube, NLP, Knowledge Graph y Google Ads Keyword Planner
- Combina datos de laboratorio de Lighthouse con datos de campo reales de Chrome (CrUX) para métricas Core Web Vitals
- Detecta el nivel de credenciales configurado (Tier 0-3) y comunica qué comandos están disponibles antes de ejecutarlos
- Genera reportes PDF/HTML/XLSX a partir de los datos JSON recopilados con gráficos y tablas
- Filtra tráfico de GSC/GA4 por AI Overview, referidos de asistentes de IA (ChatGPT, Claude, Perplexity, etc.) y mezcla de canales

## Cuándo usarla

- El usuario pide 'search console', 'GSC', 'PageSpeed', 'CrUX', 'field data', 'indexing API' o 'GA4 organic'
- Se necesitan datos reales de Chrome (LCP, INP, CLS, FCP, TTFB) en vez de estimaciones de rastreo
- Se quiere verificar el estado real de indexación, impresiones, clics, CTR o posición de búsqueda
- Se requiere investigación de palabras clave con Google Ads Keyword Planner, YouTube SEO, Knowledge Graph o Web Risk

## Qué la activa

- "Consulta los datos de Search Console para este dominio"
- "Revisa el CrUX y el histórico de 25 semanas de esta URL"
- "Verifica si esta página está indexada con URL Inspection"
- "Muéstrame el tráfico orgánico de GA4 y los referidos de asistentes de IA"

## Antes de instalar

- Requiere Python 3.10+, las librerías cliente de Google API (instalables con extensions/google/install.sh) y al menos una API key de Google (Tier 0), con service account, GA4 property ID o Ads developer token para niveles superiores.
- Necesita en el PATH: python

## Archivos

- SKILL.md — 19 KB
- assets/templates/cwv-audit-report.md — 2 KB
- assets/templates/gsc-performance-report.md — 1 KB
- assets/templates/indexation-status-report.md — 1 KB
- references/auth-setup.md — 6 KB
- references/cross-skill-integration.md — 10 KB
- references/ga4-data-api.md — 5 KB
- references/indexing-api.md — 3 KB
- references/keyword-planner-api.md — 2 KB
- references/nlp-api.md — 2 KB
- references/pagespeed-crux-api.md — 6 KB
- references/rate-limits-quotas.md — 3 KB
- references/search-console-api.md — 5 KB
- references/supplementary-apis.md — 3 KB
- references/youtube-api.md — 1 KB

## SKILL.md

Reproducido tal cual desde seranking/seo-skills bajo MIT. Esta sección es el documento original y está en inglés.

> 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`](https://github.com/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:

```bash
python scripts/google_auth.py --check --json
```

Config file shape (`~/.config/seo-skills/google-api.json`):

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

---

## PageSpeed + CrUX

### `pagespeed <url>`

Combined Lighthouse lab data + CrUX field data.

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

### `crux <url>`

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

**Script:** `python scripts/pagespeed_check.py <url> --crux-only --json`

### `crux-history <url>`

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

**Script:** `python scripts/crux_history.py <url> --json`
**Reference:** `references/pagespeed-crux-api.md`

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

---

## Search Console

### `gsc <property>`

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

**Script:** `python scripts/gsc_query.py --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.

**Filtering:** `--device {desktop,mobile,tablet}`, `--country <ISO3>`, `--page <url-or-substring>` (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 <value>`.

### `inspect <url>`

URL Inspection: real indexation status from Google.

**Script:** `python scripts/gsc_inspect.py <url> --json`

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

### `inspect-batch <file>`

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

**Script:** `python scripts/gsc_inspect.py --batch <file> --json`

### `sitemaps <property>`

List submitted sitemaps with status, errors, warnings.

**Script:** `python scripts/gsc_query.py sitemaps --property <property> --json`

---

## Indexing API

### `index <url>`

Notify Google of a URL update.

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

### `index-batch <file>`

Batch submit URLs from a file. Tracks quota usage.

**Script:** `python scripts/indexing_notify.py --batch <file> --json`

---

## GA4 Traffic

All GA4 reports accept an optional `--page <path-or-url>` 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 <name|all>`: 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 <id> --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 <id> --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 <id> --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 <id> --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 <query>`

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

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

### `youtube-video <video_id>`

Detailed video info + tags + top 10 comments.

**Script:** `python scripts/youtube_search.py video <video_id> --json`
**Quota:** 2 units (video details + comments).

---

## NLP Content Analysis

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

### `nlp <url-or-text>`

Full NLP analysis: entities, sentiment, content classification.

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

### `entities <url-or-text>`

Entity extraction only (faster, less quota).

**Script:** `python scripts/nlp_analyze.py --url <url> --features entities --json`

---

## Keyword Research (Google Ads)

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

### `keywords <seed>`

Generate keyword ideas from seed terms.

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

### `volume <keywords>`

Search volume for specific keywords (comma-separated).

**Script:** `python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json`

---

## Supplementary

### `entity <query>`

Knowledge Graph entity check. Verifies brand presence.

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

### `safety <url>`

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 <type>`

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

**Script:** `python scripts/google_report.py --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, 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 <url> --json > data.json`
3. Generate report: `python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>`

**Convention:** After completing analysis, suggest: "Generate a report? Use `report <type>`."

---

## 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 SE Ranking'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 SE Ranking'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 <url>` answers "did this URL appear in AI Overview, and what did it earn?" with Google's own data, complementing the SE Ranking 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/gemini.google.com etc.) with the SoV pull (upstream citation/brand mention presence) for a complete AI-visibility picture: SoV measures whether LLMs cite you, GA4 referrals measure whether their users actually click through.
- **`seo-keyword-cluster`** / **`seo-keyword-niche`** — `volume` (Tier 3) replaces SE Ranking volume with Google Ads gold-standard volumes when available.
- **`seo-plan`** — when GSC + GA4 are configured, the "Where you are" baseline uses real impressions/clicks/conversions instead of SE Ranking estimates.

## 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`
- Use templates from `assets/templates/` for structured output

## 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 a 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

| Scenario | Action |
|----------|--------|
| No credentials configured | Run `setup`. List Tier 0 commands that work with just an API key. |
| Service account lacks GSC access | Report error. Instruct: add `client_email` to GSC > Settings > Users > Add. |
| CrUX data unavailable (404) | Report insufficient Chrome traffic. Suggest PSI lab data as fallback. |
| GA4 property not found | Report error. Show how to find property ID in GA4 Admin > Property Details. |
| Indexing API quota exceeded | Report 200/day limit. Suggest prioritizing most important URLs. |
| Rate limit (429) | Wait and retry with exponential backoff. Report which API hit the limit. |

## Dónde encaja

- Categoría: [SEO y GEO](https://skillsagentes.com/categorias/seo-geo.md) — Keywords, auditorías on-page, datos estructurados y visibilidad en respuestas de IA.
- Creador: [seranking](https://skillsagentes.com/creators/seranking.md) — 32 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Client Onboarding Proposal](https://skillsagentes.com/skills/seranking/seo-skills/client-onboarding-proposal.md): Construye una propuesta de onboarding de cliente basada en datos, combinando un audit SEO + búsqueda IA de SE Ranking con un análisis en Planable del rendimiento social actual del cliente.
- [Local Gmb Visibility](https://skillsagentes.com/skills/seranking/seo-skills/local-gmb-visibility.md): Combina el seguimiento de rankings por ciudad de SE Ranking con contenido social local en Planable, incluyendo publicaciones de Google Business Profile.
- [Ai Search Gaps To Social Campaign](https://skillsagentes.com/skills/seranking/seo-skills/ai-search-gaps-to-social-campaign.md): Encuentra los prompts y temas de búsqueda con IA donde una marca es invisible o pierde frente a competidores en SE Ranking, y convierte esos vacíos en una campaña social en Planable con seguimiento antes/después.
- [Site Audit To Social Distribution](https://skillsagentes.com/skills/seranking/seo-skills/site-audit-to-social-distribution.md): Detecta páginas débiles y brechas de contenido en SE Ranking, y coordina la corrección en Planable: redacta el copy reescrito para revisión y aprobación, y programa la distribución social.
- [Seo Ai Social Report](https://skillsagentes.com/skills/seranking/seo-skills/seo-ai-social-report.md): Genera un único reporte de rendimiento que une rankings SEO, visibilidad en búsquedas IA (SE Ranking) y engagement social (Planable): resumen en el chat más un informe HTML interactivo autónomo.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)