Cum folosesc API-ul Google Search Console?

Creează un proiect în consola Google Cloud, activează Google Search Console API, creează credențiale OAuth 2.0 și autentifică-te cu un cont Google care are acces la proprietate. Apoi poți trimite cereri către patru resurse: Search Analytics pentru clicuri, afișări, CTR și poziție; URL Inspection pentru starea indexării; Sitemaps; și Sites. Cheile API singure nu funcționează: fiecare apel necesită un token OAuth, iar cotele limitează cât de multe date poți cere.

Ce acoperă API-ul și ce nu

Asta este tot API-ul. Linkurile, Crawl stats, raportul Page indexing și raportul Core Web Vitals nu au endpoint, așa că rămân doar în interfața Search Console. URL Inspection raportează ce se află în indexul Google, nu un test live al paginii.

Configurarea accesului

1. În consola Google Cloud, creează sau alege un proiect.
2. Activează Google Search Console API pentru proiectul respectiv.
3. Configurează ecranul de consimțământ OAuth și creează un ID de client OAuth.
4. Solicită un scope: https://www.googleapis.com/auth/webmasters.readonly pentru citire sau https://www.googleapis.com/auth/webmasters dacă vrei să poți trimite sau șterge și sitemap-uri.
5. Autentifică-te cu un cont care are permisiuni pe proprietate. Pentru citirea datelor de performanță este necesar cel puțin acces de citire; API-ul vede exact ce vede contul respectiv.

Prima ta interogare 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
}

Site-ul se transmite în cale, codat ca URL: sc-domain:example.com pentru o proprietate de tip Domeniu sau prefixul exact, cu slash final, precum https://www.example.com/, pentru o proprietate de tip prefix URL. Câmpurile cele mai importante:

• Datele sunt inclusive și se raportează în fusul orar al Pacificului (Pacific Time).
• type este implicit web; celelalte valori sunt image, video, news, googleNews și discover. Fiecare necesită o cerere separată.
• Filtrele se pun în dimensionFilterGroups, cu operatori de la equals și contains până la includingRegex și excludingRegex (sintaxă RE2).
• rowLimit merge de la 1 la 25,000 (implicit 1,000); startRow parcurge restul rezultatelor.
• dataState este implicit final; all adaugă zilele recente, încă nefinalizate, iar hourly_all funcționează cu dimensiunea hour.

Fiecare rând returnează keys, clicks, impressions, ctr (de la 0 la 1) și position, sortate după clicuri, cu excepția cazului în care grupezi după dată.

Limitele care îți influențează codul

• 50,000 de rânduri pe zi pentru fiecare tip de căutare. Parcurge rezultatele cu startRow în pași de 25,000 și oprește-te la un răspuns gol. Pentru a obține cât mai multe date, interoghează o singură zi pe cerere.
• Cota de încărcare. Gruparea sau filtrarea simultană după pagină și interogare este cea mai costisitoare cerere, iar intervalele lungi costă mai mult decât cele scurte. Dacă depășești cota pe termen scurt, Google îți cere să aștepți 15 minute.
• Ritmul cererilor. 1,200 de interogări pe minut per site și per utilizator; 40,000 pe minut și 30,000,000 pe zi per proiect.
• Cota URL Inspection. 2,000 de inspecții pe zi și 600 pe minut pentru fiecare proprietate.
• 16 luni de istoric, iar datele sunt disponibile de obicei la două-trei zile după încheierea zilei respective.
• Rândurile nu se adună la totaluri. Interogările rare sunt excluse din rândurile la nivel de interogare, iar gruparea după pagină numără afișările diferit față de gruparea după proprietate, așa că citește totalurile dintr-o cerere fără dimensiunea query.

Greșeli frecvente

• Folosirea http:// atunci când proprietatea este https:// sau omiterea slash-ului final produce o eroare de permisiuni, chiar dacă (deși) contul are acces.
• Cererea unui URL din afara proprietății în URL Inspection este respinsă: URL-ul trebuie să se afle sub siteUrl-ul pe care îl transmiți.
• O lună grupată după interogare și pagină într-un singur apel returnează doar rândurile de top. Cererile zilnice returnează mai multe.

Cum te ajută AutoPSEO

Dacă preferi să nu întreții OAuth și paginarea, AutoPSEO se conectează prin autentificarea Google și expune aceleași date prin propriul REST API la /v1 (cu un document OpenAPI 3.1) și printr-un server MCP, autorizat cu o cheie API din Account → API keys. Sunt disponibile chei doar pentru citire, endpoint-ul de search analytics returnează până la 5,000 de rânduri per apel, iar instrumentele de URL Inspection din aplicație țin evidența cotei Google de 2,000 pe zi în locul tău. Vezi MCP și chei API. Pentru a păstra datele mai mult de 16 luni fără să scrii un pipeline, citește cât timp păstrează Search Console datele.

Surse: referința API Google, metoda de interogare Search Analytics, limitele de utilizare, obținerea tuturor datelor și ghidul de autorizare.