--- title: "Analiza konkurentów (`getData`)" source: https://docs.senuto.com/modules/visibility_analysis/va-competitors-analysis-getData api: POST /api/visibility_analysis/tools/competitors_analysis/getData --- # Analiza konkurentów (`getData`) **`POST /api/visibility_analysis/tools/competitors_analysis/getData`** Narzędzie **Analiza konkurentów** porównuje frazy kluczowe domeny głównej z frazami konkurentów. W zależności od trybu (`mode`) zwraca frazy wspólne, frazy konkurentów, których brakuje domenie głównej, albo frazy domeny głównej. Każdy wiersz zawiera statystyki frazy (średnia liczba wyszukiwań, CPC, trendy, trudność) oraz pozycję i URL dla każdej z porównywanych domen. Wynik jest stronicowany. | Fraza | Wyszukiwania/mies. | CPC | Trudność | Trend (12 mies.) | Parametry | | --- | --- | --- | --- | --- | --- | | nike | 673000 | 1.31 | 77 | [673000,673000,673000,673000,673000,673000,1000000,673000,550000,550000,823000,550000] | [] | | adidas | 368000 | 0.68 | 77 | [450000,368000,368000,450000,368000,301000,368000,301000,301000,368000,550000,450000] | [] | _zalando.pl vs eobuwie.com.pl (mode: common_keywords, limit: 2). Wszystkie adresowalne pola stałe wiersza (pominięto klucze dynamiczne per domena — ``, `_pos`, `_url` — bo zawierają kropkę w nazwie i nie da się ich zaadresować ścieżką; są w JSON-ie i sekcji „Struktura odpowiedzi”)._ --- ## Żądanie `POST` `/api/visibility_analysis/tools/competitors_analysis/getData` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "main_domain": { "domain": "zalando.pl", "gte": 1, "lte": 50 }, "competitors_domains": [ { "domain": "eobuwie.com.pl", "gte": 1, "lte": 50 } ], "mode": "common_keywords" } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "main_domain": { "domain": "zalando.pl", "gte": 1, "lte": 50 }, "competitors_domains": [ { "domain": "eobuwie.com.pl", "gte": 1, "lte": 50 } ], "mode": "common_keywords", "country_id": 1, "page": 1, "limit": 2 } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/tools/competitors_analysis/getData' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "main_domain": { "domain": "zalando.pl", "gte": 1, "lte": 50 }, "competitors_domains": [{ "domain": "eobuwie.com.pl", "gte": 1, "lte": 50 }], "mode": "common_keywords", "limit": 2 }' ``` ### Parametry ```ts type GetCompetitorsAnalysisRequest = { /** * **Wymagane** (walidator `DataValidator`). Domena główna analizy jako **obiekt** — * nie zwykły string. Pola `gte` i `lte` (zakres pozycji w TOP wyników) są wymagane * wewnątrz obiektu. */ main_domain: DomainWithPositionRange; /** * **Wymagane**. Niepusta **tablica** obiektów o tej samej strukturze co `main_domain` — * konkurenci, z którymi porównywana jest domena główna. Każdy obiekt musi zawierać * `domain`, `gte` i `lte`. */ competitors_domains: DomainWithPositionRange[]; /** * **Wymagane**. Tryb porównania (klasa `KeywordsFetchMode`): * - `common_keywords` — frazy wspólne domeny głównej i konkurentów, * - `competitors_keywords` — frazy konkurentów, których brakuje domenie głównej, * - `main_domain_keywords` — frazy domeny głównej. */ mode: "common_keywords" | "competitors_keywords" | "main_domain_keywords"; /** * ID kraju (bazy słów kluczowych). * @default 1 (Polska) */ country_id?: number; /** * Numer strony paginacji. * @default 1 */ page?: number; /** * Rozmiar strony paginacji. Odbija się w `pagination.limit`. * @default 10 */ limit?: number; /** * Filtrowanie wyników. Rejestr dostępnych pól filtrowania jest **niezweryfikowany** — * używaj ostrożnie i testuj na małych zapytaniach. */ filtering?: Record; /** * Sortowanie wyników. Podobnie jak `filtering` — rejestr pól niezweryfikowany. */ order?: Record; } type DomainWithPositionRange = { /** **Wymagane**. Nazwa domeny, np. `zalando.pl`. */ domain: string; /** **Wymagane w obiekcie**. Dolna granica zakresu pozycji (np. `1`). */ gte: number; /** **Wymagane w obiekcie**. Górna granica zakresu pozycji (np. `50`). */ lte: number; } export default GetCompetitorsAnalysisRequest ``` > **Ostrzeżenie:** > Pamiętaj, że `main_domain` to **obiekt** (nie string), a `competitors_domains` to **tablica obiektów** — każdy z kompletem `domain` + `gte` + `lte`. Brak któregokolwiek z pól wymaganych kończy się odpowiedzią `418` z `invalid_data` i kluczem `_required`. > **Ostrzeżenie:** > Endpoint obsługuje metodę **`POST`** z ciałem JSON (`Authorization: Bearer `, `Content-Type: application/json`). Narzędzia z grupy `tools` mają **dzienny limit użyć** — po jego przekroczeniu API zwraca `418`. **Pułapka w strukturze odpowiedzi:** poza polami stałymi (`keyword`, `cpc`, `searches`, `trends`, `difficulty`, `params`) każdy wiersz zawiera klucze **dynamiczne per domena**, zdublowane w dwóch postaciach — obiekt `"": { pos, url }` **oraz** spłaszczone pola `"_pos"` i `"_url"` z tymi samymi wartościami. ## Odpowiedź Po pomyślnym żądaniu otrzymujesz `data` (tablicę wierszy fraz kluczowych) oraz `pagination`. Wiersz składa się z pól stałych — `keyword`, `cpc`, `searches`, `trends` (12 miesięcy), `difficulty`, `params` — oraz z kluczy **dynamicznych per domena** dla domeny głównej i każdego konkurenta. Dane pozycji każdej domeny są zdublowane: raz jako obiekt `"": { pos, url }`, a raz jako spłaszczone pola `"_pos"` i `"_url"` z tymi samymi wartościami. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "keyword": "nike", "cpc": 1.31, "searches": 673000, "difficulty": 77, "zalando.pl": { "pos": 3, "url": "zalando.pl/nike/" }, "eobuwie.com.pl": { "pos": 2, "url": "eobuwie.com.pl/c/eobuwie/marka:nike" } } ], "pagination": { "page_count": 37217, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 74433, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "keyword": "nike", "cpc": 1.31, "searches": 673000, "trends": [673000, 673000, 673000, 673000, 673000, 673000, 1000000, 673000, 550000, 550000, 823000, 550000], "difficulty": 77, "params": [], "zalando.pl": { "pos": 3, "url": "zalando.pl/nike/" }, "zalando.pl_pos": 3, "zalando.pl_url": "zalando.pl/nike/", "eobuwie.com.pl": { "pos": 2, "url": "eobuwie.com.pl/c/eobuwie/marka:nike" }, "eobuwie.com.pl_pos": 2, "eobuwie.com.pl_url": "eobuwie.com.pl/c/eobuwie/marka:nike" }, { "keyword": "adidas", "cpc": 0.68, "searches": 368000, "trends": [450000, 368000, 368000, 450000, 368000, 301000, 368000, 301000, 301000, 368000, 550000, 450000], "difficulty": 77, "params": [], "zalando.pl": { "pos": 10, "url": "zalando.pl/adidas-originals/" }, "zalando.pl_pos": 10, "zalando.pl_url": "zalando.pl/adidas-originals/", "eobuwie.com.pl": { "pos": 2, "url": "eobuwie.com.pl/c/eobuwie/marka:adidas" }, "eobuwie.com.pl_pos": 2, "eobuwie.com.pl_url": "eobuwie.com.pl/c/eobuwie/marka:adidas" } ], "pagination": { "page_count": 37217, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 74433, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type GetCompetitorsAnalysisResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Wiersze fraz kluczowych z pozycjami porównywanych domen */ data: CompetitorsAnalysisRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; /** Łączna liczba fraz spełniających kryteria (w przykładzie: 74433) */ count: number; /** Wartość przekazanego `limit` */ limit: number; }; } type CompetitorsAnalysisRow = { /** Fraza kluczowa */ keyword: string; /** Średni koszt kliknięcia (CPC) */ cpc: number; /** Średnia miesięczna liczba wyszukiwań */ searches: number; /** Liczba wyszukiwań w ostatnich 12 miesiącach (tablica 12 liczb) */ trends: number[]; /** Trudność frazy (0-100) */ difficulty: number; /** Parametry frazy */ params: unknown[]; /** * **Klucze dynamiczne per domena** — dla domeny głównej i każdego konkurenta wiersz * zawiera trzy wpisy o kluczu pochodnym od nazwy domeny: * - `""`: obiekt `{ pos: number, url: string }`, * - `"_pos"`: ta sama pozycja jako liczba, * - `"_url"`: ten sam URL jako string. * Wartości w postaci obiektowej i spłaszczonej są identyczne (duplikacja). */ [domainKey: string]: { pos: number; url: string } | number | string | unknown[]; } export default GetCompetitorsAnalysisResponse ``` ## 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 przy błędach walidacji: brak pól wymaganych (`main_domain`, `competitors_domains`, `mode`) skutkuje `invalid_data` z regułą `_required` dla brakującego pola. Pola `gte` i `lte` są wymagane **wewnątrz** obiektów domen — pominięcie ich w `main_domain` lub w elemencie `competitors_domains` również kończy się `418`. Kod `418` pojawia się także po **przekroczeniu dziennego limitu użyć** narzędzi `tools`. ## Powiązane akcje - `getData` — porównanie fraz domeny głównej z konkurentami (ta strona; jedyna akcja narzędzia)