--- title: "AI Overviews: intencje (`getKeywordsIntents`)" source: https://docs.senuto.com/modules/visibility_analysis/va-ai-overviews-getKeywordsIntents api: GET /api/visibility_analysis/reports/ai_overviews/getKeywordsIntents --- # AI Overviews: intencje (`getKeywordsIntents`) **`GET /api/visibility_analysis/reports/ai_overviews/getKeywordsIntents`** > **Ostrzeżenie:** > **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 **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 `. ### Struktura żądania **Podstawowy** ```jsonc filename="żą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** ```jsonc filename="żą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** ```bash 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 ```ts type AiOverviewsGetKeywordsIntentsRequest = { /** * **Wymagane**. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`. * Bez schematu/protokołu — np. `zalando.pl`. */ domain: string; /** * **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 */ fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url'; /** * Identyfikator kraju (baza Google). Opcjonalne — walidator tej akcji nie wymusza pola; * gdy pominięte, backend stosuje domyślny kraj (PL). * @default 1 */ country_id?: number; /** * **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: ...". */ aggregation_type: 'primary_intent_value' | 'main_intent_value' | 'action_type_value' | 'journey_stage_value' | 'content_timeliness_value'; } export default AiOverviewsGetKeywordsIntentsRequest ``` > **Ostrzeżenie:** > Dozwolone wartości `fetch_mode` to dokładnie `['topLevelDomain', 'subdomain', 'catalog', 'url']` — przekazanie `domain` to częsty błąd i nie przechodzi walidacji. > **Ostrzeżenie:** > 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**. > **Błąd:** > **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). ```json filename="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 ```ts type AiOverviewsKeywordsIntentsResponse = { /** Flaga przetworzenia żądania. Potwierdzone (`true`) w odpowiedzi `200`. */ success: boolean; /** Agregacja fraz AIO według wymiaru z `aggregation_type`, malejąco po `count`. */ data: { /** Wartość wymiaru — zestaw zależy od `aggregation_type` (tabela niżej). */ name: string; /** Liczba fraz w tej kategorii. Uwaga: przychodzi jako STRING. */ count: string; /** Udział procentowy w całości (liczba, np. 61.07). */ percentage: number; }[]; } export default AiOverviewsKeywordsIntentsResponse ``` ### 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` | > **Informacja:** > **Gdzie jeszcze w API znajdziesz intencje.** Ten raport podaje je **zbiorczo dla domeny** i tylko dla fraz > wywołujących AI Overviews. Drugie miejsce to **Content Planner** — `szczegóły grupy planów` > i `szczegóły planu` zwracają `main_intent` oraz rozbicie > `intents[]` dla fraz w grupie. W **Bazie słów kluczowych nie ma endpointu z intencją pojedynczej frazy** — > jeśli tego szukasz, dziś API tego nie udostępnia. > > ### Trzy słowniki intencji — jak się mapują > > Uwaga: **te same pojęcia mają różne nazwy** w Content Plannerze, w tym raporcie i w interfejsie aplikacji. > Zestawienie (aplikacja sprawdzona 2026-08-12 w filtrze „Intencje" Content Plannera): > > | Znaczenie | Content Planner — API | Ten raport (`main_intent_value`) | Aplikacja Senuto | > | -------------------------- | --------------------- | -------------------------------- | ----------------- | > | szukanie informacji | `research` | `INFORMATIONAL` | **Research** | > | zamiar zakupu / działania | `transactional` | `TRANSACTIONAL` | **Transactional** | > | konkretna marka lub serwis | `navigational` | `NAVIGATIONAL` | **Navigational** | > | intencja lokalna | `local` | `LOCAL` | **Local** | > > Content Planner zwraca małe litery, ten raport — wersaliki. Filtr w aplikacji zna dokładnie te cztery > wartości. Wymiar `primary_intent_value` (Know / Do / Website / Visit-in-Person) jest **osobną, bardziej > szczegółową klasyfikacją** w duchu taksonomii Google i nie ma odpowiednika w powyższej czwórce. > > `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 ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, unreachable_data, timeout, database, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > 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 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 - `getKeywordsIntents` — agregacja fraz AIO według intencji (ta strona) - `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`).