/google-search-console

name: google-search-console
description: "[RU: Google Search Console API, гугл серч консоль, вебмастер гугл, gsc] GSC (Webmasters) API v1 — OAuth 2.0 + service account, searchanalytics.query (dimensions, filter operators, 25k row cap + startRow pagination), urlInspection.index.inspect (2000/day cap), Sites + Sitemaps CRUD, Indexing API for JobPosting/BroadcastEvent only, ~2-3 day data lag. Use when: GSC, search console, webmasters api, urlInspection, URL-prefix vs Domain property. SKIP: Yandex Webmaster (→yandex-webmaster); GA4 (→google-analytics); Bing Webmaster (→bing-webmaster); generic Google auth (→google-cloud-auth); SERP scraping (→xmlstock)."
stacks:
  - google-search-console
  - seo
  - python
  - nodejs
tags:
  - seo
  - google
  - gsc
  - search-console
  - indexing
  - oauth
  - sitemaps
source: vechkasov-global-skills
risk: high-stakes

<!-- 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](../../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 (S