# Seo Google

> Direct access to Google's own SEO data via Search Console (Search Analytics, URL Inspection, Sitemaps), PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3, GA4 organic traffic, YouTube video search, Google NLP entity/sentiment analysis, Knowledge Graph entity verification, Web Risk safety, and Google Ads Keyword Planner. Bridges crawl-based analysis (the rest of this cat…

- **Type:** Skill
- **Install:** `agentstack add skill-amirjahfar1-automate-seo-with-claude-seo-google`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [amirjahfar1](https://agentstack.voostack.com/s/amirjahfar1)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [amirjahfar1](https://github.com/amirjahfar1)
- **Source:** https://github.com/amirjahfar1/automate-seo-with-claude/tree/main/skills/seo-google
- **Website:** https://nextbrainsolutions.com/

## Install

```sh
agentstack add skill-amirjahfar1-automate-seo-with-claude-seo-google
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

---

## PageSpeed + CrUX

### `pagespeed `

Combined Lighthouse lab data + CrUX field data.

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

### `crux `

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

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

### `crux-history `

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

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

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

---

## Search Console

### `gsc `

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

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

### `inspect `

URL Inspection: real indexation status from Google.

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

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

### `inspect-batch `

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

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

### `sitemaps `

List submitted sitemaps with status, errors, warnings.

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

---

## Indexing API

### `index `

Notify Google of a URL update.

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

Batch submit URLs from a file. Tracks quota usage.

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

---

## GA4 Traffic

All GA4 reports accept an optional `--page ` 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 `: 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  --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  --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  --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  --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 `

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

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

### `youtube-video `

Detailed video info + tags + top 10 comments.

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

---

## NLP Content Analysis

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

### `nlp `

Full NLP analysis: entities, sentiment, content classification.

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

### `entities `

Entity extraction only (faster, less quota).

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

---

## Keyword Research (Google Ads)

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

### `keywords `

Generate keyword ideas from seed terms.

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

### `volume `

Search volume for specific keywords (comma-separated).

**Script:** `python scripts/keyword_planner.py volume "," --json`

---

## Supplementary

### `entity `

Knowledge Graph entity check. Verifies brand presence.

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

### `safety `

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 `

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

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

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

---

## 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 DataForSEO'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 DataForSEO'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 ` answers "did this URL appear in AI Overview, and what did it earn?" with Google's own data, complementing the DataForSEO 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/

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [amirjahfar1](https://github.com/amirjahfar1)
- **Source:** [amirjahfar1/automate-seo-with-claude](https://github.com/amirjahfar1/automate-seo-with-claude)
- **License:** MIT
- **Homepage:** https://nextbrainsolutions.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-amirjahfar1-automate-seo-with-claude-seo-google
- Seller: https://agentstack.voostack.com/s/amirjahfar1
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.