Konkurenci (raport) (`getData`)

POST/api/visibility_analysis/reports/competitors/getData

Zwraca listę konkurentów badanej domeny wraz z zestawem porównawczych statystyk widoczności: liczbą fraz w TOP3 / TOP10 / TOP50, widocznością, ekwiwalentem Ads oraz rangą domeny (domain_rank) — każda metryka z wartością bieżącą, poprzednią oraz zmianą (diff, percent). Dla każdego konkurenta podawana jest też liczba fraz wspólnych z badaną domeną (common_keywords).

Podgląd · 6 z 33 kolumn

Domena	Domena główna	Wspólne frazy	TOP3 · bieżąca	TOP3 · poprz.	TOP3 · zmiana
ccc.eu	nie	849	10 276	10 297	-21
www2.hm.com	nie	623	8920	8933	-13

zalando.pl (limit: 2) — najwięksi konkurenci wg liczby wspólnych fraz. Wszystkie adresowalne pola wiersza (brak pól o zmiennych kluczach; history jest w tym raporcie zawsze null).

To inny raport niż przestarzały domain_competitors/getTopCompetitors — ten raport nie jest przestarzały i to jego należy używać do porównywania konkurentów. Wymagane są trzy parametry: domain, fetch_mode oraz country_id (walidator CompetitorsValidator). Nieznane country_id zwraca 418 z komunikatem "Unknown country_id".

Żądanie

POST /api/visibility_analysis/reports/competitors/getData

Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "page": 1,
  "limit": 2
}

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/competitors/getData' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{
    "domain": "zalando.pl",
    "fetch_mode": "topLevelDomain",
    "country_id": 1
  }'

Parametry

Name	Type	Default
`domain`	`string` Wymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`.
`fetch_mode`	`"topLevelDomain" \| "subdomain" \| "catalog" \| "url"` Wymagane. Sposób interpretacji `domain`. `topLevelDomain` — cała domena (najczęstszy przypadek) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem `"Unknown country_id"`.
`page`	`number` Numer strony.	`1`
`limit`	`number` Liczba wierszy na stronę.	`10`

Odpowiedź

W przypadku powodzenia otrzymujesz data (tablicę wierszy konkurentów) oraz pagination. Każdy wiersz zawiera domenę konkurenta, flagę is_main_domain (czy to badana domena), liczbę wspólnych fraz common_keywords oraz obiekt statistics z sześcioma metrykami — każda w formacie { current, previous, diff, percent, history }. Wartość domain_rank równa 0 oznacza brak rangi dla danej domeny.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "domain": "ccc.eu", "is_main_domain": false, "common_keywords": 849, "statistics": { "top10": { "current": 22397 }, "visibility": { "current": 1794218.55 } /* … */ } }
  ],
  "pagination": { "page_count": 27, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 53, "limit": 2 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`CompetitorRow[]` Zwrócone wiersze konkurentów
`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 zwracany jest również dla błędów walidacji (CompetitorsValidator) — nie tylko przy ograniczeniu liczby żądań. Brak wymaganego pola (domain, fetch_mode, country_id) zwraca invalid_data z mapą params, a nieznane country_id zwraca komunikat "Unknown country_id".

Powiązane akcje

getData — porównawcze dane konkurentów (ta strona)

Pokrewny, ale przestarzały raport: domain_competitors/getTopCompetitors (kontroler oznaczony @deprecated) — zwraca listę największych konkurentów w starszym formacie. W nowych integracjach używaj opisywanego tu reports/competitors/getData.

Konkurenci (raport) (getData)