API Search Console: jak budować własne raporty

API Search Console to bezpośredni dostęp do danych wyszukiwania Google – tych samych, które widzicie w interfejsie GSC, tylko w surowej, programowalnej formie. W 2026 roku zespoły, które budują własne raporty na API zamiast eksportować CSV-ki, mają o 60-80% szybsze tempo iteracji na decyzjach SEO. Ten tekst pokazuje, jak konkretnie postawić taki pipeline i co z nim robić.

Interface Search Console w przeglądarce jest wygodny, ale zaprojektowany dla osoby, która klika raz w tygodniu. API daje dwa rzeczy, których nie ma w UI: ściągnięcie pełnej siatki zapytanie × URL × kraj × urządzenie bez limitu 1000 wierszy, oraz powtarzalność – to samo zapytanie, codziennie, automatycznie, do własnego magazynu danych.

W skrócie

Search Console API zwraca dane performance (kliki, wyświetlenia, CTR, średnia pozycja) z dokładnością dzienną i wymiarami: query, page, country, device, searchAppearance.
Limity: 1200 wierszy na żądanie (można paginować), 40 000 wierszy na dzień per property, 16-miesięczna historia. To wystarczy do większości scenariuszy agencyjnych.
Stack minimalny: Google Cloud project z włączonym Search Console API, service account albo OAuth, skrypt w Pythonie (biblioteka google-api-python-client) i magazyn (BigQuery, SQLite, albo zwykły CSV dla małych projektów).
Trzy najczęstsze scenariusze: raporty alertowe (spadek ruchu na konkretnym URL), mapowanie query-to-page (które frazy trafiają na które URL-e), długoterminowy trending (co miesiąc to samo zapytanie, 16 miesięcy wstecz).
Koszt: 0 PLN (API darmowe w limitach), kilkanaście godzin na setup i ~2 godziny miesięcznie na utrzymanie.

Czym jest API Search Console i dlaczego warto odejść od UI

Google Search Console API to zestaw punktów końcowych REST udostępniających dane indeksacji, wydajności w wyszukiwarce, sitemap i URL inspection. Najczęściej używany endpoint to searchanalytics.query – ten sam, który zasila zakładkę „Skuteczność” w interfejsie. Daje dane historyczne za ostatnie 16 miesięcy z granulacją dzienną.

Przejście z UI na API ma cztery twarde przyczyny:

Limit 1000 wierszy w UI. Przy dużej stronie tracisz 90% danych. API pozwala paginować do 40 000 wierszy dziennie per property – wystarczy na serwis z ~25 000 URL-i.
Brak agregacji wielowymiarowej w UI. Nie da się jednym kliknięciem zobaczyć „query × page × device × country” – trzeba klikać filtry. W API to jedno żądanie z czterema wymiarami.
Brak historii dłuższej niż 16 miesięcy. API ma ten sam limit, ale jeśli codziennie pobieracie dane do własnego magazynu, po roku macie 28 miesięcy, po dwóch latach 40.
Brak powtarzalności. Zrobienie tego samego raportu co tydzień w UI to 20-30 minut klikania. W API to jedno uruchomienie skryptu.

W praktyce agencje SEO obsługujące 10+ klientów praktycznie nie mogą pracować bez API – samo eksportowanie CSV-ek zjadłoby połowę godzin zespołu. Dobre spięcie API z dashboardem w Looker Studio daje klientowi dostęp do zawsze aktualnych danych bez logowania do GSC, o czym piszemy szerzej w przewodniku o automatyzacji raportów SEO. Kluczowe narzędzia do analityki SEO – te płatne i darmowe – porównujemy też w zestawieniu Ahrefs vs Semrush vs Sistrix 2026.

Jak to działa w praktyce: architektura pipeline’u na danych GSC

Pipeline danych z Search Console ma cztery warstwy. Każda robi jedną rzecz – nie mieszaj ich w jednym skrypcie, bo za trzy miesiące nie rozgryziesz, dlaczego raport się nie zgadza.

Warstwa ekstrakcji. Skrypt, który codziennie pyta API o dane z poprzedniego dnia (GSC ma 2-3 dniowe opóźnienie, więc bezpiecznie pytaj o „wczoraj minus 3 dni”). Zapisuje surowe dane do magazynu bez transformacji.
Warstwa przechowywania. BigQuery (preferowane dla średnich i dużych), SQLite (małe projekty do 500 MB danych) albo Parquet na dysku (prototypy). NIE trzymaj danych w Google Sheets – to się rozjedzie przy 100 000 wierszy.
Warstwa transformacji. Osobne skrypty/queries, które z surowych danych produkują agregaty (tygodniowe, miesięczne), joiny z innymi źródłami (GA4, Ahrefs) i kolumny obliczane (CTR, delta do poprzedniego okresu).
Warstwa wizualizacji. Looker Studio, Power BI albo własny dashboard (Streamlit, Dash). Nigdy nie czytaj z surowych tabel – zawsze z transformowanych.

Warstwa	Narzędzie (rekomendacja)	Czas setup	Koszt miesięczny
Ekstrakcja	Python + Cloud Functions (albo cron na serwerze)	4-6 godzin	~0 PLN (limity darmowe)
Przechowywanie	BigQuery	1-2 godziny	5-40 PLN dla średniej strony
Transformacja	dbt albo zwykłe SQL w BigQuery	6-10 godzin	0 PLN (dbt core darmowy)
Wizualizacja	Looker Studio	3-5 godzin	0 PLN

Łączny setup: 15-25 godzin pracy. Utrzymanie po ustawieniu: 1-2 godziny miesięcznie. Dla agencji obsługującej 10 klientów ten sam pipeline skaluje się liniowo – każdy klient to osobna property i osobny skrypt, ale architektura ta sama.

Proces krok po kroku: od zera do pierwszego raportu w 3 godziny

Poniżej dokładny scenariusz wdrożenia. Zakłada, że masz konto Google i property zweryfikowane w Search Console.

Utwórz projekt w Google Cloud Console. Console > New Project > nazwa np. „gsc-data-pipeline”. Zapisz projectId.
Włącz Search Console API. APIs & Services > Library > szukaj „Search Console API” > Enable. To 10 sekund.
Utwórz service account. IAM & Admin > Service Accounts > Create. Pobierz klucz JSON. Uwaga: service account sam z siebie nie ma dostępu do Twojej property – trzeba go dodać.
Dodaj service account do property w GSC. Search Console > Settings > Users and permissions > Add user. Wklej email service account’u (kończy się na @project.iam.gserviceaccount.com). Rola: Restricted (czyta, nie edytuje).
Napisz pierwszy skrypt. Python, biblioteka google-api-python-client. Autentykacja przez klucz JSON, wywołanie searchanalytics.query z parametrami: siteUrl, startDate, endDate, dimensions: ["query", "page"].
Zapisz wyniki do pliku/bazy. Dla prototypu wystarczy CSV. Dla produkcji – BigQuery z bigquery.Client().load_table_from_dataframe.
Zautomatyzuj. Cron na serwerze (Linux), Cloud Scheduler + Cloud Function (Google Cloud) albo GitHub Actions. Codziennie, 3 razy w tygodniu – zależy od potrzeb.
Podłącz do dashboardu. Looker Studio > nowe źródło danych > BigQuery > wybierz tabelę. Zbuduj raport: wykres liniowy ruchu, tabela top query, tabela top pages, alerty wbudowane.

Najdłuższy element to punkt 4 – dodanie service account do property. Ludzie zapominają, że API nie dziedziczy uprawnień osoby, która tworzyła projekt. Zawsze trzeba jawnie przyznać dostęp. Drugi pułap to punkt 5 – pierwszy skrypt API-owy bywa 2-3 godziny zabawy z autentykacją, jeśli nie robiliście tego wcześniej.

Gotowe skrypty w Pythonie do standardowych scenariuszy GSC opisujemy w przeglądzie 10 skryptów, które oszczędzają godziny. Warto też zintegrować dane GSC z szerszą strategią analityki SEO i AIO, bo sam ruch organiczny bez kontekstu biznesowego jest tylko liczbą.

Trzy scenariusze, które daje tylko API: konkretne zapytania

Poniżej trzy scenariusze, które są praktycznie niemożliwe w UI Search Console i trywialne w API. Każdy z nich ma wartość biznesową mierzalną w godzinach zespołu.

Scenariusz 1: alert spadku ruchu per URL

Codzienny skrypt: dla każdego URL-a z ostatnich 7 dni porównuje ruch (kliki) do średniej z poprzednich 28 dni. Jeśli spadek powyżej 30% i URL miał wcześniej >50 kliknięć tygodniowo – flaguje w Slack. Zespół dowiaduje się o problemie w 24 godziny, nie po miesiącu, gdy ktoś zajrzy do GSC.

W API: jedno żądanie z dimensions: ["page", "date"] za ostatnie 35 dni. W UI: niemożliwe bez eksportu 35 osobnych raportów.

Scenariusz 2: query-to-page mapping dla całej strony

Pełna macierz: dla 500 najważniejszych fraz, który dokładnie URL Google pokazuje w wynikach. To pokazuje kanibalizację (dwa URL-e rankują na tę samą frazę, walcząc o pozycję) i luki (fraza o wysokich wyświetleniach trafia na słaby URL).

W API: żądanie z dimensions: ["query", "page"], filtr na min. 100 wyświetleń miesięcznie, eksport do tabeli. W UI: trzeba by kliknąć 500 fraz pojedynczo.

Scenariusz 3: dzienny trend wyświetleń dla nowo opublikowanego artykułu

Publikujecie pillar. Chcecie wiedzieć dzień po dniu, ile wyświetleń, na jakich frazach i z jakimi pozycjami. Przez pierwsze 2 tygodnie dane GSC są najciekawsze – pokazują, jak Google klasyfikuje treść.

W API: skrypt codziennie pobiera dane dla URL-a nowego artykułu, zapisuje do osobnej tabeli. W UI: można śledzić, ale trzeba ręcznie klikać filtr URL co dzień.

Przykłady i liczby z realnych wdrożeń

Dane z dwóch wdrożeń z 2025 roku pokazują różne skale zastosowań.

Klient	Skala strony	Setup (godziny)	Oszczędność czasu/mc	Wykryte problemy
E-commerce (12 000 URL)	średnia	22 h	14 h/mc	Kanibalizacja na 47 frazach, 3 spadki ruchu wykryte w 24 h
Portal medialny (80 000 URL)	duża	40 h	50 h/mc	Indeksacja 12 000 starych newsów zidentyfikowana i rozwiązana

W obu przypadkach ROI zwrócił się w 2-3 miesiącach. Dla portalu medialnego 50 godzin/miesiąc oszczędności to etat na pół – realna wartość 5-7 tys. PLN miesięcznie. Setup 40 godzin to jednorazowo 4-6 tys. PLN, więc break-even po ~6-8 tygodniach.

Dodatkowa korzyść, której nie widać w liczbach: zespół analityczny przestaje tracić energię na powtarzalne eksporty i zaczyna odpowiadać na pytania typu „dlaczego to się stało” zamiast „co się stało”. To zmienia rolę SEO specjalisty z reportera na analityka.

Limity API i jak je obejść

API ma trzy ograniczenia, które trzeba rozumieć, zanim zaczniesz budować produkcyjny pipeline:

25 000 wierszy na żądanie, paginacja do 40 000 na property dziennie. Dla dużej strony to za mało na pobranie wszystkich danych naraz. Obejście: pobieraj per kraj albo per urządzenie (mniejsze partie), albo ograniczaj do top query (min. 10 wyświetleń).
16 miesięcy historii. Jeśli potrzebujesz więcej, jedyna droga to pobierać codziennie i archiwizować. Nie ma sposobu na pobranie danych starszych niż 16 miesięcy, nawet jeśli masz property od 5 lat.
Próg prywatności. Google ukrywa frazy, które wyszukało mniej niż kilka osób (tzw. threshold). W danych API też ich nie zobaczysz – pojawiają się jako „(other)” w pewnych raportach.

Obejścia, które działają:

Dla limitu wierszy – segmentacja zapytań per searchAppearance (web, image, news), per country albo per device. Zwielokrotnia liczbę żądań, ale każde jest w limicie.
Dla historii – codzienne pobieranie od dziś zbuduje w rok 28-miesięczne archiwum. Po dwóch latach macie dane, których nikt w branży nie ma.
Dla progu prywatności – to się nie obchodzi. Google chroni prywatność wyszukiwań i nie ma legalnej drogi, żeby to ominąć.

Najczęstsze błędy w integracji GSC API

Pomijanie autoryzacji service account dla property. Skrypt zwraca 403, zespół traci pół dnia na debugowanie. Zawsze najpierw w GSC: Settings > Users > Add.
Odpytywanie zbyt często. Dane GSC odświeżają się raz dziennie. Zapytania co godzinę to marnowanie quoty API i brak nowych danych.
Brak retry przy rate limit. API zwraca 429. Skrypt bez backoff się wywala, dane nie wchodzą. Używaj tenacity albo własnej logiki retry z exponential backoff.
Nieprawidłowe strefy czasowe. GSC operuje w Pacific Time. Jeśli raportujecie „ostatnie 7 dni” bez uwzględnienia strefy, dane mogą się rozjechać o 24 godziny.
Mieszanie danych surowych z agregatami. Tabela „raw” powinna być nietykalna. Tabele agregowane to osobne obiekty. Nadpisywanie surowych danych po transformacji to utrata możliwości re-liczenia.
Filtry po stronie klienta zamiast w API. Pobieranie 40 000 wierszy, żeby potem odfiltrować 90% w pandas, to marnowanie quoty. Używaj parametru dimensionFilterGroups w żądaniu.
Brak monitoringu pipeline’u. Skrypt się wywala, nikt nie wie, dashboard pokazuje stare dane, klient myśli, że ruch spadł. Zawsze: alert w Slack/email, gdy skrypt nie zakończył się poprawnie.

Integracja z innymi źródłami: GA4, Ahrefs, własne dane

Pełna wartość GSC API ujawnia się dopiero, gdy łączycie dane z innych źródeł. Trzy najcenniejsze połączenia:

GSC + GA4. GSC ma pozycję, CTR, wyświetlenia. GA4 ma zachowanie po wejściu (bounce rate, czas, konwersje). Join po URL-u i dacie. Pokazuje: które frazy nie tylko rankują, ale też konwertują – to zupełnie inna lista niż „top query” w GSC.
GSC + Ahrefs/Semrush. Ahrefs podaje szacunkową difficulty i search volume. GSC podaje realne wyświetlenia i pozycję. Join po frazie pokazuje, które łatwe frazy macie już wysoko (i warto wzmocnić), a które trudne i tam tracicie czas.
GSC + CRM/sales. Jeśli wasz biznes konwertuje leadów telefonicznie lub offline, GA4 nie pokaże pełnego obrazu. Join GSC z danymi sprzedażowymi po URL landing page daje real ROI per fraza.

Wszystkie trzy wymagają dobrego modelu danych. Tabele fact (zdarzenia, sesje) vs dimension (URL-e, frazy, daty). Bez tego join-y będą się psuły i liczby nie będą się zgadzać.

FAQ – najczęstsze pytania o API Search Console

Czy API jest darmowe?

Tak. Google Search Console API nie ma opłat za wywołania – tylko limity: 1200 wierszy per żądanie, 40 000 per property dziennie. Dla 99% przypadków to wystarcza. Koszty pojawiają się, gdy przechowujecie dane w BigQuery (5-50 PLN/mc zależnie od wolumenu) albo uruchamiacie Cloud Functions do automatyzacji (pierwsze 2 miliony wywołań/mc darmowe).

Czy da się pobrać więcej niż 16 miesięcy historii?

Nie. Google ogranicza historię do 16 miesięcy niezależnie, jak długo macie property. Jedyne obejście to codziennie pobierać dane i archiwizować – po roku macie 28 miesięcy, po dwóch 40. Jeśli dopiero zakładacie property, zacznijcie codzienne pobieranie od pierwszego dnia.

Python czy inny język do integracji z API?

Python jest defaultem – biblioteka google-api-python-client jest oficjalna, dobrze udokumentowana, bardzo aktywnie utrzymywana. Node.js też ma oficjalną bibliotekę. R ma wspólnotowe rozwiązania (biblioteka searchConsoleR). Dla jednorazowych eksportów wystarczy nawet cURL. W zespołach analitycznych Python wygrywa dzięki pandas i łatwej dalszej obróbce.

Ile trwa pierwszy pipeline od zera do działającego dashboardu?

Osoba z doświadczeniem w API i Pythonie: 3-5 godzin. Osoba pracująca z API po raz pierwszy, ale znająca Python: 8-12 godzin (większość na autentykację i service account). Osoba bez tła programistycznego, z nauką po drodze: 20-30 godzin albo zatrudnienie freelancera (2-3 tys. PLN za prosty pipeline).

Jak często pobierać dane?

Raz dziennie o stałej porze (np. 6:00 rano). Dane w GSC mają 2-3 dniowe opóźnienie, więc pobieraj zawsze „dziś minus 3 dni”. Częściej niż raz dziennie nie ma sensu – dane się nie zmieniają. Rzadziej niż raz dziennie traci się alertowalność (spadek ruchu wykryty po 7 dniach zamiast 1).

Czy API pokazuje dane, których nie ma w UI?

Te same dane – różnica w ilości i elastyczności. W API możecie łączyć więcej wymiarów naraz (np. query × page × country × device w jednym żądaniu), paginować do 40 000 wierszy i pobierać ściśle określone segmenty. UI ma prostsze filtry, ale mniejsze wolumeny. Jeden wyjątek: URL Inspection API zwraca więcej szczegółów technicznych niż UI (indeksacja, status crawla, canonical).

Co zrobić, gdy skrypt zwraca pusty wynik, choć w UI widzę dane?

Najczęstsze przyczyny: (1) service account nie został dodany do property w GSC Settings > Users, (2) siteUrl w żądaniu musi dokładnie odpowiadać property (sc-domain:example.com dla domain property, albo https://example.com/ z ukośnikiem na końcu dla URL prefix), (3) zakres dat obejmuje dni z 0 kliknięciami. Sprawdź te trzy punkty w kolejności, w 95% przypadków problem leży tutaj.

Co dalej

Pierwsze API-owe pobranie danych warto zrobić dziś – nawet w formie 20-liniowego skryptu zapisującego CSV. Dopiero mając surowe dane na dysku, zobaczycie, co jest warte dalszego automatyzowania. Gdy pipeline ruszy, następnym krokiem jest spięcie go z szerszym obrazem wydajności organicznej opisanym w przewodniku o analityce SEO i AIO oraz rozważenie, czy część raportów nie przenieść do w pełni zautomatyzowanych dashboardów zamiast arkuszy.