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
quotaExceededstöß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
| Dienst | Methode | HTTP | Bereich (min.) |
|---|---|---|---|
| Search Analytics | searchanalytics.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| URL Inspection | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| Sitemaps | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| Sitemaps | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| Sites | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| Sites | add / delete | PUT / 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
siteUrlundfeedpathvollstä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.listund verwenden Sie einensiteUrlgenau wie zurückgegeben.siteUnverifiedUserkann 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
pageoderquery(beide zusammen sind am teuersten), - der Länge des Datumsbereichs (6 Monate ≫ 1 Tag),
- dem erneuten Abfragen bereits vorhandener Daten.
- Gruppierung/Filterung nach
- 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")
- 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. - Einen Tag nach dem anderen abfragen (
startDate == endDate), einmal pro Tag, für jeden benötigtentype. Eine tägliche Ein-Tages-Abfrage sollte Ihr tägliches Kontingent nicht überschreiten; ein 16-Monats-Bereich, gruppiert nach Seite + Abfrage, wird es tun. - Ergebnisse durchblättern:
rowLimitmaximal 25.000 (Standard 1.000),startRowum 25.000 erhöhen, bis eine Seite weniger Zeilen als angefordert oder 0 Zeilen zurückgibt. - 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
pageund/oderquerylä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 Dimensionenpage/queryab. - Die Summen unterscheiden sich je nach Aggregation:
byProperty(pro Property dedupliziert) vsbyPage(pro kanonischer URL). Wenn Sie nachpagegruppieren oder filtern, istbyPropertynicht erlaubt – verwenden Sieauto. - 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. positionist 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).searchTypeist der veraltete Alias.dimensionFilterGroups[].filters[]:{dimension, operator, expression}; Operatorenequals(Standard, Groß-/Kleinschreibung für Seite/Abfrage),notEquals,contains,notContains,includingRegex,excludingRegex(RE2). Gruppen werden UND-verknüpft; nurgroupType: "and"wird unterstützt.dimensionFilterGroups[].filterLists[]: Mehrfachwert-Exact-Match fürcountry/device({"dimension":"country","expressions":["usa","can"]}). Dieselbe Dimension kann nicht sowohl infiltersals auch infilterListsgefiltert werden.aggregationType:auto(Standard),byPage,byProperty(nicht fürdiscover/googleNews),byNewsShowcasePanel.dataState:final(Standard),all(enthält frische, noch nicht endgültige Daten),hourly_all(erforderlich für die Dimensionhour; etwa 10 Tage verfügbar). Die Antwortmetadata.firstIncompleteDate/firstIncompleteHourmarkiert, wo sich Zahlen noch ändern können.
Fallstricke
- Search appearance ist zweistufig: Fragen Sie mit
searchAppearanceals einziger Dimension ab, um Typen aufzulisten, filtern Sie dannsearchAppearance equals <TYPE>und fügen Sie andere Dimensionen hinzu – eine Abfrage pro Typ. brandedClassification(BRANDED/NON_BRANDED): nurequals; kann nicht mit einemquery-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
startRowgibt 200 mit null Zeilen zurück, keinen Fehler. Daten genau an einer 25.000-Grenze geben eine leere nächste Seite zurück. rowsist 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.
inspectionUrlmuss untersiteUrlliegen.- Lesen Sie
indexStatusResult:verdict(PASS = gültig, NEUTRAL = ausgeschlossen, FAIL = Fehler),coverageState(die menschenlesbare Zeichenfolge, z. B. „Eingereicht und indexiert"),robotsTxtState,indexingState,pageFetchState,lastCrawlTime,googleCanonicalvsuserCanonical,crawledAs. - Das nützlichste Bulk-Signal ist
googleCanonical != userCanonical(Google hat ein anderes Canonical gewählt). mobileUsabilityResultist veraltet.ampResult/richResultsResultfehlen, 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.
- Google Cloud-Projekt erstellen/auswählen → Google Search Console API aktivieren.
- 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.
- Verwenden Sie eine Client-Bibliothek (empfohlen) – z. B. Python
google-api-python-clientmitbuild("searchconsole", "v1", credentials=creds), Nodegoogleapismitgoogle.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.
| Symptom | Ursache | Aktion |
|---|---|---|
401 authError / expired | schlechtes/abgelaufenes Token | Token erneuern; Bereiche prüfen |
403 insufficientPermissions / "User does not have sufficient permission for site" | falsche siteUrl-Form oder der Prinzipal ist kein Benutzer der Property | sites.list, exakten siteUrl verwenden; Service-Account in Search Console hinzufügen |
403 accessNotConfigured | API im Projekt nicht aktiviert | Search Console API aktivieren |
403/429 rateLimitExceeded, userRateLimitExceeded | QPS/QPM | exponentielle Backoff mit Jitter |
403/429 quotaExceeded (Search Analytics) | Lastkontingent | einmal 15 Min. warten; falls eine einzelne Abfrage immer noch fehlschlägt → langfristiges Lastkontingent: Datumsbereich verkleinern oder page/query weglassen, morgen fortsetzen |
400 invalidParameter / badRequest | falsche Aufzählung, Datumsreihenfolge, gemischte filters/filterLists in derselben Dimension, byProperty mit page | Anfrage korrigieren; nicht wiederholen |
500 / 503 backendError | vorübergehend | Backoff 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