Google Search Console

<!-- versions:start -->

Version Requirements (May 2026)

Primary pins:

• Search Console API: v1 (Webmasters v3 endpoints stable; URL Inspection on searchconsole.googleapis.com/v1)
• Indexing API: v3 (JobPosting + BroadcastEvent only)
• Python: 3.14.x
• Node.js: 24.x (Active LTS)

Source of truth: STACK_VERSIONS.md — verified 2026-08-24

<!-- versions:end -->

Usage

Loaded automatically when the description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Pull search analytics data (queries, pages, countries, devices, searchAppearance) for content planning, position audits, or client reports.
• Programmatically check URL index status via urlInspection.index.inspect (verdict, coverageState, lastCrawlTime, googleCanonical vs userCanonical, mobileUsability, AMP, richResults).
• Submit / delete / list sitemap.xml for an added property (/webmasters/v3/sites/{siteUrl}/sitemaps).
• Manage sites list (URL-prefix property vs Domain property sc-domain:example.com) and check permission level.
• Notify Google about a new or deleted page via Indexing API — only for JobPosting or BroadcastEvent. Regular pages will not work and abuse risks revoke.
• Build a Python (google-api-python-client + google-auth) or Node.js (googleapis) client with service account and automatic 25k-cap pagination.
• Schedule a daily ETL of search analytics into PostgreSQL — (query, page, country, device, date) → clicks/impressions/ctr/position.
• Audit indexation on large sites via URL Inspection while respecting the 2000/day/property quota.

Do not use this skill when

• You need Yandex Webmaster — different provider, different property/sitemap model; → cascade yandex-webmaster.
• You need GA4 web analytics (sessions, users, events) — GSC only returns Google search data; → cascade google-analytics.
• You need Bing Webmaster Tools — separate Microsoft API.
• You need generic Google OAuth2 / service account patterns; → cascade google-cloud-auth.
• You need true SERP positions with real locale/device — GSC returns averaged impressions/position for queries already discovered; real SERP snapshot → cascade xmlstock.
• You expect a "list all my indexed URLs" endpoint — Google does not provide one; sample via Sitemaps + URL Inspection.
• You want to force-index regular pages with Indexing API — abuse-banned, alternative is sitemap + internal links + UI "Request Indexing".

Purpose

Google Search Console API (Webmasters v3 + URL Inspection v1) is the only official channel for Google organic data: queries, clicks, impressions, CTR, position, index status. This skill covers OAuth 2.0 (user + service account), Search Analytics query with filters and 25k pagination, URL Inspection with daily quota, Sites + Sitemaps CRUD, and — separately — Indexing API (with a strict JobPosting/BroadcastEvent warning).

This skill is high-stakes because:

1. URL Inspection 2000/day/property quota — a naive crawl of all URLs in one go ends in dailyLimitExceeded. Design with a rate limiter and prioritization (new/changed URLs first).
2. 25,000-row hard cap on Search Analytics responses. Without startRow pagination the long tail is silently lost — the classic "where are my queries?" bug.
3. Data freshness lag ~2-3 days. A request for "today" returns empty / incomplete. Use dataState: "final" (default) or know what all means.
4. Domain property vs URL-prefix — sc-domain:example.com aggregates all protocols/subdomains; https://www.example.com/ is only that exact prefix. Mixing them yields wrong numbers.
5. Service account cannot self-grant. Its email must be added manually in the GSC UI as a user with Restricted or Full permission. The API offers no bootstrap path.
6. Indexing API trap: the "speed up indexation" myth → ban. Supported types are JobPosting and BroadcastEvent (in VideoObject) only.
7. searchAppearance dimension cannot be combined with other dimensions in one request — separate call required.
8. Billing: GSC endpoints are free at reasonable scale, but exceeding QPM/QPD → 429 with reason quotaExceeded or dailyLimitExceeded. Backoff is mandatory.
9. OAuth refresh token expiry: tokens in apps stuck in "Testing" mode expire after 7 days — production requires OAuth verification.

The skill owns provider-domain knowledge: endpoints, dimension/filter semantics, freshness lag, quotas, and the billing-free-but-quota-limited model. Pure HTTP plumbing belongs in httpx / nodejs. Deeper auth belongs in google-cloud-auth.

Capabilities

Authentication — OAuth 2.0 (user) + Service Account

Two paths: (a) User OAuth 2.0 Authorization Code flow with refresh_token — for apps where the GSC owner logs in; scopes https://www.googleapis.com/auth/webmasters.readonly (read) or webmasters (full, includes sitemap submit). (b) Service Account JWT — for server-to-server; the service account email must be added as a user in the Search Console UI (Settings → Users and permissions → Add user). Without that, the API returns 403 Forbidden or 404 User does not have sufficient permission for site.

Full reference: references/setup.md

Property types — URL-prefix vs Domain

siteUrl comes in two shapes: URL-prefix (https://www.example.com/ — trailing slash mandatory, exact protocol) and Domain (sc-domain:example.com — aggregates all protocols/subdomains, DNS-verified). Their data does not match: a Domain property sees more impressions. For URL Inspection, siteUrl must match the property exactly.

Full reference: references/setup.md

Search Analytics — searchanalytics.query

POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query. Body: startDate, endDate (YYYY-MM-DD, Pacific Time), dimensions[] (date, hour, query, page, country, device, searchAppearance), type (web/discover/googleNews/news/image/video, default web), aggregationType (auto/byPage/byProperty/byNewsShowcasePanel), dimensionFilterGroups[] (groupType is always and; operators equals/contains/notEquals/notContains/includingRegex/excludingRegex), rowLimit (1-25000, default 1000), startRow (0+), dataState (final/all/hourly_all). Response: rows[].keys[] + clicks, impressions, ctr (0..1), position. Metadata: responseAggregationType, metadata.first_incomplete_date.

Full reference: references/search-analytics.md

25,000-row cap + startRow pagination

Hard cap = 25,000 rows per response. Full export: loop with rowLimit=25000 and increment startRow += 25000 until a response returns fewer rows than the limit (or zero — empty response means end). There is no next-page-token. Without pagination the tail is silently lost beyond the top 25k by clicks.

Full reference: references/search-analytics.md

Data freshness lag (~2-3 days)

Final data appears with a 2-3 day delay (up to 4 for the long tail). dataState: "final" (default) excludes incomplete days. dataState: "all" includes fresh, recomputable rows (fine for "yesterday" dashboards, bad for historical reports). metadata.first_incomplete_date in the response tells you when data may still change. Hourly data: dataState: "hourly_all" + dimensions: ["hour"].

Full reference: references/search-analytics.md

URL Inspection API — urlInspection.index.inspect

POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect. Body: inspectionUrl, siteUrl (must match the added property; URL-prefix needs trailing /), languageCode (BCP-47). Response is inspectionResult containing: indexStatusResult (verdict, coverageState, robotsTxtState, indexingState, lastCrawlTime, pageFetchState, googleCanonical, userCanonical, sitemap[], referringUrls[], crawledAs), ampResult, mobileUsabilityResult, richResultsResult. Quota: 2000/day/property and 600 QPM/property.

Full reference: references/url-inspection.md

Sites + Sitemaps CRUD

Sites: GET /webmasters/v3/sites (list), GET /sites/{siteUrl} (get), PUT /sites/{siteUrl} (add — attaches site to current user, not verification), DELETE /sites/{siteUrl}. Fields: siteUrl, permissionLevel (siteFullUser/siteOwner/siteRestrictedUser/siteUnverifiedUser). Sitemaps: GET /sites/{siteUrl}/sitemaps (list), GET /sites/{siteUrl}/sitemaps/{feedpath} (get; feedpath URL-encoded), PUT /sites/.../sitemaps/{feedpath} (submit), DELETE (unsubmit). Fields: path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type (sitemap/rssFeed/atomFeed/urlList/patternSitemap/notSitemap), warnings, errors, contents[].

Full reference: references/sites-and-sitemaps.md

Indexing API — JobPosting and BroadcastEvent ONLY

POST https://indexing.googleapis.com/v3/urlNotifications:publish. Body: { "url": "...", "type": "URL_UPDATED" | "URL_DELETED" }. WARNING: Google explicitly states it "can only be used to crawl pages with either JobPosting or BroadcastEvent (embedded in VideoObject)". Using it for regular pages is abuse → revoke and possible manual action. Batch up to 100 sub-requests via multipart.

WARNING: Service account must have Owner role in the GSC property — Full user is insufficient for the Indexing API. Re-share property with SA email as Owner if you get 403.

Full reference: references/indexing-api.md

Quotas — short-window and daily

Search Analytics: 1200 QPM per-site, 1200 QPM per-user, 40,000 QPM + 30,000,000 QPD per-project. URL Inspection: 600 QPM per-site, 2000 QPD per-site, 15,000 QPM + 10,000,000 QPD per-project. Other resources (Sites/Sitemaps): 20 QPS + 200 QPM per-user, 100,000,000 QPD per-project. Exceeding → 429 with reason quotaExceeded / userRateLimitExceeded / dailyLimitExceeded. Exponential backoff is required.

• Indexing API: 200 calls/day/project (default, raiseable via quota form); 600 QPM/project.

Full reference: references/rate-limits.md

Errors — 400/401/403/404/429/500

400 badRequest — invalid dimensions/dates. 401 authError — expired token, refresh. 403 forbidden — no permission on property or service account not added. 404 — siteUrl unknown to user. 429 — quota, backoff. 500/503 — transient, retry with jitter. Reason codes are in error.errors[].reason.

Full reference: references/errors.md

End-to-end API workflows

Auth bootstrap → Search Analytics query lifecycle → URL Inspection → Sitemaps → Indexing API caveat → Quota management → Daily ETL into PostgreSQL.

Full reference: references/workflow.md

Production clients — Python + Node.js

Drop-in templates: Python with google-api-python-client (service account from JSON), Python with raw httpx + JWT assertion for fine control, Node.js with googleapis. Pagination helper for 25k cap. URL Inspection batch worker with per-property quota tracker. PostgreSQL schema for daily snapshots.

Full reference: references/integration.md