Search Console API i SEO

TL;DR — Interfejs API Search Console pozwala pobierać dane z Google Search Console za pomocą kodu, zamiast klikać w interfejsie. Dzięki niemu uzyskasz więcej niż to, co daje interfejs — eksport w interfejsie kończy się na około 1 000 wierszach, podczas gdy API zwraca do 25 000 na żądanie. Logujesz się przez Google (OAuth, a nie prosty klucz API) i otrzymujesz dane tylko dla witryn, które zweryfikowałeś.

Czym jest interfejs API Search Console

Search Console pokazuje, jak Twoja witryna radzi sobie w Google — dla jakich zapytań się pozycjonujesz, ile kliknięć i wyświetleń otrzymujesz, czy Twoje strony są zaindeksowane. API daje programowy dostęp do dużej części tych samych danych i tych samych kontroli, dzięki czemu możesz je zasilać w arkusz kalkulacyjny, panel lub skrypt, który działa według harmonogramu. To jednak nie jest pełna zgodność z interfejsem — kilka rzeczy (takich jak testowanie URL na żywo) istnieje tylko w interfejsie, a posiadanie dostępu API lub automatyzacji samo w sobie nie gwarantuje indeksowania, pozycji, diagnozy ruchu ani widoczności w wynikach AI.

Są cztery elementy:

1. Search Analytics API — liczby z raportu Skuteczność (kliknięcia, wyświetlenia, CTR, średnia pozycja), podzielone według zapytania, strony, kraju, urządzenia i daty.
2. URL Inspection API — status indeksowania pojedynczego adresu URL. Raportuje wersję aktualnie znajdującą się w indeksie Google; narzędzie URL Inspection w interfejsie może również uruchomić test na żywo, czego API nie potrafi.
3. Sitemaps API — lista, przesyłanie lub usuwanie Twoich map witryn.
4. Sites API — lista, dodawanie lub usuwanie właściwości na Twoim koncie.

Granica właściwości platformy: Search Console ma teraz osobne właściwości Instagram, TikTok, X i YouTube, ale aktualna dokumentacja platformy Google opisuje raporty interfejsu i eksport raportów — a nie identyfikator siteUrl ani umowę wsparcia dla tych starszych punktów końcowych. Przepływ pracy API w tym artykule obejmuje dlatego tylko właściwości witryn. LinkedIn nie jest obsługiwaną właściwością platformy.

Dlaczego warto go używać zamiast interfejsu

Najważniejszy powód: wiersze. Jeśli wyeksportujesz raport Skuteczność z interfejsu Search Console, otrzymasz około 1 000 wierszy. API zwraca do 25 000 wierszy na żądanie, a możesz przewijać strony, aby uzyskać więcej. Jeśli masz witrynę z tysiącami zapytań lub stron, interfejs po prostu nie pokazuje Ci większości Twoich danych.

Innym powodem jest automatyzacja. Gdy masz już wywołanie API, możesz uruchamiać je każdego ranka, przesyłać wyniki do panelu albo wysyłać alert, gdy liczba kliknięć spadnie.

Haczyk

Możesz pobierać dane tylko dla właściwości, które zweryfikowałeś w Search Console. Skieruj API na witrynę, której nie posiadasz, a nie otrzymasz nic — to najczęstszy błąd początkujących.

API nie udostępnia jednak wszystkiego. Zwraca najważniejsze wiersze, a nie pełną listę, i nigdy nie pokazuje zapytań anonimizowanych przez Google ze względów prywatności. W przypadku dużej witryny, która potrzebuje pełniejszego obrazu, lepszym rozwiązaniem jest zbiorczy eksport danych do BigQuery — szczegóły znajdziesz w karcie Advanced.

TL;DR — Interfejs API Search Console to cztery interfejsy REST API pod webmaster-tools/v1 — Search Analytics, URL Inspection, Sitemaps, Sites — wszystkie OAuth 2,0, wszystkie ograniczone tylko do zweryfikowanych właściwości. Search Analytics zwraca 1–25 000 wierszy na żądanie (domyślnie 1 000), ale „nie gwarantuje zwrócenia wszystkich wierszy danych, a raczej najważniejsze”, więc dla kompletności na dużą skalę przechodzisz na zbiorczy eksport danych do BigQuery. URL Inspection ma twardy limit 2 000 QPD / 600 QPM na witrynę — ta arytmetyka jest tym, co ogranicza monitorowanie indeksu na dużą skalę.

Ten przewodnik po API jest ograniczony do właściwości witryn. Nie zakładaj, że punkty końcowe Sites, Search Analytics, URL Inspection lub Sitemaps obsługują właściwości platform Instagram, TikTok, X lub YouTube, dopóki Google nie udokumentuje identyfikatora i zasad obsługi punktu końcowego.

Cztery API na pierwszy rzut oka

Własne określenie Google tego, co robi API: pozwala “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (tłumaczenie) „przeglądać, dodawać lub usuwać właściwości i mapy witryn, uruchamiać zaawansowane zapytania o dane wyników wyszukiwania Google dla właściwości, którymi zarządzasz w Search Console, oraz testować pojedyncze strony.” To odwzorowuje się w cztery zasoby, wszystkie pod webmaster-tools/v1:

• Search Analytics API — raport Skuteczność, programowo: kliknięcia, wyświetlenia, CTR, pozycja według wymiaru (zapytanie, strona, kraj, urządzenie, wygląd w wynikach wyszukiwania, data, godzina).
• URL Inspection API — status indeksowania pojedynczego adresu URL, programowy odpowiednik narzędzia URL Inspection.
• Sitemaps API — lista, pobieranie, przesyłanie i usuwanie map witryn.
• Sites API — lista, dodawanie i usuwanie zweryfikowanych właściwości.

Udostępnia wiele z tego, czego już używasz w interfejsie — raport Skuteczność i narzędzie URL Inspection — jako punkty końcowe, które możesz skryptować. To nie jest jednak odzwierciedleniem 1:1: API nie gwarantuje pełnej zgodności z interfejsem (test na żywo URL Inspection, na przykład, jest tylko w UI — patrz poniżej), a ani dostęp do API, ani automatyzacja sama w sobie nie gwarantują indeksowania, pozycji, diagnozy ruchu ani widoczności w wynikach AI.

Uwierzytelnianie: OAuth 2,0, dwa zakresy, tylko zweryfikowane właściwości

Nie ma klucza API. Każde wywołanie to OAuth 2,0 — Google wyraźnie stwierdza, że “all requests to the Google Search Console API must be authorized by an authenticated user.” (tłumaczenie) „wszystkie żądania do Google Search Console API muszą być autoryzowane przez uwierzytelnionego użytkownika.” Rejestrujesz aplikację w Google Cloud, żądasz zakresu i otrzymujesz krótkotrwały token dostępu. Istnieją dwa zakresy:

• https://www.googleapis.com/auth/webmasters — odczyt/zapis.
• https://www.googleapis.com/auth/webmasters.readonly — tylko odczyt.

Do automatyzacji serwer-serwer (nocne zadanie raportowania, monitor indeksu) przyznajesz konto usługi dostęp do właściwości i pomijasz interaktywny proces zgody.

W przypadku właściwości witryn, dwa formaty identyfikatorów właściwości mają znaczenie również tutaj: właściwość z prefiksem URL jest przekazywana jako pełny adres URL właściwości (własny przykład Google to http://www.example.com/), a właściwość Domain używa formy sc-domain:example.com — musisz przekazać tę formę, która odpowiada sposobowi weryfikacji właściwości w Search Console. W każdym przypadku konto usługi (lub użytkownik) musi mieć przyznany dostęp do tej dokładnej właściwości; nie jest to obejście własności ani automatyczne przyznanie dostępu do każdej właściwości na koncie.

I brama, która wszystkich wywraca: “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (tłumaczenie) „Musisz mieć odpowiedni dostęp (właściciel, pełny, odczyt) do każdego konta Google Search Console, do którego chcesz uzyskać dostęp za pomocą API.” Wywołaj API dla właściwości, której nie zweryfikowałeś, i zwróci nic — nie błąd, który koniecznie zauważysz, tylko puste dane.

Search Analytics API — raport Skuteczność na dużą skalę

Zacznij od limitu, nie od wygody: własne zastrzeżenie Google brzmi: “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (tłumaczenie) „API jest ograniczone wewnętrznymi limitami Search Console i nie gwarantuje zwrócenia wszystkich wierszy danych, a raczej najważniejsze.” Paginacja rozszerza to, jak daleko możesz przewijać listę najważniejszych wierszy — nie usuwa limitu. Gdy potrzebujesz każdego wiersza, to sygnał, aby sięgnąć po eksport zbiorczy BigQuery (poniżej), a nie większy rowLimit.

W ramach tego limitu to wciąż to, po co większość przychodzi. Powód, dla którego bije interfejs, to parametr rowLimit: “[Optional; Valid range is 1–25,000; Default is 1,000].” Eksport z interfejsu kończy się na około 1 000 wierszy; API daje do 25 000 na żądanie, a paginujesz dalej za pomocą startRow. Na stronie z długim ogonem zapytań to różnica między widzeniem góry danych a widzeniem ich większej części — wciąż nie wszystkich.

Dwie kolejne rzeczy kształtują to, co wraca. Po pierwsze, dataState kontroluje świeżość danych: final (domyślnie) zwraca tylko sfinalizowane dane, all obejmuje świeże, ostatnio zebrane dane, a hourly_all podaje rozbicia godzinowe, które są wyraźnie częściowe — metadane odpowiedzi oznaczają first_incomplete_date lub first_incomplete_hour, a Google zauważa, że wartości po tym punkcie mogą się jeszcze zmienić. Po drugie, limity Search Analytics nie są pojedynczą liczbą: strona limitów użycia dzieli je na limity obciążenia (przydział oparty na zasobach, mierzony w 10-minutowych i 1-dniowych porcjach — szersze zakresy dat, więcej wymiarów i cięższe filtrowanie zużywają go szybciej) oraz limity szybkości żądań QPS/QPM/QPD omówione poniżej. Możesz osiągnąć sufit obciążenia, zanim dotrzesz do sufitu szybkości żądań.

API URL Inspection — i limit, który faktycznie cię ogranicza

API URL Inspection “view[s] the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (tłumaczenie) „Wyświetla zaindeksowany lub możliwy do zaindeksowania status podanego adresu URL. Obecnie dostępny jest tylko status wersji w indeksie Google; nie można testować indeksowalności aktywnego adresu URL.” To ostatnie zdanie to realne ograniczenie zakresu, a nie techniczny szczegół: narzędzie URL Inspection w interfejsie może przeprowadzić test na żywo strony w jej obecnym stanie; API może tylko raportować o wersji, którą Google już zaindeksował. Używaj API do budowania monitorowania pokrycia indeksu dla wielu adresów URL — nie jako zamiennika testu na żywo w interfejsie.

Tutaj liczy się matematyka. Na witrynę otrzymujesz 2 000 zapytań dziennie i 600 na minutę. (Na projekt sufit jest znacznie wyższy — 10 000 000/dzień i 15 000/minutę — ale limit na witrynę jest tym, co boli.) Jeśli chcesz monitorować status indeksu witryny z 50 000 adresami URL, nie możesz sprawdzić ich wszystkich w jeden dzień; grupujesz i planujesz na kilka dni albo priorytetyzujesz. Niewiele wpisów wykonuje tę arytmetykę, a to największe ograniczenie planistyczne dla monitorowania indeksu na dużą skalę.

Dla porównania Search Analytics jest hojny — 1 200 QPM na witrynę i na użytkownika — a pozostałe zasoby (Sitemaps, Sites) wynoszą 20 QPS / 200 QPM na użytkownika. URL Inspection jest tym ciasnym.

API Sitemaps i Sites

API Sitemaps to warstwa zarządzania mapami witryn: “submits a sitemap for a site,” (tłumaczenie) „przesyła mapę witryny dla witryny”, “deletes a sitemap from this site,” (tłumaczenie) „usuwa mapę witryny z tej witryny”, “retrieves information about a specific sitemap,” (tłumaczenie) „pobiera informacje o konkretnej mapie witryny” i “lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (tłumaczenie) „wyświetla wpisy map witryn przesłane dla tej witryny lub zawarte w pliku indeksu map witryn”. Zwracany zasób mapy witryny zwraca, zawiera pola takie jak path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors i tablicę contents — przydatne do audytu zdrowia map witryn na dużą skalę.

API Sites wyświetla, dodaje i usuwa zweryfikowane właściwości — przydatne, jeśli zarządzasz wieloma właściwościami i chcesz je programowo udostępniać lub audytować.

Kiedy zamiast tego użyć eksportu zbiorczego do BigQuery

W przypadku dużych witryn model API z limitem 25 000 wierszy na żądanie i tylko najważniejszymi wierszami staje się ograniczeniem. Odpowiedzią Google nie jest piąty zasób API zwracający ten sam kształt danych — to osobny, zaplanowany potok eksportu: zbiorczy eksport danych do BigQuery. To wybór między pobieraniem danych na żądanie a zaplanowanym eksportem, a nie między dwoma równoważnymi API. Google opisuje go tak: “Schedule a daily export of your Search Console performance data to BigQuery, where you can run complex queries over your data or export it to an external storage service. Using the bulk data export feature, you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (tłumaczenie) „Zaplanuj codzienny eksport danych o skuteczności Search Console do BigQuery, gdzie możesz uruchamiać złożone zapytania na swoich danych lub eksportować je do zewnętrznej usługi przechowywania. Korzystając z funkcji eksportu zbiorczego, zobaczysz wszystkie dane o skuteczności dostępne w Search Console dla Twojej właściwości, z wyjątkiem zanonimizowanych zapytań.”

Oto reguła decyzyjna:

• Eksport interfejsu — około 1 000 wierszy, szybki jednorazowy podgląd.
• API Search Analytics — do 25 000 wierszy na żądanie, paginacja i możliwość automatyzacji; dobre rozwiązanie do umiarkowanych pobrań na żądanie i pulpitów nawigacyjnych.
• Zbiorczy eksport do BigQuery — wszystkie dostępne dane o skuteczności, codziennie, bez limitu wierszy; właściwe narzędzie, gdy masz dziesiątki tysięcy stron lub zapytań.

Jedna rzecz, której żadne z nich nie daje, to zanonimizowane zapytania — terminy, które Google ukrywa ze względu na prywatność. To realna luka, a nie błąd, który można obejść. Znam jej skalę z pierwszej ręki: jako Ambasador Marki Ahrefs pomogłem ujawnić badanie, w którym pobraliśmy wszystkie dane dostępne z API na bardzo dużej próbie witryn i odkryliśmy, że Google ukrywa termin zapytania w dużej części kliknięć. Później wbudowaliśmy to w Ahrefs Rank Tracker — pełną historię danych GSC, procent kliknięć trafiających do zanonimizowanych zapytań oraz niestandardową krzywą CTR zbudowaną z Twoich własnych danych. Gdy ktoś mówi Ci, że API zwraca „wszystkie Twoje dane”, ta zanonimizowana część jest uczciwą gwiazdką.

Typowe przypadki użycia

• Automatyczne raportowanie — zaplanowane pobieranie do arkuszy lub hurtowni danych.
• Pulpity BI — Looker Studio lub BigQuery oparte na danych o skuteczności.
• Monitorowanie indeksu/zasięgu na dużą skalę — URL Inspection, w partiach w ramach limitu 2 000/dzień.
• Budowanie krzywej CTR — modelowanie oczekiwanego CTR według pozycji na podstawie własnych danych.
• Alerty anomalii — automatyczne oznaczanie spadków kliknięć/odsłon.

Tak właśnie działają narzędzia innych firm: gdy Ahrefs lub łącznik Looker Studio „integruje Search Console”, wywołują te same API (i coraz częściej eksport BigQuery) w Twoim imieniu.

Podsumowanie AI

Skrócona wersja wersji zaawansowanej:

• Search Console API = cztery API REST w ramach webmaster-tools/v1: Search Analytics (dane o skuteczności), URL Inspection (status indeksu), Sitemaps i Sites. Nie ma pełnej zgodności z interfejsem — kilka rzeczy, jak test na żywo URL Inspection, istnieje tylko w interfejsie, a sam dostęp do API nie gwarantuje indeksowania, pozycji ani diagnozy ruchu.
• Uwierzytelnianie to OAuth 2,0, bez klucza API. Dwa zakresy (webmasters, webmasters.readonly); konta usługowe do komunikacji serwer-serwer, ale nadal wymagają jawnego dostępu do dokładnej właściwości. siteUrl przyjmuje albo właściwość URL-prefix, albo właściwość Domain sc-domain:example.com — dopasuj do sposobu weryfikacji. API zwraca dane tylko dla zweryfikowanych właściwości — to najczęstsza pułapka dla początkujących.
• Search Analytics zwraca najpierw najważniejsze wiersze, a nie pełny zrzut — „nie gwarantuje zwrócenia wszystkich wierszy danych, ale raczej najważniejsze”, niezależnie od paginacji. W tym limicie: 1–25 000 wierszy na żądanie (domyślnie 1 000), w porównaniu z ~1 000 w eksporcie interfejsu, a limity dzielą się na limity obciążenia i limity szybkości żądań QPS/QPM/QPD.
• URL Inspection: 2 000 zapytań/dzień, 600/minutę na witrynę i raportuje tylko zindeksowaną wersję — nie może uruchomić testu na żywo. Ten limit to prawdziwe ograniczenie monitorowania indeksu na dużą skalę — grupuj i planuj wokół niego.
• API Sitemaps wyświetla, pobiera, przesyła i usuwa mapy witryn; API Sites wyświetla, dodaje i usuwa właściwości.
• W przypadku dużych witryn użyj eksportu zbiorczego BigQuery — osobny zaplanowany potok (nie piąty zasób API) dostarczający wszystkie dostępne dane o skuteczności codziennie, bez limitu wierszy, z wyjątkiem zanonimizowanych zapytań.
• Zanonimizowane zapytania to realna luka, której nie wypełnia żadne API ani eksport — praca Patricka w Ahrefs określiła ilościowo, jak duży jest ten ukryty wycinek.

Oficjalna dokumentacja

Podstawowa dokumentacja źródłowa od Google.

Dokumentacja referencyjna Search Console API

• Search Console API — przegląd / informacje — co robi API i wymóg zweryfikowanej właściwości.
• Search Analytics: dokumentacja zapytań — parametry rowLimit (1–25 000) i wymiary.
• Dokumentacja URL Inspection API — jakie dane o statusie indeksowania zwraca metoda inspect.
• Dokumentacja Sitemaps API — list, get, submit, delete.
• Dokumentacja Sites API — list, add, remove zweryfikowanych właściwości.
• Limity użycia — pełna tabela limitów dla witryny, użytkownika i projektu.
• Autoryzacja żądań (OAuth 2.0) — zakresy i przepływ uwierzytelniania.

Eksport danych zbiorczych

• Informacje o eksporcie danych zbiorczych (Pomoc Search Console) — zaplanuj codzienny eksport BigQuery wszystkich danych o skuteczności z wyjątkiem zanonimizowanych zapytań.
• Ogłoszenie eksportu danych zbiorczych (blog Search Central) — wpis o uruchomieniu, pozycjonujący eksport zbiorczy dla dużych witryn.

Cytaty ze źródła

Oficjalne wypowiedzi z dokumentacji Google. Każdy link to link bezpośredni, który prowadzi do cytowanego fragmentu na stronie źródłowej.

Google — co robi API i kto może z niego korzystać

• “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (tłumaczenie) „przeglądać, dodawać lub usuwać właściwości i mapy witryn, uruchamiać zaawansowane zapytania o dane wyników wyszukiwania Google dla właściwości, którymi zarządzasz w Search Console, oraz testować poszczególne strony.” — dokumentacja przeglądowa Google Search Console API. Przejdź do cytatu
• “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (tłumaczenie) „Musisz mieć odpowiedni dostęp (właściciel, pełny, do odczytu) do każdego konta Google Search Console, do którego chcesz uzyskać dostęp za pomocą API.” — dokumentacja przeglądowa Google Search Console API. Przejdź do cytatu
• “All requests to the Google Search Console API must be authorized by an authenticated user.” (tłumaczenie) „Wszystkie żądania do Google Search Console API muszą być autoryzowane przez uwierzytelnionego użytkownika.” — przewodnik po autoryzacji żądań. Przejdź do cytatu

Google — Search Analytics API

• “[Optional; Valid range is 1–25,000; Default is 1,000]” (tłumaczenie) „[Opcjonalnie; prawidłowy zakres to 1–25 000; domyślnie 1 000]” — parametr rowLimit. — dokumentacja zapytań Search Analytics. Przejdź do cytatu
• “The URL of the property as defined in Search Console.” (tłumaczenie) „Adres URL właściwości zgodnie z definicją w Search Console.” — parametr siteUrl, którego przykłady podają zarówno formę z prefiksem URL (http://www.example.com/), jak i formę właściwości domeny (sc-domain:example.com). — dokumentacja zapytań Search Analytics. Przejdź do cytatu
• “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (tłumaczenie) „API jest ograniczone wewnętrznymi limitami Search Console i nie gwarantuje zwrócenia wszystkich wierszy danych, a raczej te najważniejsze.” — dokumentacja zapytań Search Analytics. Przejdź do cytatu

Google — URL Inspection API

• “View the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (tłumaczenie) „Wyświetl stan indeksowania lub możliwości indeksowania podanego adresu URL. Obecnie dostępny jest tylko stan wersji w indeksie Google; nie można testować możliwości indeksowania aktywnego adresu URL.” — dokumentacja URL Inspection API. Przejdź do cytatu

Google — Sitemaps API

• “Submits a sitemap for a site.” (tłumaczenie) „Przesyła mapę witryny dla witryny”. / “Deletes a sitemap from this site.” (tłumaczenie) „Usuwa mapę witryny z tej witryny”. / “Lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (tłumaczenie) „Wyświetla wpisy map witryn przesłane dla tej witryny lub zawarte w pliku indeksu map witryn”. — dokumentacja Sitemaps API. Przejdź do cytatu

Google — eksport danych zbiorczych

• “Schedule a daily export of your Search Console performance data to BigQuery… you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (tłumaczenie) „Zaplanuj codzienny eksport danych o skuteczności Search Console do BigQuery… zobaczysz wszystkie dane o skuteczności dostępne w Search Console dla tej właściwości, z wyjątkiem zanonimizowanych zapytań”. — Pomoc Search Console: informacje o eksporcie zbiorczym. Przejdź do cytatu

Konfiguracja OAuth i lista kontrolna pierwszego wywołania

Przejście od zera do działającego wywołania API Search Console:

• Potwierdź, że masz zweryfikowany dostęp (właściciel, pełny lub tylko do odczytu) do właściwości w Search Console — API nie zwraca nic dla niezweryfikowanych właściwości.
• Utwórz projekt w Google Cloud Console.
• Włącz Search Console API dla tego projektu.
• Utwórz poświadczenia: klient OAuth 2,0 (dla aplikacji interaktywnych/użytkownika) lub konto usługi (dla automatyzacji serwer-serwer).
• Jeśli używasz konta usługi, przyznaj mu dostęp do właściwości w ustawieniach Search Console.
• Poproś o odpowiedni zakres: webmasters.readonly do raportowania, webmasters, jeśli będziesz przesyłać mapy witryn lub zarządzać właściwościami.
• Uzyskaj token dostępu przez przepływ OAuth (lub klucz konta usługi).
• Potwierdź, że format siteUrl odpowiada sposobowi weryfikacji właściwości: pełny URL dla właściwości z prefiksem URL lub sc-domain:example.com dla właściwości domenowej.
• Wykonaj testowe wywołanie searchAnalytics.query z małym zakresem dat i rowLimit: 10, aby potwierdzić, że dane wracają.
• Zaplanuj limity: Search Analytics ma hojne limity żądań, ale również zużywa osobny limit obciążenia; URL Inspection jest ograniczony do 2 000/dzień, 600/min na witrynę — odpowiednio grupuj żądania. Nie oczekuj, że URL Inspection przeprowadzi test na żywo — to tylko funkcja interfejsu.
• Dla dziesiątek tysięcy wierszy skonfiguruj eksport zbiorczy do BigQuery zamiast paginacji.

Modele mentalne

1. Cztery API, jedno uwierzytelnianie. Search Analytics (czytaj dane o skuteczności), URL Inspection (czytaj status indeksowania URL), Sitemaps (zarządzaj mapami witryn), Sites (zarządzaj właściwościami). Wszystkie cztery przechodzą przez te same drzwi OAuth 2,0 i przestrzegają tej samej zasady zweryfikowanej właściwości.

2. Drabina skali danych. Wybierz narzędzie według wolumenu:

• Szybki podgląd → eksport z interfejsu (~1 000 wierszy).
• Skryptowalne, umiarkowane → API Search Analytics (do 25 000/żądanie, paginacja).
• Duża witryna, kompletna → eksport zbiorczy do BigQuery (wszystkie dane, codziennie, bez limitu wierszy). Przesuń się w górę drabiny, gdy szczebel poniżej przestaje pasować do twoich danych.

3. Najlepsze wiersze, nie wszystkie. Zapamiętaj, że API zwraca „najlepsze”, a nie wszystko, oraz że zanonimizowane zapytania są wykluczone zarówno z API, jak i z eksportu. Jeśli kompletność ma znaczenie, BigQuery jest bliżej — ale zanonimizowany wycinek i tak znika.

4. Arytmetyka limitów przed budową. Przed zaprojektowaniem monitora indeksu wykonaj obliczenia: URL Inspection to 2 000/dzień na witryny. Witryna z 50 000 URL-i nie może być sprawdzana codziennie — więc grupuj, priorytetyzuj lub planuj na kilka dni. Projektuj z uwzględnieniem limitu, nie odkrywaj go w produkcji.

Search Console API — ściąga

Cztery API i ich kluczowe limity

Uwierzytelnianie

• Tylko OAuth 2,0 — bez klucza API.
• Zakresy: webmasters (odczyt/zapis), webmasters.readonly (odczyt).
• Konta usługowe do komunikacji serwer-serwer (przyznaj im dostęp do właściwości).
• Tylko zweryfikowane właściwości zwracają dane.

Szybkie fakty

• API zwraca tylko najlepsze wiersze — nie gwarantuje kompletności — niezależnie od paginacji.
• Eksport z interfejsu jest ograniczony do około 1 000 wierszy; API daje do 25 000/żądanie, paginuj za pomocą startRow.
• Przydziały Search Analytics dzielą się na limity obciążenia (oparte na zasobach, w blokach 10-min / 1-dniowych) oraz limity szybkości żądań QPS/QPM/QPD powyżej.
• siteUrl przyjmuje właściwość z prefiksem URL (http://www.example.com/) lub właściwość domenową (sc-domain:example.com) — dopasuj do sposobu weryfikacji.
• URL Inspection raportuje tylko wersję zindeksowaną — nie może uruchomić testu na żywo; to tylko funkcja interfejsu.
• Zanonimizowane zapytania są wykluczone z API oraz eksportu BigQuery.
• Dla dziesiątek tysięcy wierszy → zbiorczy eksport danych BigQuery — to osobny zaplanowany potok, nie piąty zasób API.
• Udostępnia dużą część raportu Wydajność (Search Analytics) i narzędzia URL Inspection, ale nie jest pełnym odpowiednikiem interfejsu.

Minimalne żądanie Search Analytics

To jest przykładowe, nie gotowe do skopiowania — musisz skonfigurować własne poświadczenia OAuth i dostosować daty oraz właściwość. Pokazuje strukturę wywołania searchAnalytics.query: treść żądania z zakresem dat, wymiary, które chcesz, oraz rowLimit.

Treść żądania (istotna część)

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0
}

Szkic w Pythonie (z biblioteką google-api-python-client)

# Illustrative only — assumes you've already built an authorized `service`
# via OAuth 2.0 (scope: webmasters.readonly) or a service account.
from googleapiclient.discovery import build

service = build("searchconsole", "v1", credentials=creds)

request = {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31",
    "dimensions": ["query", "page"],
    "rowLimit": 25000,   # max per request; default is 1000
    "startRow": 0,       # bump by 25000 to paginate
}

response = service.searchanalytics().query(
    siteUrl="https://example.com/",  # URL-prefix property; use "sc-domain:example.com"
                                      # instead for a Domain property — must be verified
    body=request,
).execute()

for row in response.get("rows", []):
    print(row["keys"], row["clicks"], row["impressions"])

Aby przejść poza 25 000 wierszy, zapętl i zwiększaj startRow o 25 000, aż żądanie nie zwróci żadnych wierszy. Pamiętaj, że wynik nadal zawiera tylko “najlepsze wiersze”, a nie pełny zrzut — w tym celu użyj zbiorczego eksportu BigQuery.

Narzędzia korzystające z API Search Console (lub je opakowujące)

• Google Cloud Console — miejsce, w którym tworzysz projekt, włączasz API i generujesz poświadczenia OAuth/konta usługi.
• Oficjalne biblioteki klienckie — biblioteki klienckie API Google dla Pythona, Javy, JavaScript/Node, PHP i .NET opakowują wywołania REST.
• BigQuery — miejsce docelowe eksportu danych zbiorczych; możesz przeszukiwać wszystkie swoje dane wydajnościowe za pomocą SQL.
• Looker Studio — łączy się z Search Console (i BigQuery) w celu tworzenia pulpitów nawigacyjnych opartych na tych samych danych.
• Ahrefs — integruje API Search Console; jego Rank Tracker pokazuje pełną historię GSC, udział kliknięć trafiających do zanonimizowanych zapytań oraz niestandardową krzywą CTR na podstawie Twoich danych.
• Interfejs Search Console — raport Skuteczność i narzędzie Inspekcja URL to ręczne odpowiedniki API Search Analytics i URL Inspection, z jedną luką, której API nie może zamknąć: tylko narzędzie interfejsu może przeprowadzić test na żywo na adresie URL.

Prompty do planowania pracy z API Search Console

Użyj tych promptów, aby ukształtować kod lub plan analizy. Nie umieszczaj poświadczeń, tokenów odświeżania ani kluczy kont usługi w żadnym wejściu czatu.

Zaprojektuj żądanie Search Analytics

Wklej adres URL swojej właściwości, zakres dat, wymiary, filtry i cel raportowania.

Design a Google Search Console Search Analytics API request for the following reporting task.

Property: [sc-domain:example.com or exact URL-prefix property]
Date range: [start and end]
Goal: [the question the report must answer]
Dimensions: [date, query, page, country, device, searchAppearance, or hour]
Filters: [include/exclude rules]

Return:
1. The request body, including a rowLimit no higher than 25,000.
2. Pagination logic using startRow.
3. The aggregation and grouping needed after retrieval.
4. Warnings about top-rows-only data and anonymized queries.
5. A small validation query I can run before scheduling the full pull.

Do not invent credentials or assume the result is a complete census.

Zaplanuj harmonogram Inspekcji URL bezpieczny dla limitów

Wklej podsumowanie CSV lub liczby według priorytetu URL, a nie poufne tokeny.

Create a quota-safe sampling and scheduling plan for the Search Console URL Inspection API.

Property: [property]
Total URLs: [count]
Priority groups: [critical templates, new URLs, changed URLs, long-tail sample]
Required revisit cadence: [daily, weekly, monthly]

Constraints from this article:
- 2,000 inspection queries per day per site.
- 600 inspection queries per minute per site.
- The API reports the indexed version, not a live test.

Return a daily allocation by priority group, a rotation method, retry/backoff rules,
and alerts for unexpected index or canonical states. Explain what cannot fit inside
the quota instead of silently dropping it.

Wybierz API a eksport BigQuery

Help me choose between the Search Console interface, Search Analytics API, and BigQuery bulk export.

Reporting need: [one-off analysis, dashboard, warehouse, anomaly alerts]
Expected rows per day: [estimate]
History required: [range]
Refresh cadence: [cadence]
Dimensions needed: [list]
Infrastructure available: [spreadsheet, script runner, BigQuery, BI tool]

Compare setup cost, row/completeness limits, automation, and maintenance. Account for
the API returning top rows and for anonymized queries being absent from every path.
End with one recommendation and the smallest proof-of-concept to validate it.

Zasoby warte Twojego czasu

Moje powiązane prace

• Blog Ahrefs — moje posty — w tym praca nad danymi GSC na dużą skalę i zanonimizowanymi zapytaniami.
• Teraz w Ahrefs Rank Tracker: pełna historia GSC + udział zanonimizowanych zapytań — funkcja krzywej CTR i historii GSC, którą ogłosiłem.

Dokumentacja Google

• Omówienie API Search Console i strona limity użycia — dwie strony, które warto dodać do zakładek w pierwszej kolejności.
• Informacje o eksporcie danych zbiorczych — kiedy i jak przejść na BigQuery.

Od innych

• Ukryte słowa kluczowe w GSC — badanie Ahrefs (relacja Search Engine Journal) — opis ustaleń dotyczących zanonimizowanych zapytań przez stronę trzecią.
• Ulepszona analityka Search Console z BigQuery (SEJ) — praktyczne spojrzenie na ścieżkę eksportu zbiorczego.
• Eksport danych zbiorczych: nowy i potężny sposób dostępu do danych Search Console (blog Google Search Central) — post z lutego 2023 z zespołu Search Console pozycjonujący eksport zbiorczy dla dużych witryn.
• google-api-python-client (PyPI) — oficjalna biblioteka kliencka Pythona używana do wywoływania API Search Console; dostępna również dla Node, Java, PHP i .NET za pośrednictwem rodziny bibliotek klienckich Google APIs.
• r/TechSEO — społeczność do rozwiązywania problemów z API i pobieraniem danych.

Statystyki, które warto cytować

• Limit wierszy Search Analytics: 25 000 na żądanie (domyślnie 1 000) — w porównaniu z limitem około 1 000 wierszy w eksporcie interfejsu. To główny powód, aby używać API. Źródło
• Limit zapytań URL Inspection: 2 000 zapytań/dzień i 600/minutę na witrynę — twardy limit dla monitorowania indeksu na dużą skalę (10M/dzień, 15 000/minutę na projekt). Źródło
• Zanonimizowane zapytania są wykluczone nawet z najbardziej kompletnej ścieżki (eksport zbiorczy BigQuery) — realna, nieunikniona luka w danych o zapytaniach. Źródło
• Google ukrywa frazę kluczową w dużej części kliknięć — z badania Ahrefs, które pomogłem ujawnić, które pobrało wszystkie dostępne dane z API na bardzo dużej próbce witryn. Zasięg

Sprawdź się: Search Console API

Pięć szybkich pytań o API, uwierzytelnianie, limity danych i skalę. Wybierz odpowiedź na każde, a następnie sprawdź swój wynik.

Dziennik zmian