AI Overviews: intencje (`getKeywordsIntents`)

GET/api/visibility_analysis/reports/ai_overviews/getKeywordsIntents

Zwraca agregację fraz wywołujących AI Overviews (AIO) według intencji wyszukiwania. Wymiar agregacji wybierasz parametrem aggregation_type — dostępnych jest pięć ujęć: intencja podstawowa (primary_intent_value), intencja główna (main_intent_value), typ akcji (action_type_value), etap ścieżki zakupowej (journey_stage_value) i charakter treści (content_timeliness_value). Raport pozwala zrozumieć, jakie intencje użytkowników dominują wśród zapytań wyzwalających bloki AIO dla analizowanej domeny.

Żądanie

GET /api/visibility_analysis/reports/ai_overviews/getKeywordsIntents

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


// Query string parameters
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 200,
  "aggregation_type": "primary_intent_value"
}
// GET /api/visibility_analysis/reports/ai_overviews/getKeywordsIntents?domain=zalando.pl&fetch_mode=topLevelDomain&country_id=200&aggregation_type=primary_intent_value

Rozszerzony

żądanie-rozszerzone.jsonc


// Query string parameters — agregacja według intencji głównej
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 200,
  "aggregation_type": "main_intent_value"
}
// GET /api/visibility_analysis/reports/ai_overviews/getKeywordsIntents?domain=zalando.pl&fetch_mode=topLevelDomain&country_id=200&aggregation_type=main_intent_value

cURL


curl --location --request GET 'https://api.senuto.com/api/visibility_analysis/reports/ai_overviews/getKeywordsIntents?domain=zalando.pl&fetch_mode=topLevelDomain&country_id=200&aggregation_type=primary_intent_value' \
  --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`. 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 z subdomenami użyj `subdomain`, dla samego hosta `topLevelDomain`. `topLevelDomain` — dokładnie ten host, bez subdomen `subdomain` — cała domena wraz ze wszystkimi subdomenami (to odpowiednik „całej domeny” i tak liczy aplikacja domyślnie) `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`
`aggregation_type`	`"primary_intent_value" \| "main_intent_value" \| "action_type_value" \| "journey_stage_value" \| "content_timeliness_value"` Wymagane. Wymiar agregacji intencji (walidator `inList`, pięć wartości): `primary_intent_value` — intencja podstawowa (Know / Do / Website / …) `main_intent_value` — intencja główna (INFORMATIONAL / TRANSACTIONAL / …) `action_type_value` — typ akcji (BUY / COMPARE / RESEARCH / TROUBLESHOOT) `journey_stage_value` — etap ścieżki zakupowej (TOFU / MOFU / BOFU) `content_timeliness_value` — charakter treści (Evergreen / Seasonal) Inna wartość → `418` z komunikatem “Invalid aggregation type. Allowed values: …”.

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

Ta akcja jest wywoływana metodą GET i odczytuje dane z query string — parametry przesyłaj w adresie URL, nie w treści JSON. Poza standardowym zestawem domain + fetch_mode + country_id wymagany jest parametr aggregation_type, walidowany regułą inList — dozwolonych jest pięć wartości (patrz wyżej). Nieprawidłowa wartość kończy się statusem 418 z komunikatem "Invalid aggregation type. Allowed values: ...". Ta akcja nie ma paginacji.

Dane intencji są wyłącznie w bazie PL 2.0 — wywołuj z country_id: 200. Bez tego (czyli na domyślnej bazie country_id: 1) raport zwraca 200 z pustą tablicą dla każdej domeny, co wygląda jak brak danych AIO, a jest tylko złą bazą. Zwalidowane 2026-08-02: medonet.pl z country_id: 1 → [], to samo żądanie z country_id: 200 → 68 tys. fraz w rozbiciu na intencje.

Odpowiedź

W przypadku powodzenia otrzymujesz success: true oraz data — tablicę wyników agregacji fraz AIO według wybranego wymiaru intencji, posortowaną malejąco po liczbie fraz. Ta akcja nie zwraca obiektu pagination. Pusta tablica oznacza brak danych AIO dla tej domeny w tej bazie — najczęściej to po prostu country_id inne niż 200 (patrz ostrzeżenie wyżej).

przykładowa-odpowiedź (zwalidowana 2026-08-02: zalando.pl, country_id=200)


{
  "success": true,
  "data": [
    { "name": "Know", "count": "1854", "percentage": 61.07 },
    { "name": "Do", "count": "800", "percentage": 26.35 },
    { "name": "Website", "count": "329", "percentage": 10.84 },
    { "name": "Know Simple", "count": "13", "percentage": 0.43 },
    { "name": "Visit-in-Person", "count": "11", "percentage": 0.36 }
  ]
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` Flaga przetworzenia żądania. Potwierdzone (`true`) w odpowiedzi `200`.
`data`	`{ name: string; count: string; percentage: number; }[]` Agregacja fraz AIO według wymiaru z `aggregation_type`, malejąco po `count`.

Jakie wartości zwraca każdy wymiar

Zaobserwowane na produkcji 2026-08-02 (country_id: 200, domeny zalando.pl, medonet.pl, senuto.com). Nazwy pochodzą wprost z danych — API nie udostępnia słownika, więc lista jest tym, co realnie wystąpiło, a nie zamkniętym enumem:

`aggregation_type`	Wartości `name`
`primary_intent_value`	`Know`, `Know Simple`, `Do`, `Website`, `Visit-in-Person`, `Unknown`
`main_intent_value`	`INFORMATIONAL`, `TRANSACTIONAL`, `NAVIGATIONAL`, `LOCAL`
`action_type_value`	`RESEARCH`, `BUY`, `COMPARE`, `TROUBLESHOOT`, `Unknown`, `""` (puste)
`journey_stage_value`	`TOFU`, `MOFU`, `BOFU`, `Unknown`
`content_timeliness_value`	`Evergreen`, `Seasonal`

Intencja pojedynczej frazy. Ten raport podaje intencje zbiorczo dla domeny i tylko dla fraz wywołujących AI Overviews. Intencję każdej frazy, na którą rankuje domena, zwraca positions/getData w polu statistics.intentions wiersza: primary_intent, main_intent, action_type, journey_stage, content_timeliness. Wartości są tam pisane małymi literami (navigational, research, tofu, evergreen), a klucze nie mają sufiksu _value. Baza słów kluczowych nie ma endpointu z intencją dowolnej frazy spoza rankingu domeny.

Jak nazwy z raportu mapują się na aplikację

Zestawienie z filtrem „Intencje” w aplikacji (sprawdzone 2026-08-12):

Znaczenie	Ten raport (`main_intent_value`)	Aplikacja Senuto
szukanie informacji	`INFORMATIONAL`	Research
zamiar zakupu / działania	`TRANSACTIONAL`	Transactional
konkretna marka lub serwis	`NAVIGATIONAL`	Navigational
intencja lokalna	`LOCAL`	Local

Filtr w aplikacji zna dokładnie te cztery wartości.

primary_intent_value to klasyfikacja w duchu taksonomii Google (Know / Do / Website / Visit-in-Person), a main_intent_value — klasyczny podział na intencje informacyjną, transakcyjną, nawigacyjną i lokalną. Wartości Unknown oraz pusty string występują realnie w danych — obsłuż je w kliencie. Nazewnictwo w aplikacji Senuto może być przetłumaczone; API zwraca zawsze formy powyżej.

Błędy

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

Nieprawidłowa wartość aggregation_type (spoza listy primary_intent_value, main_intent_value, action_type_value) zwraca 418 z komunikatem "Invalid aggregation type. Allowed values: ...". Pozostałe błędy walidacji (brak domain, fetch_mode czy country_id, nieprawidłowy fetch_mode) również zwracają 418 z kopertą invalid_data. Pamiętaj, że parametry muszą trafić do query string — ta akcja jest wywoływana metodą GET.

Powiązane akcje

Pozostałe akcje AI Overviews w Analizie widoczności:

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
getKeywordsIntents — agregacja fraz AIO według intencji (ta strona)
getOpportunities — frazy-szanse: domena rankuje organicznie, ale nie jest w AIO

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

AI Overviews: intencje (getKeywordsIntents)