Seo Google

Google SEO APIs

Shared Data Cache

Step 0 -- Check shared data cache:

Before gathering, check .seo-cache/ for reusable context from related SEO skills. Reference: ../seo/references/shared-data-cache.md for schemas and dependency map.

Check these cache files when present:

• .seo-cache/site-meta.json for domain, business type, industry, and crawl context
• .seo-cache/audit-scores.json for prior full-audit priorities
• .seo-cache/pages/{url-slug}/page-analysis.json for page-level context when a URL is provided

• If found: parse and use clearly valid fields (note "Using cached [X] from [date]")
• If missing, corrupt, or irrelevant: continue with fresh evidence
• If the user says "refresh" or "re-run": ignore cache reads and overwrite on write

Direct access to Google's own SEO data. Bridges the gap between crawl-based analysis (existing codex-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:

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

Config file: ~/.config/codex-seo/google-api.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

Always communicate the detected tier before running commands.

Quick Reference

---

PageSpeed + CrUX

/seo google 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.

/seo google crux <url>

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

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

/seo google 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

/seo google 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.

/seo google 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.

/seo google 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

/seo google sitemaps <property>

List submitted sitemaps with status, errors, warnings.

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

---

Indexing API

/seo google 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.

/seo google index-batch <file>

Batch submit URLs from a file. Tracks quota usage.

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

---

GA4 Traffic

/seo google ga4 [property-id]

Organic traffic report: daily 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.

/seo google ga4-pages [property-id]

Top organic landing pages ranked by sessions.

Script: python scripts/ga4_report.py --property <id> --report top-pages --json

---

YouTube (Video SEO)

YouTube mentions have the strongest AI visibility correlation (0.737). Free, API key only.

/seo google 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).

/seo google 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.

/seo google 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.

/seo google 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.

/seo google 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).

/seo google volume <keywords>

Search volume for specific keywords (comma-separated).

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

---

Supplementary

/seo google entity <query>

Knowledge Graph entity check. Verifies brand presence.

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

/seo google safety <url>

Web Risk API check for malware/social engineering flags.

Reference: references/supplementary-apis.md

/seo google quotas

Display rate limits table. Read references/rate-limits-quotas.md.

---

Reports

After any analysis command, offer to generate a PDF/HTML report.

/seo google report <type>

Generate a professional PDF report with charts and analytics.

Script: python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf

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 /seo google report <type>"

---

Rate Limits

Cross-Skill Integration

• seo-audit: Spawns seo-google agent for live CWV + indexation data (conditional)
• seo-technical: Uses pagespeed_check.py for real CWV field data
• seo-performance: CrUX field data supplements Lighthouse lab data
• seo-sitemap: GSC sitemap status shows real crawl/index coverage
• seo-content: GSC query data informs keyword targeting
• seo-geo: GSC search appearance data includes AI Overview references

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

Write to shared data cache

After completing all work, write a concise JSON summary to .seo-cache/ when the workflow produced durable findings. Use the schemas and naming rules in ../seo/references/shared-data-cache.md; include at least cache_type, analyzed_at, source URL/domain, key findings, issues, recommendations, and tool limitations. Add .seo-cache/ to .gitignore if it is missing.

Core Web Vitals Audit

URL/Origin: {target} Strategy: {strategy}

CrUX Field Data (28-day rolling average)

Real Chrome user experience data from the Chrome UX Report.

Collection Period: {collection_start} to {collection_end}

Lighthouse Lab Scores

CrUX History Trends (25-week)

{trends_table}

Top Opportunities

{opportunities_table}

Recommendations

{recommendations}

--- CrUX data updated daily ~04:00 UTC. 28-day rolling average. INP replaced FID as the responsiveness Core Web Vital on March 12, 2024. Generated {timestamp}.

Google Search Console Performance Report

Property: {property} Date Range: {start_date} — {end_date} Search Type: {search_type}

Summary

Top Queries

{queries_table}

Top Pages

{pages_table}

Quick Wins (Position 4-10, High Impressions)

These queries rank on page 1 but below position 3. A small ranking improvement could yield significant traffic gains.

{quick_wins_table}

Device Breakdown

{device_table}

--- Data freshness: Search Analytics has a 2-3 day lag. Data available for ~16 months. Generated {timestamp} via Google Search Console API.

URL Indexation Status Report

Property: {property} URLs Inspected: {total_urls}

Summary

Detailed Results

{results_table}

Canonical Mismatches

URLs where Google selected a different canonical than declared:

{canonical_mismatches_table}

Common Issues

{issues_table}

Rich Results Detected

{rich_results_table}

--- URL Inspection API: 2,000 inspections/day per site, 600/min. Generated {timestamp} via Google Search Console URL Inspection API.

Google API Authentication Setup

Overview

Three credential types serve different APIs:

Step 1: Create a Google Cloud Project

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

Step 2: Enable APIs

Navigate to APIs & Services > Library and enable:

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

3. Copy the key (starts with AIzaSy...)

Step 4: Create a Service Account

1. IAM & Admin > Service Accounts > Create Service Account 2. Name: codex-seo (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/codex-seo/service_account.json)

The JSON file looks like:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "[redacted service-account private key]",
  "client_email": "codex-seo@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 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 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

mkdir -p ~/.config/codex-seo

Save to ~/.config/codex-seo/google-api.json:

{
  "service_account_path": "~/.config/codex-seo/service_account.json",
  "api_key": "AIzaSy...",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

Property URL Formats

Step 8: Verify Setup

python scripts/google_auth.py --check

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: codex-seo@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:

OAuth Scopes Used

Troubleshooting

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

runReport Request

{
  "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

SEO-Relevant Metrics

Filter Expressions

String Filter

{
  "filter": {
    "fieldName": "sessionDefaultChannelGroup",
    "stringFilter": {
      "matchType": "EXACT",
      "value": "Organic Search"
    }
  }
}

Match types: EXACT, BEGINS_WITH, ENDS_WITH, CONTAINS, FULL_REGEXP, PARTIAL_REGEXP

Combining Filters

{
  "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

Up to 4 date ranges per request (for period-over-period comparison).

Token-Based Quotas

Set returnPropertyQuota: true to monitor consumption. Simple reports cost ~1-10 tokens; complex ones up to ~100.

Python Example

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

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`

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

Response:

{
  "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

Request a quota increase: Indexing API Quota Increase Form

Error Codes

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)

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/codex-seo/google-api.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

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)

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

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

One "unit" = 1,000 characters. Free tier resets monthly.

Enable the API

1. Go to 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.

PageSpeed Insights v5 + CrUX API Reference

Table of Contents

1. PageSpeed Insights v5 2. CrUX API (Daily) 3. CrUX History API (Weekly) 4. Core Web Vitals Thresholds

---

PageSpeed Insights v5

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

Parameters

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)

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

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": ["largest_contentful_paint", "interaction_to_next_paint", "cumulative_layout_shift"]
}

Available Metrics

Response

{
  "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:

{
  "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.

FID was fully removed from Chrome tools (CrUX, PSI, Lighthouse) on September 9, 2024. Never reference FID in outputs.

Google API Rate Limits & Quotas

Consolidated Quota Table

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

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.

Google Search Console API Reference

Table of Contents

1. Search Analytics API 2. URL Inspection API 3. Sitemaps API 4. Sites API

---

Search Analytics API

Endpoint: POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query

Request Body

Dimension Filters

{
  "dimensionFilterGroups": [{
    "filters": [{
      "dimension": "query",
      "operator": "contains",
      "expression": "seo"
    }]
  }]
}

Operators: contains, equals, notContains, notEquals, includingRegex, excludingRegex

• Regex uses RE2 syntax, max 4096 characters

Response

{
  "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

{
  "inspectionUrl": "https://example.com/page",
  "siteUrl": "sc-domain:example.com",
  "languageCode": "en"
}

Response Fields

`indexStatusResult`:

`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

Sitemap Resource

---

Sites API

Base: https://www.googleapis.com/webmasters/v3/sites

Property Resource

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

Response:

{
  "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

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

Response (clean URL): Empty threat object.

Response (flagged URL):

{
  "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.

YouTube Data API v3 Reference

YouTube mentions have the strongest correlation with AI visibility (0.737 per GEO research). This API provides authoritative YouTube data directly from Google.

Endpoints Used

Daily Quota

Default: 10,000 units/day (free). This allows:

• ~100 searches per day, OR
• ~10,000 video/channel lookups per day

Data Available

Video Search

• Title, channel, channel ID, published date
• Description (first 300 chars), thumbnail URL
• Views, likes, comments count, duration

Video Details

• Full description, tags, category ID
• Duration, definition (HD/SD), has captions
• Topic categories (Wikipedia URLs)
• Views, likes, comments, favorites
• Top 10 relevant comments with likes

Channel Info

• Title, description, custom URL
• Subscriber count, video count, total views
• Country, published date, thumbnail

Authentication

API key only (read-only public data). No OAuth needed.

Enable the API

1. Go to console.cloud.google.com/apis/library 2. Search for "YouTube Data API v3" 3. Click Enable

No billing required. The API key you already have for PSI/CrUX works.