optbrew 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,66 @@
+# 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.
+
+Same return fields as above but for exact keyword list instead of suggestions.
+
+### GenerateKeywordForecastMetrics
+Predict clicks, impressions, and cost for keywords.
+
+## Configuration
+
+Add to `~/.config/seo-skills/google-api.json`:
+
+```json
+{
+  "ads_developer_token": "YOUR_DEV_TOKEN",
+  "ads_customer_id": "123-456-7890",
+  "ads_login_customer_id": "123-456-7890"
+}
+```
+
+## Rate Limits
+
+- Keyword Planning requests are more strictly rate-limited than other Ads API services
+- Exact QPM/QPS not publicly documented
+- Google recommends caching results
+
+## Python Library
+
+```bash
+pip install google-ads
+```
+
+Uses `google-ads` library (separate from `google-api-python-client`).
+
+## Important Notes
+
+- **Volume accuracy**: Without active ad spend, Google returns bucketed ranges ("1K-10K", "10K-100K") instead of exact numbers like "14,800"
+- **Competition score**: Measures advertiser competition for ads, NOT organic ranking difficulty
+- **CPC bids**: Reflect what advertisers pay, useful for estimating keyword commercial value
+- **Location targeting**: Use location IDs (2840 = United States, 2826 = United Kingdom)
+- **Language targeting**: Use language IDs (1000 = English, 1003 = Spanish)

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

@@ -0,0 +1,55 @@
+# Google Cloud Natural Language API Reference
+
+NLP analysis enhances E-E-A-T scoring by measuring entity coverage, content sentiment, and topic classification using Google's own taxonomy.
+
+## Endpoint
+
+`POST https://language.googleapis.com/v2/documents:annotateText?key={API_KEY}`
+
+## 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`: Entity text
+- `type`: Entity type
+- `salience`: Importance score (0-1, higher = more relevant)
+- `sentiment`: Per-entity sentiment (score + magnitude)
+- `metadata`: Wikipedia URL, MID (Knowledge Graph ID)
+- `mentions`: Occurrences in the text
+
+## Sentiment Scoring
+
+- **Score**: -1.0 (negative) to +1.0 (positive)
+- **Magnitude**: 0 to infinity (emotional intensity, higher = more emotional)
+- Neutral content: score ~0, low magnitude
+- Mixed content: score ~0, HIGH magnitude (both positive and negative)
+
+## Pricing
+
+| Feature | Free/month | Paid (per 1K chars) |
+|---------|-----------|-------------------|
+| Entity Analysis | 5,000 units | $0.001 |
+| Sentiment Analysis | 5,000 units | $0.001 |
+| Content Classification | 30,000 units | $0.002 |
+| Text Moderation | 50,000 units | $0.0005 |
+
+One "unit" = 1,000 characters. Free tier resets monthly.
+
+## Enable the API
+
+1. Go to [console.cloud.google.com/apis/library](https://console.cloud.google.com/apis/library)
+2. Search for "Cloud Natural Language API"
+3. Click Enable
+4. **Billing must be enabled** on the project (free tier still applies)
+
+Uses the same API key as PSI/CrUX.

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

@@ -0,0 +1,204 @@
+# 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 }
+    },
+    "audits": { ... }                  // Individual audit results
+  },
+  "analysisUTCTimestamp": "2026-03-27T..."
+}
+```
+
+### Field Data Metrics (in loadingExperience)
+
+| PSI Key | CrUX Metric | Unit |
+|---------|-------------|------|
+| `LARGEST_CONTENTFUL_PAINT_MS` | LCP | ms |
+| `INTERACTION_TO_NEXT_PAINT` | INP | ms |
+| `CUMULATIVE_LAYOUT_SHIFT_SCORE` | CLS | unitless |
+| `FIRST_CONTENTFUL_PAINT_MS` | FCP | ms |
+| `EXPERIMENTAL_TIME_TO_FIRST_BYTE` | TTFB | ms |
+
+Each metric contains: `percentile` (p75), `distributions[]` ({min, max, proportion}), `category` (FAST/AVERAGE/SLOW/NONE).
+
+### Key Lighthouse Audit IDs
+
+`first-contentful-paint`, `largest-contentful-paint`, `total-blocking-time`, `cumulative-layout-shift`, `speed-index`, `interactive`
+
+### Rate Limits
+- 25,000 QPD with API key
+- 240 QPM
+- Free, no billing required
+
+### Note on Field Data Migration
+Google is migrating CrUX field data out of PSI. For field data, prefer the CrUX API directly. Use PSI primarily for Lighthouse lab data.
+
+---
+
+## CrUX API (Daily)
+
+**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryRecord?key={API_KEY}`
+
+### Request
+
+```json
+{
+  "origin": "https://example.com",
+  "formFactor": "PHONE",
+  "metrics": ["largest_contentful_paint", "interaction_to_next_paint", "cumulative_layout_shift"]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `origin` | Origin URL (mutually exclusive with `url`) |
+| `url` | Specific page URL (mutually exclusive with `origin`) |
+| `formFactor` | `DESKTOP`, `PHONE`, `TABLET` (optional, omit for all) |
+| `metrics` | Array of metric names (optional, omit for all) |
+
+### Available Metrics
+
+| Metric | Type | Notes |
+|--------|------|-------|
+| `largest_contentful_paint` | int (ms) | Core Web Vital |
+| `interaction_to_next_paint` | int (ms) | Core Web Vital (replaced FID) |
+| `cumulative_layout_shift` | **string** | Core Web Vital. **String-encoded!** Parse carefully. |
+| `first_contentful_paint` | int (ms) | |
+| `experimental_time_to_first_byte` | int (ms) | |
+| `round_trip_time` | int (ms) | Replaced effectiveConnectionType (Feb 2025) |
+| `navigation_types` | fractions | navigate, navigate_cache, reload, etc. |
+| `form_factors` | fractions | desktop/phone/tablet distribution |
+
+### Response
+
+```json
+{
+  "record": {
+    "key": { "origin": "https://example.com" },
+    "metrics": {
+      "largest_contentful_paint": {
+        "histogram": [
+          { "start": 0, "end": 2500, "density": 0.72 },
+          { "start": 2500, "end": 4000, "density": 0.18 },
+          { "start": 4000, "density": 0.10 }
+        ],
+        "percentiles": { "p75": 2100 }
+      },
+      "cumulative_layout_shift": {
+        "percentiles": { "p75": "0.05" }
+      }
+    },
+    "collectionPeriod": {
+      "firstDate": { "year": 2026, "month": 2, "day": 27 },
+      "lastDate": { "year": 2026, "month": 3, "day": 26 }
+    }
+  }
+}
+```
+
+### Important
+- **CLS p75 is a string** (e.g., `"0.05"` not `0.05`). Always parse as float from string.
+- Last histogram bin has **no `end`** (extends to infinity).
+- Densities sum to approximately 1.0.
+- **404** = no data (insufficient Chrome traffic). Not an auth error.
+- Updated daily ~04:00 UTC with ~2 day lag.
+
+### Rate Limits
+- 150 QPM shared between CrUX and CrUX History APIs
+- Free, no paid increase available
+
+---
+
+## CrUX History API (Weekly)
+
+**Endpoint:** `POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key={API_KEY}`
+
+Same request format as CrUX API. Returns up to **25 weekly collection periods**.
+
+### Response Differences from CrUX API
+
+Instead of single values, returns timeseries:
+
+```json
+{
+  "record": {
+    "metrics": {
+      "largest_contentful_paint": {
+        "histogramTimeseries": [
+          { "start": 0, "end": 2500, "densities": [0.70, 0.71, 0.72, ...] },
+          { "start": 2500, "end": 4000, "densities": [0.19, 0.18, 0.18, ...] },
+          { "start": 4000, "densities": [0.11, 0.11, 0.10, ...] }
+        ],
+        "percentilesTimeseries": {
+          "p75s": [2200, 2150, 2100, ...]
+        }
+      }
+    },
+    "collectionPeriods": [
+      {
+        "firstDate": { "year": 2025, "month": 9, "day": 29 },
+        "lastDate": { "year": 2025, "month": 10, "day": 26 }
+      },
+      ...
+    ]
+  }
+}
+```
+
+### NaN Handling
+- `"NaN"` string for densities in ineligible periods
+- `null` for percentile values in ineligible periods
+- Always check for these before numeric operations
+
+### Update Schedule
+- Updated **Mondays** ~04:00 UTC
+- Each period = 28-day rolling average ending on a Sunday
+
+---
+
+## Core Web Vitals Thresholds
+
+Current as of March 2026. INP replaced FID on March 12, 2024.
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** | ≤ 2,500ms | 2,500–4,000ms | > 4,000ms |
+| **INP** | ≤ 200ms | 200–500ms | > 500ms |
+| **CLS** | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+| **FCP** | ≤ 1,800ms | 1,800–3,000ms | > 3,000ms |
+| **TTFB** | ≤ 800ms | 800–1,800ms | > 1,800ms |
+
+FID was fully removed from Chrome tools (CrUX, PSI, Lighthouse) on September 9, 2024. Never reference FID in outputs.

package/skills/optbrew/modules/seranking-seo/skills/seo-google/references/rate-limits-quotas.md

@@ -0,0 +1,75 @@
+# 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 specific GSC property. "Per project" quotas are shared across all properties in a GCP project. "Per user" quotas are per authenticated user (service account).
+
+## Exponential Backoff Strategy
+
+When receiving 429 or 5xx errors:
+
+```
+Attempt 1: wait 1 second
+Attempt 2: wait 2 seconds
+Attempt 3: wait 4 seconds
+Attempt 4: wait 8 seconds
+Attempt 5: wait 16 seconds
+Max: give up after 5 retries
+```
+
+Add random jitter (0-500ms) to each wait to avoid thundering herd.
+
+## Common Error Codes
+
+| Code | Meaning | Applies To | Action |
+|------|---------|------------|--------|
+| 400 | Bad request | All | Check URL format, request body |
+| 401 | Unauthorized | Service Account APIs | Refresh credentials |
+| 403 | Forbidden | GSC, GA4, Indexing | Check permissions (service account access) |
+| 404 | Not found | CrUX, GSC | Insufficient traffic (CrUX) or invalid property (GSC) |
+| 429 | Rate limited | All | Backoff and retry. Check Retry-After header. |
+| 500 | Server error | All | Retry with backoff |
+| 503 | Service unavailable | All | Retry with backoff |
+
+## Retry-After Header
+
+Some Google APIs return a `Retry-After` header with 429 responses. When present, use this value (in seconds) instead of exponential backoff.
+
+## GA4 Token Budgeting
+
+GA4 uses a token system rather than simple request counts:
+- Simple 1-dimension, 1-metric report: ~1-5 tokens
+- Complex multi-dimension, multi-metric: ~10-100 tokens
+- Set `returnPropertyQuota: true` to monitor consumption
+- Daily limit: 25,000 tokens per property per project
+- Hourly limit: 5,000 tokens per property per project
+- Concurrent: max 10 simultaneous requests
+
+## CrUX Shared Quota
+
+The CrUX API and CrUX History API share the same 150 QPM quota per project. Plan accordingly if querying both APIs in the same workflow.
+
+## Cost Summary
+
+**All APIs used by seo-google are free** at normal usage levels. No billing is required for:
+- PSI, CrUX, CrUX History (API key, unlimited free)
+- GSC (service account, 30M QPD)
+- Indexing API (service account, 200 publish/day)
+- GA4 Data API (service account, 25K tokens/day)
+- Knowledge Graph (API key, 100K QPD)
+
+Only Custom Search and Web Risk have paid tiers at high volumes.

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

@@ -0,0 +1,156 @@
+# 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 https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query`
+
+### Request Body
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `startDate` | string | Required. YYYY-MM-DD format. |
+| `endDate` | string | Required. YYYY-MM-DD format. |
+| `dimensions` | string[] | `query`, `page`, `country`, `device`, `date`, `searchAppearance` |
+| `type` | string | `web` (default), `image`, `video`, `news`, `discover`, `googleNews` |
+| `dimensionFilterGroups` | object[] | Array of filter groups (see below) |
+| `aggregationType` | string | `auto` (default), `byPage`, `byProperty`, `byNewsShowcasePanel` |
+| `rowLimit` | int | 1-25000 (default: 1000) |
+| `startRow` | int | Pagination offset (default: 0) |
+| `dataState` | string | `final` (default), `all`, `hourly_all` |
+
+### Dimension Filters
+
+```json
+{
+  "dimensionFilterGroups": [{
+    "filters": [{
+      "dimension": "query",
+      "operator": "contains",
+      "expression": "seo"
+    }]
+  }]
+}
+```
+
+**Operators:** `contains`, `equals`, `notContains`, `notEquals`, `includingRegex`, `excludingRegex`
+- Regex uses RE2 syntax, max 4096 characters
+
+### Response
+
+```json
+{
+  "rows": [
+    {
+      "keys": ["seo tools", "https://example.com/tools"],
+      "clicks": 150,
+      "impressions": 5000,
+      "ctr": 0.03,
+      "position": 4.2
+    }
+  ],
+  "responseAggregationType": "byPage"
+}
+```
+
+### Important Notes
+- Data has a **2-3 day lag**. Available for approximately 16 months.
+- `discover` and `googleNews` types do not support `query` dimension or `position` metric.
+- Country codes are **ISO 3166-1 alpha-3** (e.g., `USA`, `GBR`, `DEU`).
+- Pagination: increment `startRow` by `rowLimit` until fewer rows returned.
+
+### Rate Limits
+- 1,200 QPM per user
+- 1,200 QPM per site
+- 40,000 QPM / 30,000,000 QPD per project
+
+---
+
+## URL Inspection API
+
+**Endpoint:** `POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect`
+
+### Request
+
+```json
+{
+  "inspectionUrl": "https://example.com/page",
+  "siteUrl": "sc-domain:example.com",
+  "languageCode": "en"
+}
+```
+
+### Response Fields
+
+**`indexStatusResult`:**
+
+| Field | Values |
+|-------|--------|
+| `verdict` | `PASS`, `FAIL`, `NEUTRAL`, `PARTIAL`, `VERDICT_UNSPECIFIED` |
+| `coverageState` | Human-readable coverage description |
+| `robotsTxtState` | `ALLOWED`, `DISALLOWED` |
+| `indexingState` | `INDEXING_ALLOWED`, `BLOCKED_BY_META_TAG`, `BLOCKED_BY_HTTP_HEADER` |
+| `pageFetchState` | `SUCCESSFUL`, `SOFT_404`, `BLOCKED_ROBOTS_TXT`, `NOT_FOUND`, `ACCESS_DENIED`, `SERVER_ERROR`, `REDIRECT_ERROR`, `ACCESS_FORBIDDEN`, `BLOCKED_4XX`, `INTERNAL_CRAWL_ERROR`, `INVALID_URL` |
+| `lastCrawlTime` | ISO 8601 timestamp |
+| `googleCanonical` | URL Google selected as canonical |
+| `userCanonical` | URL declared canonical by the page |
+| `crawledAs` | `DESKTOP`, `MOBILE` |
+
+**`richResultsResult`:** Verdict + detected rich result types (FAQPage, HowTo, etc.)
+
+### Rate Limits
+- 2,000 QPD / 600 QPM per site
+- 10,000,000 QPD / 15,000 QPM per project
+
+---
+
+## Sitemaps API
+
+**Base:** `https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/sitemaps`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/sitemaps` | List all sitemaps |
+| `GET` | `/sitemaps/{feedpath}` | Get specific sitemap |
+| `PUT` | `/sitemaps/{feedpath}` | Submit a sitemap |
+| `DELETE` | `/sitemaps/{feedpath}` | Delete a sitemap |
+
+### Sitemap Resource
+
+| Field | Description |
+|-------|-------------|
+| `path` | URL of the sitemap |
+| `lastSubmitted` | Last submission timestamp |
+| `isPending` | Whether processing is incomplete |
+| `isSitemapsIndex` | Whether this is a sitemap index |
+| `type` | `sitemap`, `atomFeed`, `rssFeed`, `urlList`, `notSitemap` |
+| `warnings` | Warning count |
+| `errors` | Error count |
+| `contents[]` | Array with `type` (web, image, video, news) and `submitted` count |
+
+---
+
+## Sites API
+
+**Base:** `https://www.googleapis.com/webmasters/v3/sites`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/sites` | List all verified properties |
+| `GET` | `/sites/{siteUrl}` | Get property info |
+| `PUT` | `/sites/{siteUrl}` | Add a property |
+| `DELETE` | `/sites/{siteUrl}` | Remove a property |
+
+### Property Resource
+
+| Field | Values |
+|-------|--------|
+| `siteUrl` | Property URL (e.g., `sc-domain:example.com`) |
+| `permissionLevel` | `siteOwner`, `siteFullUser`, `siteRestrictedUser`, `siteUnverifiedUser` |

package/skills/optbrew/modules/seranking-seo/skills/seo-google/references/supplementary-apis.md

@@ -0,0 +1,99 @@
+# Supplementary Google APIs for SEO
+
+## Knowledge Graph Search API
+
+Verify brand/entity presence in Google's Knowledge Graph.
+
+**Endpoint:** `GET https://kgsearch.googleapis.com/v1/entities:search`
+
+| Param | Description |
+|-------|-------------|
+| `query` | Search query |
+| `ids` | Specific entity IDs (e.g., `/m/0d6lp`) |
+| `languages` | Language codes (e.g., `en`) |
+| `types` | Schema.org types to filter (e.g., `Organization`, `Person`) |
+| `limit` | Max results (1-500) |
+| `key` | API key (required) |
+
+**Response:**
+```json
+{
+  "itemListElement": [{
+    "result": {
+      "@id": "kg:/m/0d6lp",
+      "name": "Google",
+      "@type": ["Organization", "Corporation"],
+      "description": "Technology company",
+      "detailedDescription": {
+        "articleBody": "Google LLC is an American...",
+        "url": "https://en.wikipedia.org/wiki/Google"
+      },
+      "image": { "url": "..." },
+      "url": "https://www.google.com"
+    },
+    "resultScore": 4892.5
+  }]
+}
+```
+
+**Use for SEO:** Verify if a brand has a Knowledge Panel, check entity disambiguation, find related entities.
+
+**Quota:** 100,000 reads/day. Free. API key only.
+
+---
+
+## Custom Search JSON API
+
+Programmatic Google search results (limited).
+
+**Endpoint:** `GET https://customsearch.googleapis.com/customsearch/v1`
+
+| Param | Description |
+|-------|-------------|
+| `key` | API key (required) |
+| `cx` | Programmable Search Engine ID (required) |
+| `q` | Search query |
+| `num` | Results per page (1-10) |
+| `start` | Start index (max 91) |
+| `dateRestrict` | Date restriction (e.g., `d30` for 30 days) |
+| `gl` | Country (e.g., `us`) |
+| `lr` | Language restriction |
+| `searchType` | `image` for image search |
+| `siteSearch` | Restrict to a domain |
+
+**Limitations:**
+- Max 100 total results per query (10 pages x 10 results)
+- **CLOSED to new customers as of 2025.** Existing customers must migrate by January 2027.
+- 100 queries/day free, $5 per 1,000 up to 10,000/day
+
+**For SERP data, prefer DataForSEO** (`/seo dataforseo serp`) which has no such limitations.
+
+---
+
+## Web Risk API
+
+Check if URLs are flagged as unsafe by Google Safe Browsing.
+
+**Endpoint:** `GET https://webrisk.googleapis.com/v1/uris:search`
+
+| Param | Description |
+|-------|-------------|
+| `threatTypes` | `MALWARE`, `SOCIAL_ENGINEERING`, `UNWANTED_SOFTWARE`, `SOCIAL_ENGINEERING_EXTENDED_COVERAGE` |
+| `uri` | URL to check |
+| `key` | API key (required) |
+
+**Response (clean URL):** Empty threat object.
+
+**Response (flagged URL):**
+```json
+{
+  "threat": {
+    "threatTypes": ["MALWARE"],
+    "expireTime": "2026-04-01T00:00:00Z"
+  }
+}
+```
+
+**Use for SEO:** Check if pages are flagged (could explain deindexing), verify competitor safety, audit outbound links.
+
+**Quota:** 6,000 QPM. 100,000/month free tier. Requires billing enabled on GCP project.