--- title: "AI Overviews: konkurenci (`getCompetitors`)" source: https://docs.senuto.com/modules/rank_tracker/rt-ai-overviews-getCompetitors api: POST /api/rank_tracker/reports/ai_overviews/getCompetitors --- # AI Overviews: konkurenci (`getCompetitors`) **`POST /api/rank_tracker/reports/ai_overviews/getCompetitors`** Porównuje obecność w blokach AI Overviews (AIO) domeny projektu Rank Tracker i jego konkurentów. Dla każdego konkurenta (lista pochodzi z `GET /api/rank_tracker/management/competitors/list`) zwracane są liczby fraz wspólnych i unikalnych oraz komplet dziewięciu metryk `aio_*` w ujęciu `current` / `previous` / `diff` / `percent`. Wynik jest stronicowany — paginacja liczona jest po konkurentach. Ten raport — w odróżnieniu od modułu AI Overviews w Analizie widoczności — **nie jest przestarzały**. | Domena | ID konkurenta | Frazy wspólne | Frazy unikalne (projekt) | Frazy unikalne (konkurent) | Widoczność AIO (bieżąco) | Widoczność AIO (poprz.) | Widoczność AIO (Δ) | Widoczność AIO (%) | Liczba wystąpień AIO (bieżąco) | Liczba wystąpień AIO (poprz.) | Liczba wystąpień AIO (Δ) | Liczba wystąpień AIO (%) | Śr. pozycja AIO (bieżąco) | Śr. pozycja AIO (poprz.) | Śr. pozycja AIO (Δ) | Śr. pozycja AIO (%) | Cytowania AIO (bieżąco) | Cytowania AIO (poprz.) | Cytowania AIO (Δ) | Cytowania AIO (%) | Frazy z AIO łącznie (bieżąco) | Frazy z AIO łącznie (poprz.) | Frazy z AIO łącznie (Δ) | Frazy z AIO łącznie (%) | SoV AIO (bieżąco) | SoV AIO (poprz.) | SoV AIO (Δ) | SoV AIO (%) | SoV AIO — śr. konkurentów | SoV AIO — maks. konkurentów | Potencjał AIO (bieżąco) | Potencjał AIO (poprz.) | Potencjał AIO (Δ) | Potencjał AIO (%) | Wykorz. potencjał AIO (bieżąco) | Wykorz. potencjał AIO (poprz.) | Wykorz. potencjał AIO (Δ) | Wykorz. potencjał AIO (%) | Unikalne frazy AIO (bieżąco) | Unikalne frazy AIO (poprz.) | Unikalne frazy AIO (Δ) | Unikalne frazy AIO (%) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | fajnyzwierzak.pl | 55578 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | | psy.pl | 4741 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | _Konkurenci w AI Overviews (limit 2). Projekt bez obecności w AIO ma zera w metrykach. Wszystkie adresowalne pola wiersza (obiekt statistics ma stałe klucze aio_*)._ --- ## Żądanie `POST` `/api/rank_tracker/reports/ai_overviews/getCompetitors` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "project_id": null } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "project_id": null, "limit": 2, "page": 1 } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/ai_overviews/getCompetitors' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "project_id": null, "limit": 2 }' ``` ### Parametry ```ts type GetCompetitorsRequest = { /** * **Wymagane**. ID projektu Rank Tracker (`ProjectAccessRules`). * Projekt musi należeć do użytkownika lub być mu udostępniony — cudzy `project_id` zwraca `418` z `Unauthorized access`. * Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`. */ project_id: number; /** * Filtrowanie listy konkurentów. Nieznany `key` → `418` `invalid_filtering`. * Dozwolone klucze m.in.: `competitor_domain`, `aio_visibility`, `aio_count`, `aio_sov`, * `shared_keywords`, `unique_keywords`, `unique_for_competitor` oraz aliasy `statistics.aio_*.current`/`.diff`. * Operatory liczbowe: `gt` | `gte` | `lt` | `lte` | `eq`. */ filtering?: Array<{ filters: Array<{ key: string; match?: 'gt' | 'gte' | 'lt' | 'lte' | 'eq'; value: string | number | Array; complement?: boolean }>; conjunction?: 'and' | 'or'; }>; /** * Numer strony paginacji. Paginacja liczona jest po konkurentach projektu. * @default 1 */ page?: number; /** * Rozmiar strony paginacji (liczba konkurentów na stronę). Odbija się w `pagination.limit`. * @default 10 */ limit?: number; } export default GetCompetitorsRequest ``` > **Ostrzeżenie:** > **Pułapki typów i struktury:** pola `competitor_id`, `shared_keywords`, `unique_keywords` oraz `unique_for_competitor` są zwracane jako **stringi** (np. `"0"`), a nie liczby. Obiekt `statistics` zawiera te same dziewięć metryk `aio_*` co akcja `getStatistics`, ale każda metryka ma wyłącznie `{current, previous, diff, percent}` — **bez pola `history`**; dodatkowo `aio_sov` niesie jeszcze `competitorsAvgSov` i `competitorsMaxSov`. Paginacja liczona jest **po konkurentach** (w projekcie testowym `count: 3`). `project_id` jest wymagane (`ProjectAccessRules`) — cudzy lub nieistniejący projekt zwraca `418` z `Unauthorized access`. Projekt testowy `87944` (pies.pl) nie ma bieżącej obecności w AIO, stąd zera w metrykach — struktura odpowiedzi jest pewna, wartości są przykładowe. ## Odpowiedź Po pomyślnym żądaniu otrzymujesz `data` (tablicę konkurentów) oraz `pagination`. Każdy element `data` opisuje jednego konkurenta: jego identyfikator i domenę, liczby fraz wspólnych i unikalnych (jako stringi) oraz obiekt `statistics` z dziewięcioma metrykami `aio_*`. `count` w `pagination` to łączna liczba konkurentów w projekcie. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "competitor_id": "55578", "competitor_domain": "fajnyzwierzak.pl", "shared_keywords": "0", "unique_keywords": "0", "unique_for_competitor": "0", "statistics": { "aio_visibility": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_sov": { "competitorsAvgSov": 0, "competitorsMaxSov": 0, "current": 0, "previous": 0, "diff": 0, "percent": 0 } } } ], "pagination": { "page_count": 2, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 3, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "competitor_id": "55578", "competitor_domain": "fajnyzwierzak.pl", "shared_keywords": "0", "unique_keywords": "0", "unique_for_competitor": "0", "statistics": { "aio_visibility": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_count": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_avg_pos": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_citations": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_keywords_total": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_sov": { "competitorsAvgSov": 0, "competitorsMaxSov": 0, "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_utilized_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_unique_keywords": { "current": 0, "previous": 0, "diff": 0, "percent": 0 } } }, { "competitor_id": "4741", "competitor_domain": "psy.pl", "shared_keywords": "0", "unique_keywords": "0", "unique_for_competitor": "0", "statistics": { "aio_visibility": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_count": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_avg_pos": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_citations": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_keywords_total": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_sov": { "competitorsAvgSov": 0, "competitorsMaxSov": 0, "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_utilized_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }, "aio_unique_keywords": { "current": 0, "previous": 0, "diff": 0, "percent": 0 } } } ], "pagination": { "page_count": 2, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 3, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type GetCompetitorsResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Konkurenci projektu wraz z metrykami AI Overviews */ data: AioCompetitor[]; /** Metadane paginacji — liczone po konkurentach (`count` = łączna liczba konkurentów) */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number | null; }; } type AioCompetitor = { /** ID konkurenta — **string**, nie liczba (np. "55578") */ competitor_id: string; /** Domena konkurenta */ competitor_domain: string; /** Liczba fraz wspólnych z domeną projektu — **string** (np. "0") */ shared_keywords: string; /** Liczba fraz unikalnych dla domeny projektu — **string** */ unique_keywords: string; /** Liczba fraz unikalnych dla konkurenta — **string** */ unique_for_competitor: string; /** Dziewięć metryk AI Overviews — te same co w `getStatistics`, ale bez pola `history` */ statistics: { /** Widoczność w AI Overviews */ aio_visibility: AioMetric; /** Liczba wystąpień w blokach AIO */ aio_count: AioMetric; /** Średnia pozycja w blokach AIO */ aio_avg_pos: AioMetric; /** Liczba cytowań w blokach AIO */ aio_citations: AioMetric; /** Łączna liczba fraz z blokiem AIO */ aio_keywords_total: AioMetric; /** Share of Voice — dodatkowo zawiera `competitorsAvgSov` i `competitorsMaxSov` */ aio_sov: AioMetric & { competitorsAvgSov: number; competitorsMaxSov: number }; /** Potencjał obecności w AIO */ aio_potential: AioMetric; /** Wykorzystany potencjał obecności w AIO */ aio_utilized_potential: AioMetric; /** Liczba unikalnych fraz z obecnością w AIO */ aio_unique_keywords: AioMetric; }; } type AioMetric = { /** Wartość bieżąca */ current: number; /** Wartość poprzednia */ previous: number; /** Różnica (current - previous) */ diff: number; /** Zmiana procentowa */ percent: number; } export default GetCompetitorsResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > **`418`** jest zwracane również przy błędach walidacji i dostępu. Brak `project_id` skutkuje `invalid_data`, a cudzy lub nieistniejący `project_id` zwraca `Unauthorized access` (`418`), a nie `404` — dostęp weryfikuje `ProjectAccessRules`. ## Powiązane akcje - `getStatistics` — zbiorcze metryki `aio_*` domeny projektu (z historią) - `getKeywords` — frazy projektu z obecnością w AI Overviews - `getDistribution` — rozkład obecności w blokach AIO - `getCompetitors` — porównanie z konkurentami (ta strona) - `getOpportunities` — frazy z szansą na obecność w AIO - `getAioDetails` — surowa treść bloku AIO dla pojedynczej frazy - `getAioSources` — źródła cytowane w blokach AIO