seo-google

[{"code":"env_var","match":"GOOGLE_API_KEY","path":"SKILL.md"},{"code":"api_key_mention","match":"API key","path":"SKILL.md"},{"code":"api_key_mention","match":"api_key","path":"SKILL.md"},{"code":"api_key_mention","match":"API Key","path":"SKILL.md"},{"code":"oauth","match":"OAuth","path":"SKILL.md"},{"code":"payment","match":"billing","path":"SKILL.md"},{"code":"env_var","match":"GOOGLE_API_KEY","path":"references/auth-setup.md"},{"code":"env_var","match":"GOOGLE_APPLICATION_CREDENTIALS","path":"references/auth-setup.md"},{"code":"api_key_mention","match":"API Key","path":"references/auth-setup.md"},{"code":"api_key_mention","match":"API key","path":"references/auth-setup.md"},{"code":"api_key_mention","match":"api_key","path":"references/auth-setup.md"},{"code":"oauth","match":"oauth2","path":"references/auth-setup.md"},{"code":"oauth","match":"OAuth","path":"references/auth-setup.md"},{"code":"oauth","match":"oauth2","path":"references/ga4-data-api.md"},{"code":"oauth","match":"OAuth","path":"references/indexing-api.md"},{"code":"endpoint","match":"https://indexing.googleapis.com/v3/urlNotifications:publish`**","path":"references/indexing-api.md"},{"code":"endpoint","match":"ht

# Google API Authentication Setup

## Overview

Three credential types serve different APIs:

| Type | Used By | Cost |
|------|---------|------|
| **API Key** | PageSpeed Insights, CrUX, CrUX History, Knowledge Graph | Free |
| **Service Account** | Search Console, Indexing API, GA4 | Free |
| **Both** | Full seo-google skill | Free |

## Step 1: Create a Google Cloud Project

1. Go to [console.cloud.google.com](https://console.cloud.google.com)
2. Click **Select a project** > **New Project**
3. Name it (e.g., "Claude SEO") and note the project ID
4. Select the project after creation

## Step 2: Enable APIs

Navigate to **APIs & Services > Library** and enable:

| API | Required For |
|-----|-------------|
| Google Search Console API | GSC Search Analytics, URL Inspection, Sitemaps |
| PageSpeed Insights API | PSI Lighthouse lab data |
| Chrome UX Report API | CrUX field data + History |
| Web Search Indexing API | Indexing API v3 |
| Google Analytics Data API | GA4 organic traffic |
| Knowledge Graph Search API | Entity verification (optional) |

## Step 3: Create an API Key

1. **APIs & Services > Credentials > Create Credentials > API key**
2. Click **Restrict key**:
   - Under

# DMA + Consent Mode v2 — click-through impact diagnostic

EU traffic flowing through Google Search has been subject to the
**Digital Markets Act** since 2024-03-07. The DMA limits how Google
can use behavioural data and forces consent-mode v2 compliance for
GA4 + Ads in EU. The operational effect for SEO audits:

- EU click-through-rate (CTR) data from Search Console is materially
  noisier after the DMA enforcement date. Year-over-year CTR
  comparisons across that boundary are not apples-to-apples.
- GA4 organic-traffic reports for EU users show systematic
  under-reporting when consent-mode v2 is configured as "denied for
  ad_storage, granted for analytics_storage" (the typical EU default).
  Conversion modelling fills the gap, but the raw counts are lower
  than pre-2024.

## What the seo-google skill should do

1. **When pulling GSC search analytics for an EU-targeted property**,
   note: "EU CTR comparisons before/after 2024-03-07 are not
   apples-to-apples (DMA + consent-mode v2 took effect)."
2. **When pulling GA4 organic traffic**, surface the consent-mode
   configuration if the GA4 admin API exposes it. If the property
   has `eu_data_collection_disabled` or denies ad

# GA4 Data API v1beta Reference

## Overview

The Google Analytics Data API v1beta provides programmatic access to GA4 report data. For SEO, the primary use case is organic traffic analysis.

**Base URL:** `https://analyticsdata.googleapis.com/v1beta`

## Key Methods

| Method | Description |
|--------|-------------|
| `properties.runReport` | Run a standard report |
| `properties.batchRunReports` | Up to 5 reports in one call |
| `properties.runRealtimeReport` | Last 30 minutes of data |
| `properties.getMetadata` | Available dimensions and metrics |
| `properties.checkCompatibility` | Verify dimension/metric combinations |

## runReport Request

```json
{
  "property": "properties/123456789",
  "dimensions": [
    { "name": "date" },
    { "name": "landingPage" }
  ],
  "metrics": [
    { "name": "sessions" },
    { "name": "totalUsers" }
  ],
  "dateRanges": [
    { "startDate": "28daysAgo", "endDate": "yesterday" }
  ],
  "dimensionFilter": {
    "filter": {
      "fieldName": "sessionDefaultChannelGroup",
      "stringFilter": {
        "matchType": "EXACT",
        "value": "Organic Search"
      }
    }
  },
  "orderBys": [
    { "metric": { "metricName": "sessions" }, "desc

# Google Indexing API v3 Reference

## Overview

The Indexing API allows you to notify Google when pages are added or removed.

**IMPORTANT:** Use the Indexing API only for eligible URLs with **JobPosting** or **BroadcastEvent embedded in VideoObject** structured data. For a few ordinary URLs, use URL Inspection; for many ordinary URLs, use sitemaps. A `URL_UPDATED` notification only means Google may recrawl soon and gives no indexing benefit for other page types.

## Endpoints

### Publish Notification

**`POST https://indexing.googleapis.com/v3/urlNotifications:publish`**

```json
{
  "url": "https://example.com/jobs/software-engineer",
  "type": "URL_UPDATED"
}
```

| Field | Values |
|-------|--------|
| `url` | The fully qualified URL |
| `type` | `URL_UPDATED` (page added/changed), `URL_DELETED` (page removed) |

**Response:**
```json
{
  "urlNotificationMetadata": {
    "url": "https://example.com/jobs/software-engineer",
    "latestUpdate": {
      "url": "https://example.com/jobs/software-engineer",
      "type": "URL_UPDATED",
      "notifyTime": "2026-03-27T10:00:00Z"
    }
  }
}
```

### Get Notification Metadata

**`GET https://indexing.googleapis.com/v3/urlNotificatio

# Google Ads API - Keyword Planner Reference

Gold-standard source for keyword search volume. DataForSEO gets its volume data from Google Ads -- this cuts out the middleman.

## Prerequisites (More Complex Than Other Google APIs)

1. **Google Ads Manager Account** -- create at ads.google.com (free to create)
2. **Developer Token** -- apply at Google Ads API Center (requires Basic access approval)
3. **OAuth 2.0 credentials** -- reuse existing OAuth client from seo-google config
4. **For exact volumes**: Run a minimal campaign (~$5-10/day). Without spend, volumes are bucketed ranges ("1K-10K")

## Key Methods

### GenerateKeywordIdeas
Generate keyword suggestions from seed terms.

**Returns per keyword:**
- `text`: Keyword string
- `avg_monthly_searches`: Average monthly volume (exact if spending, bucketed if not)
- `competition`: LOW / MEDIUM / HIGH (for ads, not organic)
- `competition_index`: 0-100 competition score
- `low_top_of_page_bid_micros`: ~20th percentile CPC in micros
- `high_top_of_page_bid_micros`: ~80th percentile CPC in micros
- `monthly_search_volumes[]`: Per-month volume for last 12 months

### GenerateKeywordHistoricalMetrics
Get volume data for specific keywords

# Google Cloud Natural Language API Reference

Use NLP analysis as an internal diagnostic for entity coverage, content sentiment, and topic classification. Do not present it as Google's E-E-A-T score, a ranking factor, or a proxy for numeric E-E-A-T weights.

## Endpoint

Entities use `POST https://language.googleapis.com/v1/documents:analyzeEntities`.
Sentiment, classification, and moderation use
`POST https://language.googleapis.com/v2/documents:annotateText`.

Send the API key in the `X-Goog-Api-Key` header, not in the URL.

## Features

| Feature | What It Does | SEO Use |
|---------|-------------|---------|
| `extractEntities` | Extract people, orgs, places, events with salience scores | Topic coverage depth, entity optimization |
| `extractDocumentSentiment` | Document + sentence-level sentiment score/magnitude | Content tone assessment |
| `classifyText` | Map content to 700+ Google categories | Topic relevance verification |
| `moderateText` | Content safety/moderation categories | Content quality flags |

## Entity Types

PERSON, LOCATION, ORGANIZATION, EVENT, WORK_OF_ART, CONSUMER_GOOD, OTHER, PHONE_NUMBER, ADDRESS, DATE, NUMBER, PRICE

Each entity includes:
- `name`: Ent

# PageSpeed Insights v5 + CrUX API Reference

## Table of Contents
1. [PageSpeed Insights v5](#pagespeed-insights-v5)
2. [CrUX API (Daily)](#crux-api-daily)
3. [CrUX History API (Weekly)](#crux-history-api-weekly)
4. [Core Web Vitals Thresholds](#core-web-vitals-thresholds)

---

## PageSpeed Insights v5

**Endpoint:** `GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed`

### Parameters

| Param | Type | Description |
|-------|------|-------------|
| `url` | string | Required. URL to analyze. |
| `category` | string | `ACCESSIBILITY`, `BEST_PRACTICES`, `PERFORMANCE`, `SEO`. Can specify multiple. |
| `strategy` | string | `DESKTOP` or `MOBILE` (default). |
| `locale` | string | Locale for text (e.g., `en`). |
| `key` | string | API key. Optional but recommended for quota. |

### Response Structure

```
{
  "id": "https://example.com/",
  "loadingExperience": { ... },        // URL-level CrUX data
  "originLoadingExperience": { ... },  // Origin-level CrUX data
  "lighthouseResult": {
    "categories": {
      "performance": { "score": 0.85 },
      "accessibility": { "score": 0.92 },
      "best-practices": { "score": 0.88 },
      "seo": { "score": 0.95 }
    },
    "au

# Google API Rate Limits & Quotas

## Consolidated Quota Table

| API | Per-Minute | Per-Day | Cost | Auth Type | Scope |
|-----|-----------|---------|------|-----------|-------|
| GSC Search Analytics | 1,200 QPM/user, 1,200 QPM/site | 30M QPD/project | Free | Service Account | Per user + per site |
| GSC URL Inspection | 600 QPM/site | 2,000 QPD/site | Free | Service Account | Per site |
| GSC Sitemaps | Standard | Standard | Free | Service Account | Per site |
| PageSpeed Insights v5 | 240 QPM | 25,000 QPD | Free | API Key | Per project |
| CrUX API | 150 QPM (shared) | Unlimited | Free | API Key | Per project |
| CrUX History API | 150 QPM (shared with CrUX) | Unlimited | Free | API Key | Per project |
| Indexing API | 380 RPM total, 180 read/min | 200 publish/day | Free | Service Account | Per project |
| GA4 Data API | 10 concurrent | ~25K tokens/day | Free | Service Account | Per property/project |
| Knowledge Graph | -- | 100,000 QPD | Free | API Key | Per project |
| Custom Search | -- | 10,000 QPD max | 100 free, $5/1K | API Key | Per project |
| Web Risk | 6,000 QPM | 100K/month | Free tier | API Key | Per project |

**Key distinction:** "Per site" quotas are scoped to a

# Google Search Console API Reference

## Table of Contents
1. [Search Analytics API](#search-analytics-api)
2. [URL Inspection API](#url-inspection-api)
3. [Sitemaps API](#sitemaps-api)
4. [Sites API](#sites-api)

---

## Search Analytics API

**Endpoint:** `POST http

---
name: seo-google
description: >
  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. Provides real Google field data for Core Web Vitals,
  indexation status, search performance, and organic traffic trends. Use when
  user says "search console", "GSC", "PageSpeed", "CrUX", "field data",
  "indexing API", "GA4 organic", "URL inspection", or "real CWV data".
user-invocable: true
argument-hint: "[command] [url|property]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.2.5"
  category: seo
---

# 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: `~