AI Overviews: wyniki frazy (`getKeywordResults`)

POST/api/visibility_analysis/reports/ai_overviews/getKeywordResults

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ą. Aktualne odpowiedniki raportów AI Overviews per projekt znajdziesz w module Monitoring (rank_tracker/reports/ai_overviews).

Zwraca wyniki AI Overviews (AIO) dla pojedynczej frazy — szczegóły obecności źródeł w bloku AI Overviews dla konkretnego słowa kluczowego wskazanego identyfikatorem keyword_id. Raport pozwala sprawdzić, jak wygląda blok AIO dla wybranego zapytania w kontekście analizowanej domeny.

Żądanie

POST /api/visibility_analysis/reports/ai_overviews/getKeywordResults

Parametry przesyłasz w treści żądania jako JSON. Nagłówki: Authorization: Bearer <token> oraz Content-Type: application/json.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "keyword_id": null
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "keyword_id": null,
  "limit": 2
}

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/ai_overviews/getKeywordResults' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"domain":"zalando.pl","fetch_mode":"topLevelDomain","country_id":1,"keyword_id":null,"limit":2}'

Parametry

Name	Type	Default
`domain`	`string` 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_id`	`number` Identyfikator kraju (baza Google). Opcjonalne — walidator tej akcji nie wymusza pola; gdy pominięte, backend stosuje domyślny kraj (PL).	`1`
`keyword_id`	`number` Wymagane (walidator: requirePresence). Identyfikator słowa kluczowego, dla którego mają zostać zwrócone wyniki AI Overviews. Identyfikatory fraz uzyskasz np. z akcji `getKeywords` tego kontrolera.
`filtering`	`{ filters: { key: string; match?: "gt" \| "gte" \| "lt" \| "lte" \| "eq"; value: string \| number \| (string \| number)[]; complement?: boolean; }[]; conjunction?: "and" \| "or"; }[]` Filtrowanie wyników AI Overviews frazy. Dozwolone klucze m.in.: `domain`, `pos`, `url`, `title`, `organic_pos`, `organic_url`, `faq_pos`, `faq_url`, `is_translated`, `is_fragment`, `fragment_text`, `is_analyzed_domain_and_url_match`. ⚠️ Uwaga: backend AIO działa na ClickHouse i — inaczej niż raporty Bazy słów — na nieznany `key` nie zwraca `418` (klucz bywa po cichu pomijany). Efektu filtra nie wsparcie potwierdzone w implementacji endpointu.
`page`	`number` Numer strony wyników. Opcjonalne.	`1`
`limit`	`number` Maksymalna liczba wyników na stronę. Opcjonalne.

Dozwolone wartości fetch_mode to dokładnie ['topLevelDomain', 'subdomain', 'catalog', 'url'] — przekazanie domain to częsty błąd i nie przechodzi walidacji.

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, data — tablicę wyników AI Overviews dla wskazanej frazy — oraz obiekt pagination z informacjami o stronicowaniu. Gdy dla danej domeny (lub frazy) brak danych AIO, data jest pustą tablicą ([]), a liczniki paginacji wskazują zero wyników. Tak właśnie odpowiedziała domena testowa zalando.pl — 200 z pustą tablicą.

Skrócona

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

Name	Type	Default
`success`	`boolean` Flaga przetworzenia żądania. Potwierdzone (`true`) w odpowiedzi `200`.
`data`	`unknown[]` Tablica wyników AI Overviews dla wskazanej frazy. Pusta tablica (`[]`), gdy domena nie ma danych AIO.
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }` Informacje o stronicowaniu wyników. Potwierdzone w odpowiedzi `200`.

Błędy

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

Błędy walidacji (np. brak wymaganego domain lub fetch_mode, albo nieprawidłowa wartość fetch_mode) zwracane są ze statusem 418 i kopertą invalid_data z mapą params wskazującą pole i naruszoną regułę.

Powiązane akcje

Wszystkie poniższe akcje są przestarzałe:

getStatistics — zbiorcze statystyki AI Overviews dla domeny
getKeywords — słowa kluczowe wywołujące AI Overviews
getDistribution — rozkład obecności domeny w AI Overviews
getCompetitors — konkurenci domeny w AI Overviews
getKeywordResults — wyniki AI Overviews dla pojedynczej frazy (ta strona)
getKeywordsIntents — agregacja fraz AIO według intencji
getOpportunities — frazy-szanse: domena rankuje organicznie, ale nie jest w AIO

Aktualne odpowiedniki raportów AI Overviews per projekt znajdziesz w module Monitoring (rank_tracker/reports/ai_overviews).

AI Overviews: wyniki frazy (getKeywordResults)