AI Overviews: statystyki (`getStatistics`)

GET/api/visibility_analysis/reports/ai_overviews/getStatistics

Endpoint przestarzały. Działa, ale może nie być aktywnie utrzymywany i w przyszłości zostać wycofany lub zastąpiony. Planuj integrację z ostrożnością.

Zwraca zbiorcze statystyki obecności domeny w AI Overviews (odpowiedziach generowanych przez AI w wynikach Google) dla zadanej domeny. Pojedynczy obiekt data z licznikami fraz wyzwalających AIO, liczbą fraz z udziałem domeny, średnią pozycją oraz bilansem zysków i strat widoczności. Raport służy do oceny, na ile domena jest reprezentowana w wynikach AI względem własnej widoczności organicznej.

Żądanie

GET /api/visibility_analysis/reports/ai_overviews/getStatistics

Nagłówki: Authorization: Bearer <token>. Parametry przekazuje się w query stringu (np. ?domain=zalando.pl&fetch_mode=topLevelDomain); pola zagnieżdżone zapisuje się w notacji klucz[pod]=….

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain"
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain"
}

cURL


curl --location --request GET 'https://api.senuto.com/api/visibility_analysis/reports/ai_overviews/getStatistics?domain=zalando.pl&fetch_mode=topLevelDomain' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE'

Parametry

Name	Type	Default
`domain`	`string` Wymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`. Przekazywane w query stringu.
`fetch_mode`	`"topLevelDomain" \| "subdomain" \| "catalog" \| "url"` Wymagane. Sposób interpretacji `domain`. Przekazywany w query stringu. `topLevelDomain` — cała domena (najczęstszy przypadek; “domena”) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL

Endpoint jest obsługiwany metodą GET — parametry przekazuje się w query stringu, a nie w ciele żądania. Zarówno domain, jak i fetch_mode są wymagane; pominięcie fetch_mode zwraca 418 z invalid_data. Wysłanie parametrów w ciele żądania (body) zamiast w query stringu skutkuje błędem (418 / 405).

Odpowiedź

Po pomyślnym żądaniu otrzymujesz pojedynczy obiekt data ze statystykami AI Overviews.

Przykładowa domena nie zwróciła danych dla tego raportu — wszystkie liczniki w odpowiedzi 200 mają wartość 0. Poniżej struktura odpowiedzi wraz z nazwami i typami pól.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": {
    "aio_keywords_count": 0,
    "aio_keywords_with_domain_count": 0,
    "aio_avg_pos": 0
    /* … */
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`{ aio_keywords_count: number; aio_keywords_with_domain_count: number; aio_avg_pos: number; aio_losses_count: number; aio_wins_count: number; aio_organic_keywords_count: number; aio_losses_vis_sum: number; organic_keywords_count: number; aio_vis_loss_percentage: number; }`

Błędy

Name	Type	Default
`success`	`false`
`data`	`{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }`

418 jest zwracane również w przypadku błędów walidacji — nie tylko przy ograniczaniu liczby żądań. Brak fetch_mode → {"success":false,"data":{"error":{"type":"invalid_data","params":{"fetch_mode":{"_required":"This field is required"}}}}}. Przekazanie parametrów w ciele żądania zamiast w query stringu (ten endpoint to GET) skutkuje błędem 418 / 405.

Powiązane akcje

getStatistics — zbiorcze statystyki AI Overviews dla domeny (ta strona)
getData z kontrolera positions — bieżące pozycje organiczne fraz domeny (taki sam kształt parametrów domain + fetch_mode)
Pozostałe raporty w przestrzeni nazw visibility_analysis/reports/… korzystają z tej samej pary parametrów domain + fetch_mode

AI Overviews: statystyki (getStatistics)