Skip to Content
ModułyAnaliza widocznościRozkład

AI Overviews: rozkład (getDistribution)

GET/api/visibility_analysis/reports/ai_overviews/getDistribution

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 rozkład obecności domeny w blokach AI Overviews (AIO) Google dla wskazanej domeny. Raport pokazuje, jak słowa kluczowe wywołujące AI Overviews rozkładają się względem widoczności domeny w tych blokach — pozwala ocenić, w jakiej części zapytań wyzwalających AIO domena faktycznie pojawia się jako cytowane źródło.

Żądanie

GET /api/visibility_analysis/reports/ai_overviews/getDistribution

Parametry są odczytywane z query string (getQuery). Nagłówki: Authorization: Bearer <token>.

Struktura żądania

żądanie-podstawowe.jsonc
// Query string parameters
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain"
}
// GET /api/visibility_analysis/reports/ai_overviews/getDistribution?domain=zalando.pl&fetch_mode=topLevelDomain

Parametry

NameTypeDefault
domainstring

Wymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z fetch_mode. Bez schematu/protokołu — np. zalando.pl.

fetch_mode"topLevelDomain" | "subdomain" | "catalog" | "url"

Wymagane. Sposób interpretacji domain. Uwaga: domain NIE jest prawidłową wartością — dla całej domeny użyj topLevelDomain.

  • topLevelDomain — cała domena (najczęstszy przypadek)
  • subdomain — pojedyncza subdomena
  • catalog — ścieżka/katalog
  • url — dokładny adres URL
country_idnumber

Identyfikator kraju (baza Google). Opcjonalne — gdy pominięte, 0 lub nieprawidłowe, backend stosuje domyślny kraj (PL).

1

Dozwolone wartości fetch_mode to dokładnie ['topLevelDomain', 'subdomain', 'catalog', 'url'] (DataFetchMode::AVAILABLE_MODES). Przekazanie domain to częsty błąd — nie odpowiada żadnemu trybowi i nie przechodzi walidacji.

Ta akcja jest wywoływana metodą GET i odczytuje dane z query string, więc parametry przesyłaj w adresie URL. Wysłanie żądania metodą POST zwraca 405, a przesłanie parametrów wyłącznie w treści JSON kończy się 418. Zarówno domain, jak i fetch_mode są wymagane. Wartość fetch_mode domain nie istnieje — dla całej domeny użyj topLevelDomain. Parametr country_id jest opcjonalny i domyślnie przyjmuje PL (1), gdy jest pominięty lub nieprawidłowy.

Domena bez danych AI Overviews zwraca 200 z pustą tablicą data — to nie błąd, tylko brak wyników dla tej domeny.

Odpowiedź

W przypadku powodzenia otrzymujesz success: true oraz data — tablicę obiektów rozkładu obecności w AI Overviews. Gdy dla danej domeny brak danych AIO, data jest pustą tablicą ([]). Tak właśnie odpowiedziała domena testowa zalando.pl — 200 z pustą tablicą.

przykładowa-odpowiedź (skrócona)
{
  "success": true,
  "data": []
}

Dla domen, które nie mają danych AI Overviews, data jest pustą tablicą — to nie błąd, tylko brak wyników dla tej domeny. Poniżej opisana jest koperta odpowiedzi.

Struktura odpowiedzi

NameTypeDefault
successboolean

Flaga przetworzenia żądania. Potwierdzone (true) w odpowiedzi 200.

dataunknown[]

Tablica obiektów rozkładu obecności w AI Overviews. Pusta tablica ([]), gdy domena nie ma danych AIO.

Błędy

NameTypeDefault
successfalse
data{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }

Wysłanie żądania niewłaściwą metodą POST zwraca 405 (Method Not Allowed) — ta akcja akceptuje wyłącznie GET. Z kolei 418 jest zwracane przy błędach walidacji (nie tylko przy ograniczaniu liczby żądań), m.in. gdy parametry trafią do treści JSON zamiast do query string (przez co getQuery jest puste) lub gdy pominięto fetch_mode. Brak fetch_mode → {"success":false,"data":{"error":{"type":"invalid_data","params":{"fetch_mode":{"_required":"This field is required"}}}}}.

Powiązane akcje

  • getDistribution — rozkład obecności domeny w AI Overviews (ta strona)
  • getStatistics — zbiorcze statystyki AI Overviews dla domeny
  • getKeywords — słowa kluczowe wywołujące AI Overviews (taki sam kształt żądania domain + fetch_mode)
Ostatnia aktualizacja:
StatystykiKonkurenci