--- title: "Konkurenci (raport) (`getData`)" source: https://docs.senuto.com/modules/visibility_analysis/va-competitors-getData api: POST /api/visibility_analysis/reports/competitors/getData --- # 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`). | Domena | Domena główna | Wspólne frazy | TOP3 · bieżąca | TOP3 · poprz. | TOP3 · zmiana | TOP3 · % | TOP3 · historia | TOP10 · bieżąca | TOP10 · poprz. | TOP10 · zmiana | TOP10 · % | TOP10 · historia | TOP50 · bieżąca | TOP50 · poprz. | TOP50 · zmiana | TOP50 · % | TOP50 · historia | Widoczność · bieżąca | Widoczność · poprz. | Widoczność · zmiana | Widoczność · % | Widoczność · historia | Ekwiwalent Ads · bieżąca | Ekwiwalent Ads · poprz. | Ekwiwalent Ads · zmiana | Ekwiwalent Ads · % | Ekwiwalent Ads · historia | Ranga domeny · bieżąca | Ranga domeny · poprz. | Ranga domeny · zmiana | Ranga domeny · % | Ranga domeny · historia | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | ccc.eu | false | 849 | 10276 | 10297 | -21 | -0.002 | | 22397 | 22415 | -18 | -0.0008 | | 72842 | 72989 | -147 | -0.002 | | 1794218.55 | 1804132.4 | -9913.85 | -0.0055 | | 1225878.21 | 1225878.21 | 0 | 0 | | 262 | 260 | 2 | 0.0077 | | | www2.hm.com | false | 623 | 8920 | 8933 | -13 | -0.0015 | | 20055 | 20105 | -50 | -0.0025 | | 84146 | 84219 | -73 | -0.0009 | | 3281018.52 | 3272619.07 | 8399.45 | 0.0026 | | 4465558.99 | 4465558.99 | 0 | 0 | | 0 | 0 | 0 | 0 | | _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`)._ > **Ostrzeżenie:** > 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 `, `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, "page": 1, "limit": 2 } ``` **cURL** ```bash 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 ```ts type CompetitorsGetDataRequest = { /** * **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; /** * Numer strony. * @default 1 */ page?: number; /** * Liczba wierszy na stronę. * @default 10 */ limit?: number; } export default CompetitorsGetDataRequest ``` ## 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** ```json filename="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 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "domain": "ccc.eu", "is_main_domain": false, "common_keywords": 849, "statistics": { "top3": { "current": 10276, "previous": 10297, "diff": -21, "percent": -0.002, "history": null }, "top10": { "current": 22397, "previous": 22415, "diff": -18, "percent": -0.0008, "history": null }, "top50": { "current": 72842, "previous": 72989, "diff": -147, "percent": -0.002, "history": null }, "visibility": { "current": 1794218.55, "previous": 1804132.4, "diff": -9913.85, "percent": -0.0055, "history": null }, "ads_equivalent": { "current": 1225878.21, "previous": 1225878.21, "diff": 0, "percent": 0, "history": null }, "domain_rank": { "current": 262, "previous": 260, "diff": 2, "percent": 0.0077, "history": null } } }, { "domain": "www2.hm.com", "is_main_domain": false, "common_keywords": 623, "statistics": { "top3": { "current": 8920, "previous": 8933, "diff": -13, "percent": -0.0015, "history": null }, "top10": { "current": 20055, "previous": 20105, "diff": -50, "percent": -0.0025, "history": null }, "top50": { "current": 84146, "previous": 84219, "diff": -73, "percent": -0.0009, "history": null }, "visibility": { "current": 3281018.52, "previous": 3272619.07, "diff": 8399.45, "percent": 0.0026, "history": null }, "ads_equivalent": { "current": 4465558.99, "previous": 4465558.99, "diff": 0, "percent": 0, "history": null }, "domain_rank": { "current": 0, "previous": 0, "diff": 0, "percent": 0, "history": null } } } ], "pagination": { "page_count": 27, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 53, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type CompetitorsGetDataResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze konkurentów */ data: CompetitorRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type CompetitorRow = { /** Domena konkurenta */ domain: string; /** Czy wiersz dotyczy badanej (głównej) domeny */ is_main_domain: boolean; /** Liczba fraz wspólnych z badaną domeną */ common_keywords: number; statistics: { /** Liczba fraz w TOP3 */ top3: MetricValue; /** Liczba fraz w TOP10 */ top10: MetricValue; /** Liczba fraz w TOP50 */ top50: MetricValue; /** Widoczność (szacowany miesięczny ruch organiczny) */ visibility: MetricValue; /** Ekwiwalent Ads — szacowany koszt równoważnego ruchu płatnego */ ads_equivalent: MetricValue; /** Ranga domeny; `0` oznacza brak rangi */ domain_rank: MetricValue; }; } type MetricValue = { /** Wartość bieżąca */ current: number; /** Wartość z poprzedniego pomiaru */ previous: number; /** Różnica current - previous */ diff: number; /** Zmiana względna (ułamek, np. -0.0055 = -0,55%) */ percent: number; /** W tym raporcie zawsze null */ history: null; } export default CompetitorsGetDataResponse ``` ## 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 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`.