optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/modules/seranking-seo/skills/seo-google/references/auth-setup.md

@@ -0,0 +1,160 @@
+# Google API Authentication Setup
+
+## Overview
+
+Three credential types serve different APIs:
+
+| Type | Used By | Cost |
+|------|---------|------|
+| **API Key** | PageSpeed Insights, CrUX, CrUX History, Knowledge Graph, YouTube, NLP, Web Risk | Free |
+| **Service Account** | Search Console, Indexing API, GA4 | Free |
+| **Google Ads developer token** | Keyword Planner (volumes / suggestions) | Free (token approval ~24h) |
+| **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 |
+| Google Analytics Admin API | `ga4-properties` (account/property discovery) |
+| Knowledge Graph Search API | Entity verification |
+| YouTube Data API v3 | `youtube` / `youtube-video` commands |
+| Cloud Natural Language API | `nlp` / `entities` commands |
+| Web Risk API | `safety` command (malware / social-engineering check) |
+| Google Ads API | `keywords` / `volume` commands (also requires a Google Ads developer token — see [`keyword-planner-api.md`](keyword-planner-api.md)) |
+
+## Step 3: Create an API Key
+
+1. **APIs & Services > Credentials > Create Credentials > API key**
+2. Click **Restrict key**:
+   - Under **API restrictions**, select: PageSpeed Insights API, Chrome UX Report API, Knowledge Graph Search API, YouTube Data API v3, Cloud Natural Language API, Web Risk API
+3. Copy the key (starts with `AIzaSy...`)
+
+## Step 4: Create a Service Account
+
+1. **IAM & Admin > Service Accounts > Create Service Account**
+2. Name: `seo-skills` (or similar)
+3. Skip optional permissions steps
+4. Click on the created service account > **Keys > Add Key > Create new key > JSON**
+5. Download the JSON file and store it securely (e.g., `~/.config/seo-skills/service_account.json`)
+
+The JSON file looks like:
+```json
+{
+  "type": "service_account",
+  "project_id": "your-project-id",
+  "private_key_id": "...",
+  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+  "client_email": "seo-skills@your-project.iam.gserviceaccount.com",
+  "client_id": "...",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token"
+}
+```
+
+The `client_email` field is what you add to GSC and GA4.
+
+## Step 5: Grant Search Console Access
+
+1. Go to [Google Search Console](https://search.google.com/search-console)
+2. Select your property
+3. **Settings > Users and permissions > Add user**
+4. Paste the service account `client_email`
+5. Set permission level:
+   - **Full** for read-only (Search Analytics, URL Inspection, Sitemaps)
+   - **Owner** if you also need the Indexing API
+
+## Step 6: Grant GA4 Access
+
+1. Go to [Google Analytics](https://analytics.google.com)
+2. **Admin > Property Access Management > Add users** (the + icon)
+3. Paste the service account `client_email`
+4. Set role: **Viewer** (minimum for read-only reporting)
+5. Note the numeric property ID from **Admin > Property Details** (e.g., `123456789`)
+
+## Step 7: Create Config File
+
+```bash
+mkdir -p ~/.config/seo-skills
+```
+
+Save to `~/.config/seo-skills/google-api.json`:
+
+```json
+{
+  "service_account_path": "~/.config/seo-skills/service_account.json",
+  "api_key": "AIzaSy...",
+  "default_property": "sc-domain:example.com",
+  "ga4_property_id": "properties/123456789"
+}
+```
+
+### Property URL Formats
+
+| Format | Example | When to Use |
+|--------|---------|-------------|
+| Domain property | `sc-domain:example.com` | Covers all URLs on the domain (recommended) |
+| URL-prefix property | `https://example.com/` | Covers only that specific prefix |
+
+## Step 8: Verify Setup
+
+```bash
+upstream script excluded; use optbrew capability routing
+```
+
+Expected output at Tier 2 (full):
+```
+Credential Tier: 2 -- Full (API key + Service Account + GA4)
+
+  [OK] PageSpeed Insights v5
+  [OK] Chrome UX Report (CrUX) API
+  [OK] CrUX History API
+  [OK] Google Search Console API
+       Service account: seo-skills@your-project.iam.gserviceaccount.com
+  [OK] Google Indexing API v3
+  [OK] GA4 Data API v1beta
+```
+
+## Environment Variable Alternatives
+
+Instead of (or in addition to) the config file:
+
+| Variable | Purpose |
+|----------|---------|
+| `GOOGLE_API_KEY` | API key for PSI/CrUX |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON |
+| `GA4_PROPERTY_ID` | GA4 property (e.g., `properties/123456789`) |
+| `GSC_PROPERTY` | Default GSC property (e.g., `sc-domain:example.com`) |
+
+## OAuth Scopes Used
+
+| Scope | APIs |
+|-------|------|
+| `https://www.googleapis.com/auth/webmasters.readonly` | GSC (read) |
+| `https://www.googleapis.com/auth/webmasters` | GSC (read/write, needed for sitemap submission) |
+| `https://www.googleapis.com/auth/indexing` | Indexing API |
+| `https://www.googleapis.com/auth/analytics.readonly` | GA4 (read) |
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `403 Forbidden` on GSC | Service account email not added to GSC property, or wrong permission level |
+| `403 Forbidden` on GA4 | Service account email not added to GA4 property as Viewer |
+| `404 Not Found` on GSC | Wrong property URL format. Use `sc-domain:` or include trailing slash for URL-prefix |
+| `404 Not Found` on CrUX | Site has insufficient Chrome traffic. Not a credentials issue. |
+| `429 Rate Limit` | Wait and retry. See rate-limits-quotas.md for per-API limits |
+| `API not enabled` | Enable the specific API in GCP Console > APIs & Services > Library |

package/skills/optbrew/modules/seranking-seo/skills/seo-google/references/cross-skill-integration.md

@@ -0,0 +1,187 @@
+# Cross-skill integration: enriching other skills with real Google field data
+
+This file is the contract other skills follow to enrich their deliverables with Google-API field data **without** spawning the full `seo-google` skill. Each enrichment is a single Python script call that returns JSON; the calling skill parses it and folds the data into its primary deliverable.
+
+The pattern was adapted from `AgriciDaniel/claude-seo`'s wiring across `seo-audit`, `seo-technical`, and `seo-drift`. Config path is namespaced to `~/.config/seo-skills/` so the two plugins coexist cleanly.
+
+## Trigger pattern (every enrichment-aware skill)
+
+Add this near the top of the skill's Process steps, immediately after the existing preflight (credit balance / Firecrawl detection):
+
+```
+**Google data availability check.** Run `upstream script excluded; use optbrew capability routing`
+and parse the result. If `tier >= 0` (any creds present), Google enrichment runs in step
+N (see below). If `tier == -1` or the file is missing, the skill proceeds without
+Google enrichment and notes "Google field data: not configured (run `optbrew capability setup (see top-level routing)`)" in the deliverable.
+```
+
+The `google_auth.py --check --json` output shape:
+
+```json
+{
+  "tier": 1,
+  "available": ["pagespeed", "crux", "crux-history", "gsc", "inspect", "sitemaps", "index"],
+  "missing": ["ga4", "ga4-pages", "keywords", "volume"],
+  "config_path": "/Users/.../.config/seo-skills/google-api.json"
+}
+```
+
+The skill should branch on `available`. Each enrichment lists its required entry below.
+
+## Per-skill enrichment recipes
+
+### `seo-technical-audit` — CrUX field data + per-URL Inspection (Tier 0 + Tier 1)
+
+Replaces the audit's lab-only CWV with actual Chrome user metrics from CrUX, and adds per-URL indexation reality from GSC URL Inspection.
+
+**Step 8b — CrUX (Tier 0):**
+
+```bash
+# Domain-level CrUX (origin)
+upstream script excluded; use optbrew capability routing "https://{domain}" --crux-only --json
+
+# 25-week trend (catches degradation we'd otherwise miss until next month's audit)
+upstream script excluded; use optbrew capability routing "https://{domain}" --origin --json
+```
+
+Surface in `TECH-AUDIT.md` as "## Core Web Vitals (field data)" with p75 LCP / INP / CLS, source label "CrUX 28-day origin", and the 25-week trend direction.
+
+If CrUX has no field data for the origin (low-traffic site), surface "CrUX: insufficient data for {domain}" and continue.
+
+**Step 8c — Per-URL Inspection (Tier 1, mirrors theirs at `seo-technical/GUIDE.md:164`):**
+
+For each of the top 5 traffic URLs from step 5 (or homepage + key landing pages):
+
+```bash
+upstream script excluded; use optbrew capability routing "{url}" --site-url "{config.default_property}" --json
+```
+
+Capture `indexStatusVerdict`, `coverageState`, `googleCanonical` vs `userCanonical`, and `lastCrawlTime`.
+
+Cross-check against the audit's noindex / canonical findings:
+- GSC says `INDEXED` but audit flagged `noindex` → audit is stale, flag for re-audit.
+- GSC says `EXCLUDED` for a "healthy" page → hidden indexability issue invisible to SE Ranking's audit.
+- `userCanonical ≠ googleCanonical` on a top-traffic page → elevated to Critical in the Top-10 fix list regardless of `severity-mapping.md` defaults.
+
+Surface in `TECH-AUDIT.md` as "## Indexation reality check (GSC URL Inspection)" with one row per URL.
+
+If property not verified in this account: "GSC: {domain} not verified — add it in Search Console" and skip 8c only (8b still runs).
+
+### `seo-page` — GSC URL performance + URL Inspection (Tier 1 — `gsc`, `inspect` available)
+
+Replaces inferred-from-SE-Ranking traffic with first-party Google data for the target URL.
+
+```bash
+# GSC search analytics for the URL (requires default_property in config to be set
+# to a verified property that owns this URL — sc-domain:example.com)
+upstream script excluded; use optbrew capability routing "{config.default_property}" --url "{target_url}" --days 28 --json
+
+# URL Inspection (real indexation status, canonical Google sees, last crawl date)
+upstream script excluded; use optbrew capability routing "{target_url}" --site-url "{config.default_property}" --json
+```
+
+Surface in `PAGE.md` "## Snapshot" as new rows:
+- GSC last 28d: `{clicks} clicks / {impressions} impressions / {ctr}% CTR / pos {position}`
+- Google sees: `index status: {INDEXED|EXCLUDED|...}`, canonical: `{userCanonical} → {googleCanonical}`, last crawled: `{date}`
+
+Feed into the verdict heuristic:
+- `INDEXED` + impressions > 100 + position 4–10 → harden REFRESH (clear quick-win territory).
+- `EXCLUDED` (any reason) → harden KILL or CONSOLIDATE.
+- googleCanonical ≠ userCanonical → flag in PAGE.md as a critical issue regardless of verdict.
+
+If the URL's domain isn't a verified GSC property, surface "GSC: {target_domain} not verified — add it in Search Console" and continue.
+
+### `seo-content-audit` — GA4 organic traffic on the audited URL (Tier 2 — `ga4-pages` available)
+
+Replaces estimated traffic with measured organic traffic for the audited URL.
+
+```bash
+upstream script excluded; use optbrew capability routing top-pages --days 28 --json
+```
+
+Filter the result client-side for the audited URL's path. Surface in `VERDICT.md` "## Snapshot" alongside the existing AIO citation cross-check:
+- GA4 organic last 28d: `{sessions} sessions / {users} users / avg engagement time {n}s`
+- If the audited URL doesn't appear in the top-100 organic landing pages: "GA4: not in top-100 organic landing pages last 28d — low or zero traffic."
+
+This is a *signal*, not a veto. Low GA4 traffic on a YMYL page with high E-E-A-T is informative ("we're not earning the visibility our content quality should support") but doesn't change the publish decision.
+
+### `seo-drift` — CrUX-history + indexation drift + SSRF protection (Tier 0+1)
+
+Three additions versus the bare-MCP drift run.
+
+**SSRF protection (always, mirrors theirs at `seo-drift/GUIDE.md:97`):**
+
+Before any URL fetch (Firecrawl, WebFetch, Google APIs), validate via:
+
+```python
+from scripts.google_auth import validate_url
+if not validate_url(target_url):
+    abort("URL rejected: loopback, private IP, link-local, or metadata endpoint")
+```
+
+Or invoke as a one-liner:
+
+```bash
+python3 -c "from scripts.google_auth import validate_url; import sys; sys.exit(0 if validate_url('{url}') else 1)"
+```
+
+`validate_url()` (defined at `upstream script excluded; use optbrew capability routing:366`) rejects: loopback (127.0.0.1, ::1, localhost), RFC1918 private ranges (10/8, 172.16/12, 192.168/16), link-local (169.254/16), and Google metadata endpoints. Refuses non-http(s) schemes.
+
+**`--skip-cwv` flag** (mirrors theirs at `seo-drift/GUIDE.md:107, 131`): skips the entire Google field-data snapshot (step 4b) even when `google-api.json` is configured. Useful when you only care about content/structural drift, or when CrUX rate-limit concerns outweigh CWV coverage.
+
+**Field-data drift** (the actual enrichment):
+
+```bash
+# CWV drift over 25 weeks (origin or per-URL based on baseline scope)
+upstream script excluded; use optbrew capability routing "{baseline_url_or_origin}" --json
+
+# Indexation drift: re-run Inspection on each baselined URL and diff
+upstream script excluded; use optbrew capability routing "{url}" --site-url "{config.default_property}" --json
+```
+
+Compare against the previous baseline's stored CrUX + Inspection JSON. New drift triggers:
+- LCP p75 increased ≥20% → red.
+- INP p75 increased ≥20% → red.
+- CLS p75 increased ≥0.05 absolute → yellow.
+- FCP / TTFB p75 increased ≥30% → yellow.
+- Inspection status changed from `INDEXED` to anything else → red.
+- googleCanonical changed → yellow.
+- last crawl date >60 days old → yellow.
+
+Append to `DRIFT-REPORT.md` "## Field-data drift" section.
+
+**Skip note when `--skip-cwv` was passed:** "Field-data drift: skipped — `--skip-cwv` flag passed at baseline (or this compare)."
+
+### `seo-plan` — Phase-0 auto-spawn (any tier)
+
+Plan composes other skills' outputs. If creds are present and the user hasn't already run `seo-google` in this session, Phase-0 should print:
+
+```
+> Google APIs detected (tier {n}). For real CWV / GSC / GA4 enrichment in
+> downstream phases, run `seo-google {pagespeed,gsc,ga4-pages} <domain>`
+> before re-running this plan. Continue without Google enrichment? (y/n)
+```
+
+If user continues, plan proceeds with SE Ranking data only and notes the limitation in PLAN.md. If user opts to run `seo-google` first, plan exits and re-runs after.
+
+This is the lightest possible auto-spawn — plan doesn't dispatch the skill itself (transferring friction is theirs' anti-pattern we critiqued in EVAL_RESULT_v2.md), it just tells the user there's a richer path available.
+
+## Failure modes (handle gracefully across all skills)
+
+| Failure | Detection | Skill response |
+|---|---|---|
+| Config file missing | `google_auth.py --check` exits non-zero | Note "Google field data: not configured" and skip enrichment |
+| API key invalid | Script returns `{"error": "API_KEY_INVALID"}` | Note "Google API key rejected — re-check `~/.config/seo-skills/google-api.json`" and skip |
+| Property not verified (GSC) | `gsc_query.py` returns `{"error": "PROPERTY_NOT_VERIFIED"}` | Note "GSC property `{x}` not verified for this account" and skip GSC enrichment only |
+| GA4 property not configured | `ga4_property_id` empty in config | Note "GA4: property ID not configured (Tier 2 setup required)" and skip GA4 only |
+| Insufficient CrUX data | `pagespeed_check.py --crux-only` returns `{"crux": null}` | Note "CrUX: insufficient field data for `{url}` (low traffic)" and skip CrUX only |
+| Rate-limit hit | Script returns HTTP 429 | Note "Google API rate-limit reached — try again in 1h" and skip the affected enrichment |
+
+A skill **never** fails the run because Google enrichment failed. Enrichment is optional uplift; the SE Ranking-based deliverable always ships.
+
+## Why this pattern (vs spawning `seo-google` as a sub-skill)
+
+- One Python call per enrichment, returns JSON, parsed in-line — no extra agent context, no extra latency.
+- Each skill stays self-contained; no orchestration logic in the calling skill.
+- Failure-isolated: a failed Google call doesn't pollute the SE Ranking-based primary deliverable.
+- Mirrors the upstream wiring (`AgriciDaniel/claude-seo`'s `seo-technical/GUIDE.md:164` invokes the same scripts directly).

package/skills/optbrew/modules/seranking-seo/skills/seo-google/references/ga4-data-api.md

@@ -0,0 +1,184 @@
+# 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": true }
+  ],
+  "limit": 100,
+  "returnPropertyQuota": true
+}
+```
+
+## SEO-Relevant Dimensions
+
+| Dimension | Description |
+|-----------|-------------|
+| `date` | Date in YYYYMMDD format |
+| `pagePath` | Page path (e.g., `/blog/post`) |
+| `landingPage` | Entry page path |
+| `landingPagePlusQueryString` | Entry page with query params |
+| `fullPageUrl` | Full page URL |
+| `pageTitle` | Page title |
+| `sessionSource` | Traffic source (e.g., `google`) |
+| `sessionMedium` | Traffic medium (e.g., `organic`) |
+| `sessionDefaultChannelGroup` | Channel grouping (e.g., `Organic Search`) |
+| `country` | User country |
+| `deviceCategory` | `desktop`, `mobile`, `tablet` |
+| `hostName` | Domain name |
+| `pageReferrer` | Referrer URL |
+
+## SEO-Relevant Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `sessions` | Number of sessions |
+| `totalUsers` | Total unique users |
+| `newUsers` | First-time users |
+| `activeUsers` | Users with engagement |
+| `screenPageViews` | Page views |
+| `bounceRate` | Bounce rate (0-1, multiply by 100 for %) |
+| `averageSessionDuration` | Avg duration in seconds |
+| `engagementRate` | Engaged session rate (0-1) |
+| `keyEvents` | Key events (replaced deprecated `conversions`) |
+| `eventCount` | Total event count |
+
+## Filter Expressions
+
+### String Filter
+
+```json
+{
+  "filter": {
+    "fieldName": "sessionDefaultChannelGroup",
+    "stringFilter": {
+      "matchType": "EXACT",
+      "value": "Organic Search"
+    }
+  }
+}
+```
+
+Match types: `EXACT`, `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, `FULL_REGEXP`, `PARTIAL_REGEXP`
+
+### Combining Filters
+
+```json
+{
+  "andGroup": {
+    "expressions": [
+      { "filter": { "fieldName": "country", "stringFilter": { "matchType": "EXACT", "value": "US" }}},
+      { "filter": { "fieldName": "deviceCategory", "stringFilter": { "matchType": "EXACT", "value": "mobile" }}}
+    ]
+  }
+}
+```
+
+Also supports `orGroup` and `notExpression`.
+
+## Date Range Shortcuts
+
+| Value | Meaning |
+|-------|---------|
+| `today` | Current day |
+| `yesterday` | Previous day |
+| `NdaysAgo` | N days ago (e.g., `28daysAgo`) |
+| `YYYY-MM-DD` | Specific date |
+
+Up to 4 date ranges per request (for period-over-period comparison).
+
+## Token-Based Quotas
+
+| Quota | Limit | Scope |
+|-------|-------|-------|
+| Daily tokens | 25,000 | Per property per project |
+| Hourly tokens | 5,000 | Per property per project |
+| Concurrent requests | 10 | Per property per project |
+| Hourly tokens (project-wide) | 1,250 | Per project per property per hour |
+
+Set `returnPropertyQuota: true` to monitor consumption. Simple reports cost ~1-10 tokens; complex ones up to ~100.
+
+## Python Example
+
+```python
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import (
+    DateRange, Dimension, Filter, FilterExpression,
+    Metric, OrderBy, RunReportRequest,
+)
+from google.oauth2 import service_account
+
+credentials = service_account.Credentials.from_service_account_file(
+    "service_account.json",
+    scopes=["https://www.googleapis.com/auth/analytics.readonly"],
+)
+
+client = BetaAnalyticsDataClient(credentials=credentials)
+
+request = RunReportRequest(
+    property="properties/123456789",
+    dimensions=[Dimension(name="landingPage")],
+    metrics=[Metric(name="sessions"), Metric(name="totalUsers")],
+    date_ranges=[DateRange(start_date="28daysAgo", end_date="yesterday")],
+    dimension_filter=FilterExpression(
+        filter=Filter(
+            field_name="sessionDefaultChannelGroup",
+            string_filter=Filter.StringFilter(
+                match_type=Filter.StringFilter.MatchType.EXACT,
+                value="Organic Search",
+            ),
+        )
+    ),
+    order_bys=[OrderBy(metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True)],
+    limit=50,
+    return_property_quota=True,
+)
+
+response = client.run_report(request)
+for row in response.rows:
+    print(f"{row.dimension_values[0].value}: {row.metric_values[0].value} sessions")
+```
+
+## Authentication
+- **Scope:** `https://www.googleapis.com/auth/analytics.readonly`
+- Service account must have **Viewer** role in GA4 property
+- Add via GA4 Admin > Property Access Management

package/skills/optbrew/modules/seranking-seo/skills/seo-google/references/indexing-api.md

@@ -0,0 +1,109 @@
+> optbrew distribution notice: Submission disabled. The POST publish and batch examples below document upstream behavior; do not execute them from optbrew. A separate user authority decision and approved submission path are required.
+
+# Google Indexing API v3 Reference
+
+## Overview
+
+The Indexing API allows you to notify Google when pages are added or removed.
+
+**IMPORTANT:** Officially restricted to pages with **JobPosting** or **BroadcastEvent/VideoObject** structured data. Google may process other page types, but provides no guarantees. Always inform users of this limitation.
+
+## 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/urlNotifications/metadata?url={ENCODED_URL}`**
+
+Returns `latestUpdate` and `latestRemove` timestamps for the URL.
+
+### Batch Requests
+
+**`POST https://indexing.googleapis.com/batch`**
+
+Up to **100 URLs** per batch request using `multipart/mixed` format:
+
+```
+POST /batch HTTP/1.1
+Content-Type: multipart/mixed; boundary=batch_boundary
+
+--batch_boundary
+Content-Type: application/http
+Content-ID: <item1>
+
+POST /v3/urlNotifications:publish HTTP/1.1
+Content-Type: application/json
+
+{"url": "https://example.com/jobs/1", "type": "URL_UPDATED"}
+--batch_boundary
+Content-Type: application/http
+Content-ID: <item2>
+
+POST /v3/urlNotifications:publish HTTP/1.1
+Content-Type: application/json
+
+{"url": "https://example.com/jobs/2", "type": "URL_UPDATED"}
+--batch_boundary--
+```
+
+## Authentication
+
+- **Scope:** `https://www.googleapis.com/auth/indexing`
+- **Auth type:** Service account (OAuth 2.0)
+- The service account must be **Owner** in Google Search Console for the target domain
+
+## Quotas
+
+| Limit | Value | Scope |
+|-------|-------|-------|
+| Publish requests | **200/day** (default) | Per project |
+| Read-only requests | 180/min | Per project |
+| Total requests | 380/min | Per project |
+
+Request a quota increase: [Indexing API Quota Increase Form](https://developers.google.com/search/apis/indexing-api/v3/quota-increase)
+
+## Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 400 | Malformed URL or request body | Check URL format |
+| 403 | Permission denied or quota exceeded | Add service account as Owner in GSC, or check quota |
+| 429 | Rate limit exceeded | Back off and retry with exponential delay |
+| 500/503 | Server error | Retry with exponential backoff |
+
+## Best Practices
+
+1. Submit only URLs with actual content changes (don't spam updates)
+2. Use `URL_DELETED` only when a page is permanently removed (returns 404/410)
+3. Track daily quota usage -- the 200/day limit resets at midnight Pacific Time
+4. For large-scale indexing, use XML sitemaps + Search Console instead
+5. Batch requests count individually against the daily quota (100 batch = 100 quota)