AI Overviews: frazy (`getKeywords`)

POST/api/visibility_analysis/reports/ai_overviews/getKeywords

Endpoint przestarzały. Działa, ale może nie być aktywnie utrzymywany i w przyszłości zostać wycofany lub zastąpiony — co może też tłumaczyć, dlaczego zwraca pustą listę mimo obecności danych AIO. Planuj integrację z ostrożnością.

Zwraca frazy kluczowe, dla których domena pojawia się w sekcji AI Overviews Google (generatywne podsumowania wyświetlane nad wynikami organicznymi), wraz ze statystykami pozycji, widoczności, ruchu oraz cech SERP dla każdej frazy. Kształt żądania i odpowiedzi jest spójny z pozostałymi raportami kontrolera visibility_analysis/reports.

Żądanie

POST /api/visibility_analysis/reports/ai_overviews/getKeywords

Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


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

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "limit": 10,
  "page": 1,
  "with_history": true,
  "order": { "prop": "visibility", "dir": "desc" },
  "filtering": []
}

cURL


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

Parametry

Name	Type	Default
`domain`	`string` Wymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`.
`fetch_mode`	`"topLevelDomain" \| "subdomain" \| "catalog" \| "url"` Wymagane. Sposób interpretacji `domain`. `topLevelDomain` — cała domena (najczęstszy przypadek; “domena”) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL
`limit`	`number` Liczba wierszy na stronę. Nieujemna liczba całkowita.	`10`
`page`	`number` Numer strony. Nieujemna liczba całkowita.	`1`
`with_history`	`boolean` Dołącz do odpowiedzi mapę historii pozycji (`history`) dla każdej frazy.	`true`
`order`	`{ prop: string; dir: "asc" \| "desc"; }` Sortowanie wyników — pojedynczy obiekt, nie tablica. Dozwolone `prop` m.in.: `keyword`, `organic_pos`, `visibility`, `searches`, `best_aio_pos`, `aio_positions_count`, `aio_domains_count`. Zły kształt lub nieznany klucz NIE zwraca błędu — API po cichu wraca do sortu domyślnego (`best_organic_pos` rosnąco, `searches` malejąco).
`filtering`	`unknown[]` Dyrektywy filtrowania. Pusta tablica = brak filtrowania.

Nazwy parametrów: jest to filtering (nie filters) oraz order (nie sort_by / sort_order). Uwaga na kształt order: to obiekt { "prop": …, "dir": … } — forma tablicowa [{ field, direction }] jest przez API ignorowana po cichu (zwraca 200 z sortem domyślnym). Kierunku sortowania nie udało się potwierdzić na żywym API, bo raport zwraca pustą listę (patrz ostrzeżenie o statusie @deprecated powyżej) — kształt na podstawie źródła backendu.

Zarówno domain, jak i fetch_mode są wymagane; pominięcie fetch_mode zwraca 418 z invalid_data. Metoda to POST z treścią JSON — przesłanie parametrów inną drogą skutkuje 405/418.

Przykładowa domena nie zwróciła danych dla tego raportu (data jest puste, count = 0) — poniżej udokumentowano strukturę odpowiedzi na podstawie analizy kontrolera, bez zmyślania wartości. Dla domeny obecnej w AI Overviews data zawiera wiersze fraz o kształcie analogicznym do raportu pozycji.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data (tablicę wierszy fraz, dla których domena pojawia się w AI Overviews) oraz pagination. Gdy domena nie występuje w AI Overviews, data jest puste, a count wynosi 0.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [],
  "pagination": { "count": 0, "page_count": 0, "current_page": 1, "limit": 2 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`KeywordRow[]` Zwrócone wiersze fraz; puste, gdy domena nie pojawia się w AI Overviews
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }` Metadane paginacji

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"}}}}}.

Powiązane akcje

getKeywords — frazy z AI Overviews (ta strona)
getData — bieżące pozycje organiczne (raport positions, taki sam kształt żądania)
getWins / getLosses — frazy, które zyskały / straciły pozycje
getKeywordHistory — pełna historia pozycji dla pojedynczej frazy (keyword_id + kid + domain + fetch_mode)

AI Overviews: frazy (getKeywords)