Google Search Console API - automatyzacja raportów i analiz SEO

Search Analytics udostępnia m.in. kliknięcia, wyświetlenia, CTR i średnią pozycję. Możesz grupować dane według daty, strony, zapytania, kraju czy urządzenia. Odrębnie wybierasz typ wyników, np. web, image albo discover. To pozwala zbudować raport odpowiadający pytaniu biznesowemu, zamiast eksportować wszystkie możliwe kombinacje.

API nie jest sposobem na ujawnienie ukrytych zapytań użytkowników. Google w dokumentacji query zaznacza:

Dokładniejszy podział może oznaczać mniej kompletną sumę danych. Porównuj wyniki z panelem przy tych samych filtrach i sposobie agregacji. Kliknięcia z GSC nie muszą być równe sesjom GA4, a średnia pozycja nie jest jednym stałym miejscem dla wszystkich użytkowników.

Search Console API obejmuje również metody modyfikujące, np. obsługę map witryny. Ten poradnik dotyczy odczytu. Indexing API jest oddzielną usługą o ograniczonym zastosowaniu do ofert pracy i określonych transmisji wideo. Nie służy do masowego zgłaszania zwykłych artykułów czy stron usługowych.

Potrzebujesz projektu Google Cloud z włączonym Search Console API oraz tożsamości, która ma dostęp do właściwej usługi w GSC. Samo włączenie API nie nadaje dostępu do cudzych danych.

Możliwe są dwa typowe warianty:

• OAuth użytkownika, który świadomie autoryzuje aplikację.
• Konto usługi przeznaczone do konkretnego procesu, dodane do właściwej usługi Search Console.

Autoryzacja GSC przewiduje zakres odczytu `https://www.googleapis.com/auth/webmasters.readonly`. Nie wybieraj szerszych uprawnień tylko dlatego, że pojawiły się w przypadkowym przykładzie. Konto usługi nie musi być właścicielem domeny do samego raportowania.

OAuth dla aplikacji serwerowych obsługuje dostęp offline i odświeżanie tokenu. Nie wymaga więc codziennego ręcznego logowania. Trzeba jednak bezpiecznie przechowywać token odświeżający i obsłużyć jego unieważnienie.

Sekrety pozostają po stronie serwera lub w prywatnym środowisku wykonania. Nie trafiają do kodu strony, repozytorium, publicznych logów ani arkusza z wynikami. Gdy środowisko zapewnia tożsamość usługi bez pliku klucza, korzystaj z tego mechanizmu. Jeśli używasz pliku JSON, trzymaj go poza katalogiem publikowanym i ogranicz dostęp do niego.

Przykład pobiera jeden zakończony dzień i zapisuje dostępne wiersze stron do lokalnego CSV. Nie zmienia ustawień GSC. Najpierw zainstaluj biblioteki w swoim środowisku:

python -m pip install google-api-python-client google-auth

Kod korzysta z Application Default Credentials. Przed uruchomieniem skonfiguruj autoryzowaną tożsamość w środowisku: np. konto usługi przypisane do serwera albo zmienną `GOOGLE_APPLICATION_CREDENTIALS` wskazującą prywatny plik poświadczeń. Nie wklejaj zawartości tego pliku do skryptu. Tożsamość musi mieć dostęp do podanej usługi GSC.

import csv
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

import google.auth
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]
SITE = "sc-domain:example.com"  # zastąp swoją usługą GSC
day = (
    datetime.now(ZoneInfo("America/Los_Angeles")).date()
    - timedelta(days=3)
).isoformat()

credentials, _ = google.auth.default(scopes=SCOPES)
client = build("searchconsole", "v1", credentials=credentials)
result = client.searchanalytics().query(
    siteUrl=SITE,
    body={
        "startDate": day,
        "endDate": day,
        "dimensions": ["page"],
        "type": "web",
        "dataState": "final",
        "rowLimit": 25000,
        "startRow": 0,
    },
).execute()

rows = result.get("rows", [])
with open("gsc-pages.csv", "w", encoding="utf-8", newline="") as file:
    writer = csv.writer(file)
    writer.writerow(["date", "page", "clicks", "impressions", "ctr", "position"])
    for row in rows:
        writer.writerow([
            day, row["keys"][0], row["clicks"],
            row["impressions"], row["ctr"], row["position"]
        ])
print(f"Zapisano {len(rows)} wierszy do gsc-pages.csv")

Podstaw własne SITE. Dla usługi domenowej będzie to `sc-domain:twojadomena.pl`, a dla URL-prefix np. `https://twojadomena.pl/`, z protokołem i końcowym ukośnikiem. To nazwa usługi, nie dowolny adres podstrony.

Daty są liczone w strefie GSC, a `dataState=final` ogranicza wynik do danych zakończonych. Wybranie dnia sprzed trzech dni nie gwarantuje istnienia danych. Pusta lista może być poprawna. Skrypt nie drukuje tokenu; nie udostępniaj też pliku CSV publicznie bez oceny zawartości. Na systemie bez bazy stref czasowych może być potrzebny pakiet `tzdata`.

Pojedyncze wywołanie powyżej zwraca pierwszą partię, a nie kompletne archiwum. Jeśli otrzymasz 25000 wierszy, kolejną partię pobierzesz z tymi samymi parametrami i `startRow=25000`. Zwiększaj offset o wielkość partii, aż odpowiedź nie zawiera kolejnych wierszy.

Google opisuje limit danych: maksymalnie 50000 wierszy dziennie na typ wyszukiwania, uporządkowanych według kliknięć. Dodatkowe filtry nie są obietnicą odzyskania każdej pominiętej frazy. Nie przedstawiaj sumy z tabeli szczegółowej jako pełnej sumy całej usługi.

Zapisuj parametry eksportu: usługę, dzień, typ, wymiary, filtry i moment odczytu. Przy powtórnym uruchomieniu zastępuj tę samą partię albo używaj stabilnego klucza rekordu. Bez tego codzienny harmonogram może wielokrotnie dopisywać te same wiersze.

Archiwum zaczyna działać od danych, które faktycznie zapisałeś. Nie odzyska informacji niedostępnych już w GSC. Jeśli potrzebujesz pomocy z zaplanowaniem takiego procesu, sprawdź automatyzacje raportowania. Najpierw ustal, na jakie pytanie raport ma odpowiadać i kto będzie go czytał.

W cyklicznym raporcie rozdziel dane zakończone od świeżych. Aktualne API obsługuje `dataState=all`, a dla wymiaru godzinowego `hourly_all`. Takie dane mogą się jeszcze zmieniać. Metadane `first_incomplete_date` i `first_incomplete_hour` pomagają wskazać granicę niepełnego okresu.

Nie uruchamiaj alarmu o utracie ruchu tylko dlatego, że dzisiejszy częściowy wynik jest niższy od całej wczorajszej doby. Porównuj odpowiednie okresy, uwzględniaj dni tygodnia i sezonowość. Zapisz także sytuację, gdy eksport nie doszedł do skutku; brak rekordu nie powinien automatycznie oznaczać zera kliknięć.

Na początek wystarczy harmonogram zapisujący wynik i status wykonania. Powiadomienia można dodać po sprawdzeniu, czy reguły nie generują przypadkowych alarmów. Nie ma konieczności kupowania konkretnego VPS ani używania wyłącznie jednego języka.

Apps Script może wywoływać API bezpośrednio z odpowiednią autoryzacją. Lista zaawansowanych usług Google nie potwierdza jednak usługi SearchConsole, którą można po prostu dopisać do projektu. Jeśli wykorzystujesz zewnętrzny dodatek do Arkuszy, sprawdź jego autora, dostęp do danych i aktualne warunki.

URL Inspection API pokazuje stan wersji adresu znanej indeksowi Google. Nie wykonuje testu działającej strony na żywo i nie prosi o indeksowanie. Wybieraj adresy ważne dla firmy: ofertę, kluczowe kategorie i strony po istotnych zmianach.

Wynik może pomóc rozpoznać status indeksowania, ostatnie znane pobranie czy kanoniczny adres wybrany przez Google. Interpretuj go razem z publiczną odpowiedzią strony i jej konfiguracją. Sama zmiana statusu nie wskazuje jeszcze przyczyny.

Opis odpowiedzi inspekcji oznacza `mobileUsabilityResult` jako wycofany. Nie buduj nowego raportu mobilności na tym polu. Podobnie zasób Sitemaps oznacza `contents[].indexed` jako deprecated. Liczba przesłanych URL nie jest tym samym co aktualna liczba stron w indeksie.

Jeśli dopiero poznajesz raporty, zacznij od przewodnika Search Console. Przy problemie obejmującym wiele typów stron właściwy może być audyt cyfrowy, który połączy dane API z kontrolą samej witryny.

Masowy eksport GSC jest osobnym sposobem codziennego przekazywania danych do BigQuery. Warto go rozważyć, kiedy potrzebujesz długiej historii i bardziej rozbudowanych analiz. Nie jest konieczny do pierwszego raportu małej strony.

Instrukcja uruchomienia wskazuje, że pierwszy eksport może nastąpić do 48 godzin po poprawnej konfiguracji i obejmuje dzień eksportu. Nie ma automatycznego uzupełnienia całej wcześniejszej historii. Starsze dostępne dane pobiera się osobno.

Dokumentacja tabel opisuje pole `is_anonymized_query`. Treść takich zapytań nie zostaje ujawniona. Eksport nie omija ochrony prywatności. Wiersze wymagają agregacji, więc proste policzenie rekordów nie jest liczbą wyszukiwań.

Przed wdrożeniem ustal miejsce przechowywania danych, retencję, uprawnienia i sposób ograniczania kosztów zapytań. Nie zakładaj z góry zerowego rachunku. Połączenie z GA4 na poziomie stron może być użyteczne, ale nie tworzy wiarygodnego przychodu przypisanego do każdej frazy z GSC.

Limity Search Console API obejmują kilka niezależnych ograniczeń. Search Analytics ma 1200 wywołań na minutę na usługę i użytkownika oraz limit obciążenia krótkoterminowego i dziennego. Inspekcja ma 2000 wywołań dziennie i 600 na minutę na usługę.

Grupowanie i filtrowanie równocześnie według strony oraz zapytania jest bardziej kosztowne. Długi zakres dat także zwiększa obciążenie. Nie pobieraj stale tych samych miesięcy, jeśli potrzebujesz tylko nowych dni.

Przy 401 lub 403 przeczytaj treść odpowiedzi i sprawdź tożsamość, zakres dostępu, włączenie API oraz poprawność SITE. Nie rozwiązuj problemu przez nadawanie wszystkim roli właściciela. Dla przejściowych błędów sieci lub serwera stosuj ograniczone ponowienia z rosnącym odstępem. Przekroczenie dziennego limitu wymaga odłożenia pracy, nie szybkiej pętli.

Proces jest gotowy, gdy ponowne wykonanie nie dubluje danych, niepełny dzień jest oznaczony, błędy są widoczne, a pliki wynikowe nie ujawniają sekretów. Wnioski o treści i widoczności można następnie wykorzystać w pozycjonowaniu SEO. Na pierwszy kontakt wystarczy adres strony i opis raportu, który chcesz otrzymywać. Parametry techniczne ustalimy później.

• Search Console API pricing: czy API jest bezpłatne i jakie ma limity?
• Google Narzędzia dla webmasterów i słowa kluczowe: praktyczny przewodnik po GSC
• Google Search Console API i MCP: jak połączyć dane SEO z asystentem AI
• 3 darmowe narzędzia Google do analizy rynku i trendów oraz ich ograniczenia