Hogyan használjam a Google Search Console API-t?

Q: Hogyan használjam a Google Search Console API-t?

Hozzon létre egy Cloud-projektet, engedélyezze az API-t, adjon hozzáférést OAuth-tal, majd kérdezze le a teljesítményadatokat, az URL-vizsgálatot és a sitemapeket. Itt a lépések és a kvóták.

Hozzon létre egy projektet a Google Cloud console-ban, engedélyezze a Google Search Console API-t, hozzon létre OAuth 2.0-hitelesítő adatokat, és jelentkezzen be egy olyan Google-fiókkal, amelynek van hozzáférése a property-hez. Ezután négy erőforrásra küldhet kéréseket: a Search Analytics a kattintásokat, megjelenéseket, CTR-t és pozíciót adja vissza; az URL Inspection az indexelési állapotot; a Sitemaps a sitemapeket; a Sites pedig a property-ket. Önmagában az API-kulcs nem elég: minden híváshoz OAuth-token kell, a kvóták pedig korlátozzák, mennyi adatot kérhet le.

Mit fed le az API, és mit nem

Erőforrás	Metódusok	Mire használható
Search Analytics	`query`	Teljesítménysorok lekérdezés, oldal, ország, eszköz, keresési megjelenés, dátum vagy óra szerint
URL Inspection	`index.inspect`	Egy URL indexelt változata: lefedettség, utolsó feltérképezés, canonical címek
Sitemaps	`list`, `get`, `submit`, `delete`	A property-hez beküldött sitemapek kezelése
Sites	`list`, `get`, `add`, `delete`	A bejelentkezett fiók property-jei

Ennyi az egész API. A hivatkozásokhoz (Links), a Crawl stats, az oldalindexelési jelentéshez (Page indexing) és a Core Web Vitals jelentéshez nincs végpont, ezért ezek csak a Search Console felületén érhetők el. Az URL Inspection azt mutatja meg, ami a Google indexében van, nem az oldal élő tesztjét.

A hozzáférés beállítása

A Google Cloud console-ban hozzon létre vagy válasszon ki egy projektet.
Engedélyezze a Google Search Console API-t ehhez a projekthez.
Állítsa be az OAuth-hozzájárulási képernyőt, és hozzon létre egy OAuth-ügyfélazonosítót.
Kérjen hatókört (scope): olvasáshoz https://www.googleapis.com/auth/webmasters.readonly, a sitemapek beküldéséhez vagy törléséhez is https://www.googleapis.com/auth/webmasters.
Jelentkezzen be egy olyan fiókkal, amelynek van jogosultsága a property-n. A teljesítményadatok olvasásához legalább olvasási jogosultság kell; az API pontosan azt látja, amit az adott fiók.

Az első Search Analytics lekérdezés

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
}

A webhely az elérési útban szerepel, URL-kódolva: sc-domain:example.com Domain típusú property esetén, URL-előtagos property esetén pedig a pontos előtag a záró perjellel, például https://www.example.com/. A legfontosabb mezők:

A dátumok zártak (a kezdő- és a záródátum is beleszámít), és csendes-óceáni időben (Pacific Time) értendők.
A type alapértelmezés szerint web; a többi lehetőség image, video, news, googleNews és discover. Mindegyikhez külön kérés kell.
A szűrők a dimensionFilterGroups mezőbe kerülnek, az operátorok az equals és a contains értéktől az includingRegex és az excludingRegex értékig terjednek (RE2 szintaxis).
A rowLimit 1 és 25 000 között lehet (alapértelmezés: 1000); a többi sort a startRow segítségével lapozhatja végig.
A dataState alapértelmezés szerint final; az all a friss, még nem véglegesített napokat is tartalmazza, a hourly_all pedig az hour dimenzióval használható.

Minden sor tartalmazza a keys, clicks, impressions, ctr (0 és 1 között) és position mezőt, kattintások szerint rendezve, kivéve, ha dátum szerint csoportosít.

A kódot meghatározó korlátok

Naponta és keresési típusonként 50 000 sor. Lapozzon a startRow értékével 25 000-es lépésekben, és álljon meg, ha üres választ kap. A legtöbb adat eléréséhez egyszerre egy napot kérdezzen le.
Terhelési kvóta. Az oldal és a lekérdezés szerinti csoportosítás vagy szűrés egyszerre a legköltségesebb kérés, a hosszú dátumtartományok pedig többe kerülnek a rövidekné. Ha túllépi a rövid távú kvótát, a Google 15 perc várakozást kér.
Kérési korlátok. Webhelyenként és felhasználónként percenként 1200 lekérdezés; projektenként percenként 40 000 és naponta 30 000 000.
URL Inspection kvóta. Property-nként naponta 2000 vizsgálat és percenként 600.
16 hónapnyi előzmény, az adatok pedig jellemzően a nap végét követő két-három nap múlva érhetők el.
A sorok összege nem egyezik a végösszegekkel. A ritka lekérdezések kimaradnak a lekérdezés szintű sorokból, az oldal szerinti csoportosítás pedig másképp számolja a megjelenéseket, mint a property szerinti, ezért a végösszegeket a query dimenzió nélküli kérésből olvassa ki.

Gyakori hibák

Ha http:// címet használ, miközben a property https://, vagy elhagyja a záró perjelet, jogosultsági hibát kap akkor is, ha a fióknak van hozzáférése.
Az URL Inspection elutasítja a property-n kívüli URL-t: az URL-nek az Ön által megadott siteUrl alá kell tartoznia.
Egy hónap lekérdezés és oldal szerint, egyetlen hívásban csak a legjobb sorokat adja vissza. A napi kérések több sort adnak.

Hogyan segít az AutoPSEO

Ha nem szeretné az OAuth-ot és a lapozást saját maga karbantartani, az AutoPSEO Google-bejelentkezéssel csatlakozik, és ugyanezeket az adatokat a saját REST API-ján keresztül teszi elérhetővé a /v1 címen (OpenAPI 3.1 dokumentummal), valamint egy MCP-szerveren keresztül, amelyet az Account → API keys alatt létrehozott API-kulccsal engedélyezhet. Csak olvasási jogú kulcsok is elérhetők, a search analytics végpont hívásonként legfeljebb 5000 sort ad vissza, az alkalmazás URL-vizsgálati eszközei pedig helyette számon tartják a Google napi 2000-es kvótáját. Lásd: MCP és API-kulcsok. Ha 16 hónapnál tovább szeretné megőrizni az adatokat adatfolyam írása nélkül, olvassa el, meddig őrzi meg az adatokat a Search Console.

Források: a Google API-referenciája, a Search Analytics query metódus, a használati korlátok, az összes adat lekérése és az engedélyezési útmutató.