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

GSC API to nie jeden interfejs, tylko zestaw endpointów, z których każdy rozwiązuje inny problem. Warto je znać, zanim zdecydujesz, co automatyzować.

Search Analytics API – dane o wydajności organicznej: kliknięcia, wyświetlenia, CTR, średnia pozycja. Filtrujesz po stronie, frazie, kraju, urządzeniu i typie wyszukiwania (web, image, video, news, discover). Maksimum 25 000 wierszy na request – zamiast 1000 widocznych w panelu. Dane sięgają 16 miesięcy wstecz, z opóźnieniem 2-3 dni.

URL Inspection API – status indeksowania konkretnych adresów. Czy strona jest w indeksie, kiedy ostatnio crawlowana, jaki kanoniczny URL wybrał Google, czy przeszła testy mobile usability i rich results. Limit: 2000 zapytań dziennie na właściwość. To podstawa masowego audytu indeksacji.

Indexing API – pozwala zgłosić Google nowy lub zmieniony URL do crawla i powiadomić o usunięciu strony. Oficjalnie wspiera tylko dane strukturalne JobPosting i BroadcastEvent, ale wiele zespołów używa go do szybszego komunikowania zmian. Limit domyślny: 200 zapytań dziennie. To jedyny endpoint, który pisze do Google – reszta tylko czyta.

Sitemaps API – zarządzanie mapami witryn: lista sitemap, statusy, błędy, data ostatniego przetworzenia, liczba zgłoszonych i zaindeksowanych URL-i. Przydatne, by automatycznie wykrywać, gdy Google przestaje widzieć część strony.

Czego API nie daje: danych w czasie rzeczywistym (opóźnienie 2-3 dni), danych starszych niż 16 miesięcy, pełnego raportu Index Coverage z panelu i metryk Core Web Vitals (do tego potrzebujesz osobnego PageSpeed Insights API lub CrUX API).

Jeśli dopiero zaczynasz, sprawdź nasz przewodnik po Google Search Console – podstawy przed automatyzacją.

Uwierzytelnianie to miejsce, gdzie najczęściej wszystko się wykłada. Do automatyzacji wybierz Service Account, nie OAuth – OAuth wymaga interaktywnego logowania w przeglądarce i odświeżania tokenów, co psuje skrypty z crona.

Krok 1: Google Cloud Console. Utwórz projekt i włącz dwie biblioteki: Google Search Console API oraz (jeśli planujesz zgłaszanie URL) Web Search Indexing API.

Krok 2: Service Account. Utwórz konto serwisowe, wygeneruj klucz JSON i pobierz plik. Ten plik to sekret – nie wrzucaj go do repozytorium git ani do publicznego bucketa. Trzymaj go w menedżerze sekretów lub poza katalogiem projektu.

Krok 3: Nadanie uprawnień. Skopiuj e-mail konta serwisowego (kończy się na .iam.gserviceaccount.com) i dodaj go jako użytkownika w GSC: Ustawienia > Użytkownicy i uprawnienia. Do raportowania wystarczy rola Ograniczony (odczyt). Do Indexing API potrzebujesz roli Właściciel.

Krok 4: Pierwsze zapytanie w Pythonie.

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

from google.oauth2 import service_account
from googleapiclient.discovery import build

credentials = service_account.Credentials.from_service_account_file(
    'credentials.json',
    scopes=['https://www.googleapis.com/auth/webmasters.readonly']
)
service = build('searchconsole', 'v1', credentials=credentials)

response = service.searchanalytics().query(
    siteUrl='https://twoja-strona.pl',
    body={
        'startDate': '2026-01-01',
        'endDate': '2026-03-01',
        'dimensions': ['query', 'page'],
        'rowLimit': 25000
    }
).execute()

Uwaga na format siteUrl: dla właściwości typu domena podajesz `sc-domain:twoja-strona.pl`, dla właściwości z prefiksem URL – pełny adres z protokołem i ukośnikiem na końcu. Pomyłka tutaj zwraca pustą odpowiedź bez błędu, co potrafi kosztować godzinę debugowania.

Nie każdy projekt potrzebuje serwera i crona. Jeśli chcesz lekkiego rozwiązania, Google Apps Script uruchamia kod po stronie Google za darmo i ma wbudowany harmonogram (triggery czasowe).

Apps Script łączy się z GSC przez Advanced Service Search Console, zapisuje wyniki prosto do Google Sheets i wysyła maile przez MailApp. Cały raport tygodniowy może żyć w jednym arkuszu, bez instalowania czegokolwiek lokalnie. Wada: limit czasu wykonania (6 minut na trigger w wersji darmowej) i trudniejsza obróbka dużych zbiorów.

Python wygrywa, gdy potrzebujesz cięższej analityki (pandas, numpy), integracji z bazą lub masowych zapytań z kontrolą równoległości. Apps Script wygrywa prostotą i zerową infrastrukturą.

Perspektywa KC Mobile: w naszych wdrożeniach monitoringu SEO zaczynamy zwykle od Apps Script lub darmowego dodatku do Sheets, a na Pythona i BigQuery przechodzimy dopiero, gdy klient ma kilkanaście właściwości albo chce trzymać historię dłużej niż 16 miesięcy. Najczęściej widzimy, że pierwszy realny zysk daje nie sam kod, tylko regularność – raz ustawiony cotygodniowy raport robi więcej niż piękny dashboard, do którego nikt nie zagląda.

API jest tylko narzędziem. Wartość pojawia się, gdy rozwiązuje konkretny problem operacyjny, a nie gdy istnieje samo dla siebie.

Raporty tygodniowe. Skrypt pobiera dane, porównuje z poprzednim okresem i wysyła zestawienie na e-mail lub Slack. Zamiast 30 minut ręcznego eksportu – zero minut, bo wszystko chodzi z harmonogramu.

Alerty na spadki pozycji. Monitorujesz 50-100 kluczowych fraz. Gdy średnia pozycja spada o więcej niż 3 oczka tydzień do tygodnia – leci alert. Reagujesz, zanim ruch zdąży zniknąć.

Analiza striking distance. Pobierasz frazy z pozycji 5-15 o dużej liczbie wyświetleń i niskim CTR. To strony, które wystarczy dopracować (meta title, opis, nagłówek), żeby złapać więcej kliknięć bez pisania nowego contentu – najtańszy możliwy wzrost.

Masowa inspekcja URL. Sprawdzasz status indeksacji setek lub tysięcy adresów jednym przebiegiem. Bezcenne po migracji, po dużych zmianach na stronie albo cyklicznie jako audyt.

Połączenie z GA4. Łączysz dane GSC (frazy, pozycje) z danymi GA4 (konwersje, przychód). Dowiadujesz się, które frazy organiczne realnie sprzedają, a nie tylko generują ruch. Na to pytanie sam panel GSC nigdy nie odpowie.

Archiwizacja historii. GSC trzyma dane 16 miesięcy, potem znikają bezpowrotnie. Regularny eksport do własnej bazy to jedyny sposób na pełną historię SEO – kluczowy przy analizie sezonowości rok do roku.

Prowadzisz to wszystko ręcznie? Sprawdź naszą ofertę pozycjonowania SEO – wdrażamy systemy monitoringu, które pracują w tle.

Są dwie drogi do długoterminowego składowania danych GSC i często myli się je ze sobą.

Bulk Data Export to natywna funkcja Google: konfigurujesz ją raz w ustawieniach GSC, wskazujesz projekt BigQuery i Google codziennie wrzuca tam surowe, niesamplowane dane (tabele searchdata_site_impression i searchdata_url_impression). To inny mechanizm niż API – nie odpytujesz Google, tylko Google sam wypycha dane do Twojej hurtowni. Zaleta: pełne dane bez limitu 25 000 wierszy. Koszt: płacisz BigQuery za składowanie i zapytania (orientacyjnie grosze miesięcznie przy małej witrynie, więcej przy dużych serwisach).

Search Analytics API plus własny ETL to alternatywa, gdy nie chcesz wiązać się z BigQuery albo wolisz PostgreSQL czy zwykłe Sheets. Skrypt pobiera dane przyrostowo (np. co noc za dzień sprzed 3 dni) i dopisuje do bazy.

Looker Studio (dawniej Data Studio) to warstwa wizualizacji na wierzchu. Ma natywny konektor do GSC dla szybkich dashboardów, ale ten konektor dziedziczy limity panelu. Po podpięciu Looker Studio do tabel BigQuery zdejmujesz te ograniczenia i budujesz raporty na pełnej historii.

W praktyce kombinacja Bulk Data Export do BigQuery plus Looker Studio na wierzchu to dziś najczystsza architektura dla większych witryn – masz surowe dane i czytelny raport bez ręcznego ETL.

Znajomość limitów oszczędza wieczorów z błędami 429. Oto najważniejsze progi i sposoby radzenia sobie z nimi.

Search Analytics API: ok. 1200 zapytań na minutę na użytkownika, maksimum 25 000 wierszy na request, dane z opóźnieniem 2-3 dni. Więcej niż 25k wierszy pobierzesz paginacją przez parametr `startRow`.

URL Inspection API: 2000 zapytań dziennie na właściwość i ok. 600 na minutę. Brak endpointu batch – każdy URL to osobny request, więc masowa inspekcja wymaga kolejkowania i kontroli tempa.

Indexing API: domyślnie 200 zapytań dziennie. Limit można zwiększyć wnioskiem, ale Google traktuje go restrykcyjnie.

Obsługa błędów i dobre praktyki:
- 429 (Too Many Requests) – exponential backoff: czekaj 1s, 2s, 4s, 8s, z losowym jitterem, by nie uderzać synchronicznie.
- 403 (Forbidden) – zwykle brak uprawnień konta serwisowego w GSC albo wyczerpany limit dzienny.
- 401 (Unauthorized) – zły scope lub uszkodzony plik klucza.
- Cachuj wyniki i agreguj po stronie klienta – nie odpytuj o te same dane dwa razy.
- Przy masowej inspekcji użyj puli wątków (np. ThreadPoolExecutor), ale ogranicz równoległość do limitu minutowego, inaczej szybko trafisz na 429.
- Pobieraj dane przyrostowo za dzień sprzed 3 dni – wtedy masz pewność, że są kompletne.

Więcej kontekstu znajdziesz we wpisie o błędach w Google Search Console – API pomaga je wykrywać masowo, ale trzeba wiedzieć, czego szukać.