CommunityRecherche & Datenanalysegithub.com

google-search-console-api

Arbeitet mit der Google Search Console API (searchconsole v1 / webmasters v3) – Search-Analytics-Abfragen, URL-Inspektion, Sitemaps und Sites – und bleibt innerhalb der Kontingente.

Was ist google-search-console-api?

Dieses Skill ermöglicht Entwicklern und SEO-Fachleuten den programmatischen Zugriff auf die Google Search Console über die API. Es deckt die vier Kernbereiche Search Analytics (Performance-Daten), URL-Inspektion, Sitemaps und Sites-Liste ab. Der Fokus liegt auf der effizienten und vollständigen Datenextraktion unter Beachtung der strikten API-Kontingente (Quotas), insbesondere der Lastkontingente für Search Analytics (z. B. 1.200 QPM pro Site, 2.000 URL-Inspektionen pro Tag). Das Skill enthält detaillierte Anleitungen zur Authentifizierung (OAuth 2.0, Service-Accounts), zur Paginierung (bis zu 25.000 Zeilen pro Abfrage), zur korrekten Berechnung von Metriken (CTR, Position) und zur Fehlerbehandlung (z. B. 403/429-Fehler). Es unterstützt die gängigen Programmiersprachen über Google-Client-Bibliotheken und bietet ein eigenes CLI-Skript in Python. Das Skill ist besonders nützlich für die Erstellung von Dashboards, Data-Warehouses oder regelmäßigen Sync-Jobs, die über die Grenzen der Search-Console-UI hinausgehen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nimajafari/google-search-console-api-skill/tree/main/skills/google-search-console-api

Installed? Explore more Recherche & Datenanalyse skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Google Search Console API

Die Search Console API bietet programmatischen Zugriff auf die meisten Funktionen der Google Search Console: den Performance-Bericht (Search Analytics), URL-Inspektion, Sitemaps und die Liste der Properties (Sites). Es handelt sich um eine REST/JSON-API. Jeder Aufruf benötigt OAuth 2.0 und einen Benutzer (oder Service-Account) mit Search Console-Berechtigung für die Property.

Die Herausforderung besteht nicht darin, einen Aufruf zu tätigen, sondern darin, vollständige, korrekte Daten zu erhalten, ohne das Kontingent zu sprengen. Darum geht es in diesem Skill hauptsächlich.

Wann dieses Skill verwendet werden sollte

  • Extrahieren von Performance-Daten (Klicks, Impressionen, CTR, Position) für Analysen, Dashboards, Data Warehouses oder SEO-Untersuchungen.
  • Überprüfung des Index-Status, der kanonischen Auswahl, des Robots-/Noindex-Status oder der Gültigkeit von Rich-Snippets für URLs in großem Umfang.
  • Auflisten von Properties und Berechtigungen, Auflisten oder Einreichen von Sitemaps.
  • Entwerfen eines geplanten Sync-Jobs oder Beheben eines Jobs, der auf quotaExceeded stößt, Zeilen vermisst oder Zahlen zurückgibt, die nicht mit der Benutzeroberfläche übereinstimmen.

Nicht von dieser API abgedeckt: Der Page-Indexing-Report (Coverage), Links, Core Web Vitals, Crawl-Statistiken, manuelle Aktionen, Entfernungen und die Schaltfläche „Indexierung anfordern". Für Feld-Core-Web-Vitals verwenden Sie die CrUX-API; für Bulk-Raw-Performance-Daten auf großen Websites verwenden Sie den Search Console Bulk-Datenexport nach BigQuery; die separate Indexing-API unterstützt nur JobPosting / BroadcastEvent-Seiten.

Die vier Dienste

DienstMethodeHTTPBereich (min.)
Search Analyticssearchanalytics.queryPOST /webmasters/v3/sites/{siteUrl}/searchAnalytics/querywebmasters.readonly
URL InspectionurlInspection.index.inspectPOST /v1/urlInspection/index:inspectwebmasters.readonly
Sitemapslist / getGET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}]webmasters.readonly
Sitemapssubmit / deletePUT / DELETE …/sitemaps/{feedpath}webmasters
Siteslist / getGET /webmasters/v3/sites[/{siteUrl}]webmasters.readonly
Sitesadd / deletePUT / DELETE /webmasters/v3/sites/{siteUrl}webmasters

Stamm-URL: https://searchconsole.googleapis.com/ (aktuelles Discovery-Dokument, Dienst searchconsole v1). Die älteren Pfade https://www.googleapis.com/webmasters/v3/... werden in der Google-Dokumentation weiterhin verwendet und funktionieren weiterhin für die Ressourcen webmasters/v3.

Bereiche: https://www.googleapis.com/auth/webmasters.readonly (schreibgeschützt) und https://www.googleapis.com/auth/webmasters (lesen/schreiben). Fordern Sie schreibgeschützt an, es sei denn, die Aufgabe erfordert wirklich das Einreichen/Löschen von Sitemaps oder das Hinzufügen/Entfernen von Sites.

Property-Identifikatoren (siteUrl) – die häufigste Ursache für 403/404-Fehler

  • Domain-Property: sc-domain:example.com
  • URL-Präfix-Property: https://www.example.com/ – Schema, Host und nachgestellter Schrägstrich müssen exakt dem in der Search Console entsprechen.
  • In Pfaden müssen siteUrl und feedpath vollständig URL-kodiert sein (https%3A%2F%2Fwww.example.com%2F, sc-domain%3Aexample.com). Client-Bibliotheken erledigen dies für Sie; rohes HTTP nicht.
  • Beginnen Sie immer mit einem Aufruf von sites.list und verwenden Sie einen siteUrl genau wie zurückgegeben. siteUnverifiedUser kann keine Daten lesen.

Kontingente – vor dem Schreiben einer Schleife lesen

Ausführliche Details und ein Budgetierungs-Arbeitsblatt: references/LIMITS.md.

Search Analytics

  • QPM-Grenzen: 1.200 QPM pro Site, 1.200 QPM pro Benutzer, 40.000 QPM und 30.000.000 QPD pro Projekt. Beispiel: Ein Benutzer, der 3 Sites abfragt, erhält 1.200 QPM kombiniert; zwei Benutzer auf einer Site teilen sich 1.200 QPM.
  • Lastkontingent (dasjenige, das tatsächlich zuschlägt): interne Kosten einer Abfrage, verfolgt in 10-Minuten- (kurzfristig) und 1-Tages- (langfristig) Fenstern. Die Kosten steigen mit:
    • Gruppierung/Filterung nach page oder query (beide zusammen sind am teuersten),
    • der Länge des Datumsbereichs (6 Monate ≫ 1 Tag),
    • dem erneuten Abfragen bereits vorhandener Daten.
  • Das Überschreiten einer dieser Grenzen gibt denselben quotaExceeded -Fehler zurück. Kurzfristig: 15 Minuten warten und wiederholen. Wenn eine einzelne Abfrage in einem 10-Minuten-Fenster weiterhin fehlschlägt, ist das langfristige (tägliche) Lastkontingent überschritten – Kosten reduzieren; ein erneuter Versuch hilft bis morgen nicht.

URL Inspection: 2.000 QPD und 600 QPM pro Site; 10.000.000 QPD und 15.000 QPM pro Projekt. 2.000 pro Tag pro Property sind die eigentliche Obergrenze – Stichproben planen, nicht planen „jede URL inspizieren".

Alles andere (Sites, Sitemaps): 20 QPS und 200 QPM pro Benutzer; 100.000.000 QPD pro Projekt.

Batching spart kein Kontingent: Ein Batch von n Aufrufen zählt als n Anfragen. Batching spart nur HTTP-Overhead. Aktuelle Nutzung: Google Cloud-Konsole → APIs & Dienste → Search Console API → Kontingente.

Search Analytics: Vollständige, korrekte Daten abrufen

Vollständiges Anfrage-/Antwort-Schema und Rezepte: references/SEARCH-ANALYTICS.md.

Das empfohlene Muster (aus Googles Leitfaden „Alle Ihre Daten")

  1. Aktualität zuerst prüfen. Fragen Sie die letzten ~10 Tage ab, gruppiert nur nach date – keine Filter, keine anderen Dimensionen. Tage ohne Daten fehlen einfach. Endgültige Daten liegen typischerweise 2–3 Tage zurück.
  2. Einen Tag nach dem anderen abfragen (startDate == endDate), einmal pro Tag, für jeden benötigten type. Eine tägliche Ein-Tages-Abfrage sollte Ihr tägliches Kontingent nicht überschreiten; ein 16-Monats-Bereich, gruppiert nach Seite + Abfrage, wird es tun.
  3. Ergebnisse durchblättern: rowLimit maximal 25.000 (Standard 1.000), startRow um 25.000 erhöhen, bis eine Seite weniger Zeilen als angefordert oder 0 Zeilen zurückgibt.
  4. Finalisierte Historie nie erneut abrufen. Speichern Sie sie; holen Sie nur neue Tage (plus erneutes Abrufen der letzten nicht-finalisierten Tage, wenn Sie dataState: "all" verwenden).
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
{
  "startDate": "2026-11-14",
  "endDate":   "2026-11-14",
  "dimensions": ["page", "query", "country", "device"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

Harte Datenlimits, die Sie Stakeholdern erklären müssen

  • Die API gibt obere Zeilen zurück, nicht alle Zeilen: höchstens 50.000 Zeilen pro Tag pro Suchtyp (sortiert nach Klicks), unabhängig von der Paginierung.
  • Gruppierung/Filterung nach page und/oder query lässt einige Daten weg (um die Berechnung begrenzt zu halten), und anonymisierte seltene Abfragen werden nie zurückgegeben. Die Summe der Zeilen < Property-Gesamtsumme. Für genaue Gesamtwerte fragen Sie ohne die Dimensionen page/query ab.
  • Die Summen unterscheiden sich je nach Aggregation: byProperty (pro Property dedupliziert) vs byPage (pro kanonischer URL). Wenn Sie nach page gruppieren oder filtern, ist byProperty nicht erlaubt – verwenden Sie auto.
  • Daten sind in Pacific Time (America/Los_Angeles), nicht UTC.
  • Die Datenaufbewahrungsdauer für Performance-Daten in der Search Console beträgt etwa 16 Monate. Speichern Sie sie, wenn Sie einen längeren Verlauf benötigen.

Korrekte Metrik-Berechnung

  • CTR einer Gruppe = sum(clicks) / sum(impressions). Niemals CTRs mitteln.
  • Position einer Gruppe = Impressions-gewichtet: sum(position × impressions) / sum(impressions). Niemals Positionen mitteln.
  • position ist die durchschnittliche oberste Position (1-basiert); niedriger ist besser.

Wichtige Anfragefelder (Kurzreferenz)

  • dimensions: date, hour, query, page, country (ISO 3166-1 alpha-3, klein geschrieben in Ergebnissen, z. B. usa), device (DESKTOP/MOBILE/TABLET), searchAppearance, brandedClassification.
  • type: web (Standard), image, video, news (News-Tab), googleNews (news.google.com + App), discover, webMultimodal (Lens / Circle to Search / Bild-Uploads). searchType ist der veraltete Alias.
  • dimensionFilterGroups[].filters[]: {dimension, operator, expression}; Operatoren equals (Standard, Groß-/Kleinschreibung für Seite/Abfrage), notEquals, contains, notContains, includingRegex, excludingRegex (RE2). Gruppen werden UND-verknüpft; nur groupType: "and" wird unterstützt.
  • dimensionFilterGroups[].filterLists[]: Mehrfachwert-Exact-Match für country / device ({"dimension":"country","expressions":["usa","can"]}). Dieselbe Dimension kann nicht sowohl in filters als auch in filterLists gefiltert werden.
  • aggregationType: auto (Standard), byPage, byProperty (nicht für discover/googleNews), byNewsShowcasePanel.
  • dataState: final (Standard), all (enthält frische, noch nicht endgültige Daten), hourly_all (erforderlich für die Dimension hour; etwa 10 Tage verfügbar). Die Antwort metadata.firstIncompleteDate / firstIncompleteHour markiert, wo sich Zahlen noch ändern können.

Fallstricke

  • Search appearance ist zweistufig: Fragen Sie mit searchAppearance als einziger Dimension ab, um Typen aufzulisten, filtern Sie dann searchAppearance equals <TYPE> und fügen Sie andere Dimensionen hinzu – eine Abfrage pro Typ.
  • brandedClassification (BRANDED / NON_BRANDED): nur equals; kann nicht mit einem query-Filter in derselben Anfrage kombiniert werden; Daten ab 2026-02-21 und nur für Top-Level-Properties mit ausreichendem Volumen.
  • Ergebnisse werden nach Klicks absteigend sortiert, außer bei Gruppierung nach date (Datum aufsteigend). Gleichstände sind willkürlich – verlassen Sie sich nicht auf die Reihenfolge zur Deduplizierung.
  • Ein außerhalb des Bereichs liegender startRow gibt 200 mit null Zeilen zurück, keinen Fehler. Daten genau an einer 25.000-Grenze geben eine leere nächste Seite zurück.
  • rows ist nicht vorhanden (nicht []), wenn keine Daten vorhanden sind.

URL Inspection

Vollständiges Schema, Aufzählungen und eine Triage-Tabelle: references/URL-INSPECTION.md.

POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.example.com/page", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }
  • Meldet nur die indexierte Version. Es kann keine Live-URL testen und keine Indexierung anfordern.
  • inspectionUrl muss unter siteUrl liegen.
  • Lesen Sie indexStatusResult: verdict (PASS = gültig, NEUTRAL = ausgeschlossen, FAIL = Fehler), coverageState (die menschenlesbare Zeichenfolge, z. B. „Eingereicht und indexiert"), robotsTxtState, indexingState, pageFetchState, lastCrawlTime, googleCanonical vs userCanonical, crawledAs.
  • Das nützlichste Bulk-Signal ist googleCanonical != userCanonical (Google hat ein anderes Canonical gewählt).
  • mobileUsabilityResult ist veraltet. ampResult / richResultsResult fehlen, wenn nicht zutreffend.
  • Budget: 2.000/Tag/Property. Priorisieren Sie eine Stichprobe: Top-Seiten nach Klicks, kürzlich geänderte Vorlagen, eine URL pro Vorlage/Muster, URLs aus neuen Sitemaps.

Sites und Sitemaps

Siehe references/SITES-AND-SITEMAPS.md. sites.list → siteEntry[] {siteUrl, permissionLevel} mit siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser. sitemaps.list → sitemap[] mit path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, errors, warnings, contents[].submitted (contents[].indexed ist veraltet – nicht melden). submit / delete benötigen keinen Body und benötigen den Lese-/Schreibbereich. Dies sind Schreibvorgänge. Bestätigen Sie dies mit dem Benutzer, bevor Sie sie aufrufen.

Authentifizierung und Einrichtung

Schritt für Schritt, plus Installationszeilen für Bibliotheken für jede Sprache: references/AUTH-AND-SETUP.md.

  1. Google Cloud-Projekt erstellen/auswählen → Google Search Console API aktivieren.
  2. Anmeldeinformationen auswählen:
    • Installierter/Desktop-OAuth-Client: für einen Menschen, der Skripte lokal ausführt; der Benutzer stimmt in einem Browser zu und Sie speichern das Refresh-Token.
    • Service-Account: für unbeaufsichtigte Jobs. Dann fügen Sie die Service-Account-E-Mail als Benutzer der Property in der Search Console hinzu (Einstellungen → Benutzer und Berechtigungen). Eingeschränkt reicht zum Lesen; Besitzer/Vollzugriff ist zum Schreiben erforderlich. Ohne diesen Schritt gibt jeder Aufruf 403 zurück.
    • API-Schlüssel werden für diese Ressourcen nicht akzeptiert; OAuth 2.0 ist das einzige unterstützte Protokoll.
  3. Verwenden Sie eine Client-Bibliothek (empfohlen) – z. B. Python google-api-python-client mit build("searchconsole", "v1", credentials=creds), Node googleapis mit google.searchconsole("v1").
from google.oauth2 import service_account
from googleapiclient.discovery import build

creds = service_account.Credentials.from_service_account_file(
    "sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)

resp = gsc.searchanalytics().query(siteUrl="sc-domain:example.com", body={
    "startDate": "2026-11-14", "endDate": "2026-11-14",
    "dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", [])   # nicht vorhanden, wenn leer

Drucken, protokollieren oder committen Sie niemals Token, Client-Geheimnisse oder Service-Account-Schlüssel.

Fehler und Wiederholungen

Vollständige Zuordnung: references/ERRORS.md.

SymptomUrsacheAktion
401 authError / expiredschlechtes/abgelaufenes TokenToken erneuern; Bereiche prüfen
403 insufficientPermissions / "User does not have sufficient permission for site"falsche siteUrl-Form oder der Prinzipal ist kein Benutzer der Propertysites.list, exakten siteUrl verwenden; Service-Account in Search Console hinzufügen
403 accessNotConfiguredAPI im Projekt nicht aktiviertSearch Console API aktivieren
403/429 rateLimitExceeded, userRateLimitExceededQPS/QPMexponentielle Backoff mit Jitter
403/429 quotaExceeded (Search Analytics)Lastkontingenteinmal 15 Min. warten; falls eine einzelne Abfrage immer noch fehlschlägt → langfristiges Lastkontingent: Datumsbereich verkleinern oder page/query weglassen, morgen fortsetzen
400 invalidParameter / badRequestfalsche Aufzählung, Datumsreihenfolge, gemischte filters/filterLists in derselben Dimension, byProperty mit pageAnfrage korrigieren; nicht wiederholen
500 / 503 backendErrorvorübergehendBackoff und Wiederholung (begrenzt)

Performance

references/BATCH-AND-PERFORMANCE.md: gzip (Accept-Encoding: gzip und ein User-Agent, der gzip enthält), Teilantworten über fields= (z. B. fields=rows(keys,clicks,impressions)), und HTTP-Batch (multipart/mixed, ≤ 1.000 Aufrufe, in beliebiger Reihenfolge ausgeführt, jeder Aufruf zählt weiterhin gegen das Kontingent).

Das Hilfsskript

scripts/gsc.py ist ein einzeiliges CLI, das nur die Python 3.9+ Standardbibliothek verwendet. Es schreibt Fortschritt nach stderr und Daten nach stdout (standardmäßig JSONL, oder CSV/JSON). Es paginiert, sp

Verwandte Skills