Jak korzystać z Google Search Console API?

Q: Jak korzystać z Google Search Console API?

Skonfiguruj projekt w Cloud, włącz API, autoryzuj dostęp przez OAuth, a następnie pobieraj dane o skuteczności, inspekcję adresów URL i mapy witryn. Oto kroki i limity.

Utwórz projekt w konsoli Google Cloud, włącz Google Search Console API, utwórz dane uwierzytelniające OAuth 2.0 i zaloguj się na konto Google, które ma dostęp do usługi. Następnie możesz wysyłać żądania do czterech zasobów: Search Analytics (kliknięcia, wyświetlenia, CTR i pozycja), URL Inspection (stan indeksowania), Sitemaps oraz Sites. Same klucze API nie wystarczą: każde wywołanie wymaga tokena OAuth, a limity ograniczają ilość danych, o które możesz poprosić.

Co obejmuje API, a czego nie

Zasób	Metody	Do czego służy
Search Analytics	`query`	Wiersze z danymi o skuteczności według zapytania, strony, kraju, urządzenia, wyglądu w wynikach wyszukiwania, daty lub godziny
URL Inspection	`index.inspect`	Zaindeksowana wersja jednego adresu URL: pokrycie, ostatnie skanowanie, adresy kanoniczne
Sitemaps	`list`, `get`, `submit`, `delete`	Zarządzanie mapami witryn zgłoszonymi dla usługi
Sites	`list`, `get`, `add`, `delete`	Usługi przypisane do zalogowanego konta

To całe API. Linki, statystyki indeksowania, raport Indeksowanie stron i raport Core Web Vitals nie mają własnych endpointów, więc dostępne są wyłącznie w interfejsie Search Console. URL Inspection pokazuje, co znajduje się w indeksie Google, a nie wynik testu strony na żywo.

Konfiguracja dostępu

W konsoli Google Cloud utwórz projekt lub wybierz istniejący.
Włącz Google Search Console API dla tego projektu.
Skonfiguruj ekran zgody OAuth i utwórz identyfikator klienta OAuth.
Poproś o zakres uprawnień: https://www.googleapis.com/auth/webmasters.readonly do odczytu lub https://www.googleapis.com/auth/webmasters, jeśli chcesz też zgłaszać lub usuwać mapy witryn.
Zaloguj się na konto, które ma uprawnienia do usługi. Do odczytu danych o skuteczności wystarczy co najmniej dostęp do odczytu; API widzi dokładnie to samo, co to konto.

Pierwsze zapytanie do Search Analytics

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

Witrynę podaje się w ścieżce, zakodowaną jako URL: sc-domain:example.com dla usługi domenowej albo dokładny prefiks z ukośnikiem na końcu, np. https://www.example.com/, dla usługi z prefiksem adresu URL. Najważniejsze pola:

Daty są włączane do zakresu i podawane w czasie pacyficznym (Pacific Time).
type domyślnie ma wartość web; pozostałe to image, video, news, googleNews i discover. Każdy typ wymaga osobnego żądania.
Filtry umieszcza się w dimensionFilterGroups, z operatorami od equals i contains po includingRegex i excludingRegex (składnia RE2).
rowLimit mieści się w zakresie od 1 do 25 000 (domyślnie 1000); startRow pozwala przechodzić przez kolejne wiersze.
dataState domyślnie ma wartość final; all dodaje świeże, jeszcze niekompletne dni, a hourly_all działa z wymiarem hour.

Każdy wiersz zawiera keys, clicks, impressions, ctr (od 0 do 1) i position, posortowane według kliknięć, chyba że grupujesz według daty.

Limity, które wpływają na kod

50 000 wierszy dziennie na typ wyszukiwania. Przechodź przez wyniki za pomocą startRow co 25 000 wierszy i zakończ na pustej odpowiedzi. Aby pobrać jak najwięcej danych, odpytuj po jednym dniu.
Limit obciążenia. Najkosztowniejsze jest żądanie z grupowaniem lub filtrowaniem jednocześnie według strony i zapytania, a długie zakresy dat kosztują więcej niż krótkie. Po przekroczeniu krótkoterminowego limitu Google prosi o odczekanie 15 minut.
Limity żądań. 1200 zapytań na minutę na witrynę i na użytkownika; 40 000 na minutę i 30 000 000 dziennie na projekt.
Limit URL Inspection. 2000 inspekcji dziennie i 600 na minutę dla każdej usługi.
16 miesięcy historii, a dane są zwykle dostępne po dwóch–trzech dniach od zakończenia danego dnia.
Wiersze nie sumują się do wartości łącznych. Rzadkie zapytania są pomijane w wierszach na poziomie zapytań, a grupowanie według strony liczy wyświetlenia inaczej niż grupowanie według usługi, dlatego sumy odczytuj z żądania bez wymiaru query.

Typowe błędy

Użycie http://, gdy usługa jest zarejestrowana jako https://, lub pominięcie ukośnika na końcu powoduje błąd uprawnień, nawet jeśli konto ma dostęp.
Prośba o adres URL spoza usługi w URL Inspection zostanie odrzucona: adres musi należeć do przekazanego siteUrl.
Miesiąc zgrupowany według zapytania i strony w jednym wywołaniu zwraca tylko najlepsze wiersze. Żądania dzienne zwracają ich więcej.

Jak pomaga AutoPSEO

Jeśli wolisz nie utrzymywać obsługi OAuth i paginacji, AutoPSEO łączy się przez logowanie Google i udostępnia te same dane przez własne REST API pod adresem /v1 (wraz z dokumentem OpenAPI 3.1) oraz serwer MCP, z autoryzacją kluczem API z sekcji Konto → Klucze API. Dostępne są klucze tylko do odczytu, endpoint analityki wyszukiwania zwraca do 5000 wierszy na wywołanie, a narzędzia URL Inspection w aplikacji same pilnują limitu Google wynoszącego 2000 inspekcji dziennie. Zobacz MCP i klucze API. Jak zachować dane dłużej niż 16 miesięcy bez budowania własnego potoku danych, dowiesz się z artykułu jak długo Search Console przechowuje dane.

Źródła: Google: dokumentacja API, metoda query w Search Analytics, limity użycia, pobieranie wszystkich danych oraz przewodnik po autoryzacji.