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	673 000	1,31	77	673000, 673000, 673000, 673000, 673000, 673000, 1000000, 673000, 550000, 550000, 823000, 550000	—
adidas	368 000	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 — <domena>, <domena>_pos, <domena>_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 <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żą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

żą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


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

Name	Type	Default
`main_domain`	`DomainWithPositionRange` 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.
`competitors_domains`	`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`.
`mode`	`"common_keywords" \| "competitors_keywords" \| "main_domain_keywords"` 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.
`country_id`	`number` ID kraju (bazy słów kluczowych).	`1 (Polska)`
`page`	`number` Numer strony paginacji.	`1`
`limit`	`number` Rozmiar strony paginacji. Odbija się w `pagination.limit`.	`10`
`filtering`	`Record<string, unknown>` Filtrowanie wyników. Rejestr dostępnych pól filtrowania jest niezweryfikowany — używaj ostrożnie i testuj na małych zapytaniach.
`order`	`Record<string, unknown>` Sortowanie wyników. Podobnie jak `filtering` — rejestr pól niezweryfikowany.

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.

Endpoint obsługuje metodę POST z ciałem JSON (Authorization: Bearer <token>, 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 "<domena>": { pos, url } oraz spłaszczone pola "<domena>_pos" i "<domena>_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 "<domena>": { pos, url }, a raz jako spłaszczone pola "<domena>_pos" i "<domena>_url" z tymi samymi wartościami.

Skrócona

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 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`CompetitorsAnalysisRow[]` Wiersze fraz kluczowych z pozycjami porównywanych domen
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }` Metadane paginacji

Błędy

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

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)

Analiza konkurentów (getData)