--- title: "Kanibalizacja: frazy (`getKeywords`)" source: https://docs.senuto.com/modules/visibility_analysis/va-cannibalization-getKeywords api: POST /api/visibility_analysis/reports/cannibalization/getKeywords --- # Kanibalizacja: frazy (`getKeywords`) **`POST /api/visibility_analysis/reports/cannibalization/getKeywords`** Zwraca frazy dotknięte **kanibalizacją** — czyli takie, na które rankuje więcej niż jeden adres domeny lub dla których adres rankujący zmienia się między pomiarami. Każdy wiersz zawiera frazę wraz ze statystykami (pozycja, widoczność, CPC, liczba wyszukiwań, trudność, trendy, snippety SERP) oraz parę adresów `url.current` / `url.previous` — jeśli adresy się różnią, mamy do czynienia z kanibalizacją. | Fraza | ID frazy | KID | Domena | Liczba słów | Marka | Pozycja | Pozycja poprz. | Zmiana pozycji | Wzrosty | Spadki | Bez zmian | Widoczność | Widoczność poprz. | Δ widoczności | Widoczność % | CPC | Wyszukiwania/mies. | Trudność | Trend (12 mies.) | Szczyt trendu | URL bieżący | URL poprzedni | Snippety SERP | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | korektor maybelline | 4663 | 000fd51efa78d65196f81fd56938c4ad | zalando.pl | 2 | | 27 | 10 | 17 | 0 | 0 | 0 | 0 | 44.66 | -44.66 | -1 | 1.41 | 2900 | 47 | [3600,2900,2400,2400,2400,2400,2900,2900,3600,3600,3600,5400] | [true] | zalando.pl/maybelline-new-york-instant-concealer-korektor-mj331e00a-s16.html | zalando.pl/maybelline-new-york-instant-anti-age-eraser-color-corrector-concealer-korektor-lila-mj331e06e-i11.html | ["image_thumbs","people_also_ask"] | | trzewiki adidas | 5283 | 00120febf81775e90ad212e342df6450 | zalando.pl | 2 | | 17 | 3 | 14 | 0 | 0 | 0 | 0 | 5.38 | -5.38 | -1 | 0 | 50 | 48 | [20,10,10,20,70,170,110,40,70,50,20,10] | [true,true,true] | zalando.pl/obuwie-meskie-trzewiki/adidas/ | zalando.pl/obuwie-meskie-trzewiki-sznurowane/adidas/ | ["image_thumbs"] | _zalando.pl (limit: 2) — frazy z kanibalizacją (różne url.current i url.previous). Wszystkie adresowalne pola wiersza (pominięto mapę historii pozycji `statistics.position.history` — ma zmienne klucze-daty; jest w JSON-ie i sekcji „Struktura odpowiedzi”)._ --- ## Żądanie `POST` `/api/visibility_analysis/reports/cannibalization/getKeywords` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1 } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "limit": 2, "page": 1 } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/cannibalization/getKeywords' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "limit": 2 }' ``` ### Parametry ```ts type CannibalizationGetKeywordsRequest = { /** * **Wymagane**. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`. */ domain: string; /** * **Wymagane**. Sposób interpretacji `domain`. * - `topLevelDomain` — cała domena (najczęstszy przypadek) * - `subdomain` — pojedyncza subdomena * - `catalog` — ścieżka/katalog * - `url` — dokładny URL */ fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url'; /** * **Wymagane**. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem `Unknown country_id`. */ country_id: number; /** * Liczba wierszy na stronę. * @default 10 */ limit?: number; /** * Numer strony. * @default 1 */ page?: number; /** * Okres odniesienia do porównania (baza wykrywania zmian kanibalizacji). * Dozwolone: `week_ago_monday` (domyślny), `last_monday`, `yesterday`. */ days_compare_mode?: 'week_ago_monday' | 'last_monday' | 'yesterday'; /** * Grupy filtrów. Dozwolone pola m.in.: `keyword`, `statistics.searches.current`, * `statistics.cpc.current`, `statistics.difficulty.current`, * `statistics.url.current` (nowy URL), `statistics.url.previous` (stary URL). * Pusta tablica = brak filtrowania. */ filtering?: unknown[]; /** * Sortowanie — **pojedynczy obiekt** `{ prop, dir }`. Dozwolone `prop`: * `keyword`, `statistics.position.current|previous|diff`, * `statistics.visibility.current|previous|diff`, `statistics.searches.current`, * `statistics.cpc.current`, `statistics.difficulty.current`, * `statistics.url.is_change`, `words_count`. Nieznany klucz → sort domyślny * (`keyword_id` rosnąco). */ order?: { prop: string; dir: 'asc' | 'desc' }; } export default CannibalizationGetKeywordsRequest ``` > **Ostrzeżenie:** > Trzy parametry są **wymagane**: **`domain`**, **`fetch_mode`** oraz **`country_id`**. Nieznane `country_id` zwraca `418` z komunikatem `Unknown country_id`. Parametry `page` i `limit` są opcjonalne (domyślnie `1` / `10`). Endpoint **obsługuje** `order` (obiekt `{ prop, dir }`) oraz `filtering` — **zweryfikowane na prod** (`order` po `statistics.searches.current` realnie zmienia kolejność asc/desc). To odróżnia ten raport od raportów sekcji (`sections/*`), które `order`/`filtering` ignorują. ## Odpowiedź W przypadku powodzenia otrzymujesz `data` (tablicę wierszy z frazami dotkniętymi kanibalizacją) oraz `pagination`. Kluczowa jest para `statistics.url.current` / `statistics.url.previous` — **różne adresy oznaczają kanibalizację**. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "keyword": "korektor maybelline", "keyword_id": 4663, "statistics": { "position": { "current": 27, "previous": 10 }, "url": { "current": "zalando.pl/maybelline-new-york-instant-concealer-korektor-mj331e00a-s16.html", "previous": "zalando.pl/maybelline-new-york-instant-anti-age-eraser-color-corrector-concealer-korektor-lila-mj331e06e-i11.html" } /* … */ } } ], "pagination": { "page_count": 1429, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 2857, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "keyword": "korektor maybelline", "keyword_id": 4663, "kid": "000fd51efa78d65196f81fd56938c4ad", "domain": "zalando.pl", "words_count": 2, "brand": "", "statistics": { "position": { "current": 27, "previous": 10, "diff": 17, "changes": { "wins": 0, "losses": 0, "no_changes": 0 }, "history": { "2026-06-25": 27 } }, "visibility": { "current": 0, "previous": 44.66, "diff": -44.66, "percent": -1, "history": null }, "cpc": { "current": 1.41 }, "searches": { "current": 2900 }, "difficulty": { "current": 47 }, "trends": { "history": [3600, 2900, 2400, 2400, 2400, 2400, 2900, 2900, 3600, 3600, 3600, 5400], "peak": [true] }, "url": { "current": "zalando.pl/maybelline-new-york-instant-concealer-korektor-mj331e00a-s16.html", "previous": "zalando.pl/maybelline-new-york-instant-anti-age-eraser-color-corrector-concealer-korektor-lila-mj331e06e-i11.html" }, "snippets": { "current": ["image_thumbs", "people_also_ask"] } } }, { "keyword": "trzewiki adidas", "keyword_id": 5283, "kid": "00120febf81775e90ad212e342df6450", "domain": "zalando.pl", "words_count": 2, "brand": "", "statistics": { "position": { "current": 17, "previous": 3, "diff": 14, "changes": { "wins": 0, "losses": 0, "no_changes": 0 }, "history": { "2026-06-26": 17 } }, "visibility": { "current": 0, "previous": 5.38, "diff": -5.38, "percent": -1, "history": null }, "cpc": { "current": 0 }, "searches": { "current": 50 }, "difficulty": { "current": 48 }, "trends": { "history": [20, 10, 10, 20, 70, 170, 110, 40, 70, 50, 20, 10], "peak": [true, true, true] }, "url": { "current": "zalando.pl/obuwie-meskie-trzewiki/adidas/", "previous": "zalando.pl/obuwie-meskie-trzewiki-sznurowane/adidas/" }, "snippets": { "current": ["image_thumbs"] } } } ], "pagination": { "page_count": 1429, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 2857, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type CannibalizationKeywordsResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze z frazami dotkniętymi kanibalizacją */ data: CannibalizationKeywordRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type CannibalizationKeywordRow = { /** Treść frazy kluczowej */ keyword: string; keyword_id: number; kid: string; domain: string; /** Liczba słów we frazie */ words_count: number; /** Marka przypisana do frazy (może być pustym łańcuchem) */ brand: string; statistics: { /** Pozycja bieżąca i poprzednia; `history` to mapa data → pozycja */ position: { current: number; previous: number; diff: number; changes: { wins: number; losses: number; no_changes: number }; history: Record }; visibility: { current: number; previous: number; diff: number; percent: number; history: null }; cpc: { current: number }; searches: { current: number }; difficulty: { current: number }; /** `history` — 12 miesięcy wyszukiwań; `peak` — tablica wartości logicznych */ trends: { history: number[]; peak: boolean[] }; /** Różne adresy `current` i `previous` oznaczają kanibalizację */ url: { current: string; previous: string }; snippets: { current: string[] }; }; } export default CannibalizationKeywordsResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, database, timeout, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > **`418`** zwracany jest także dla błędów walidacji. Nieznane `country_id` → komunikat `Unknown country_id`. Pominięcie któregokolwiek wymaganego pola (`domain`, `fetch_mode`, `country_id`) skutkuje błędem walidacji. ## Powiązane akcje - `getKeywords` — frazy dotknięte kanibalizacją wraz ze statystykami (ta strona) - [`getSections`](/modules/visibility_analysis/va-cannibalization-getSections) — liczba skanibalizowanych fraz w podziale na sekcje URL