AI Overviews: konkurenci (`getCompetitors`)

POST/api/rank_tracker/reports/ai_overviews/getCompetitors

Porównuje obecność w blokach AI Overviews (AIO) domeny projektu Rank Tracker i jego konkurentów. Dla każdego konkurenta (lista pochodzi z GET /api/rank_tracker/management/competitors/list) zwracane są liczby fraz wspólnych i unikalnych oraz komplet dziewięciu metryk aio_* w ujęciu current / previous / diff / percent. Wynik jest stronicowany — paginacja liczona jest po konkurentach. Ten raport — w odróżnieniu od modułu AI Overviews w Analizie widoczności — nie jest przestarzały.

Podgląd · 6 z 43 kolumn

Domena	ID konkurenta	Frazy wspólne	Frazy unikalne (projekt)	Frazy unikalne (konkurent)	Widoczność AIO (bieżąco)
fajnyzwierzak.pl	55578	0	0	0	0
psy.pl	4741	0	0	0	0

Konkurenci w AI Overviews (limit 2). Projekt bez obecności w AIO ma zera w metrykach. Wszystkie adresowalne pola wiersza (obiekt statistics ma stałe klucze aio_*).

Żądanie

POST /api/rank_tracker/reports/ai_overviews/getCompetitors

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "project_id": null
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "project_id": null,
  "limit": 2,
  "page": 1
}

cURL


curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/ai_overviews/getCompetitors' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "project_id": null, "limit": 2 }'

Parametry

Name	Type	Default
`project_id`	`number` Wymagane. ID projektu Rank Tracker (`ProjectAccessRules`). Projekt musi należeć do użytkownika lub być mu udostępniony — cudzy `project_id` zwraca `418` z `Unauthorized access`. Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
`filtering`	`{ filters: { key: string; match?: "gt" \| "gte" \| "lt" \| "lte" \| "eq"; value: string \| number \| (string \| number)[]; complement?: boolean; }[]; conjunction?: "and" \| "or"; }[]` Filtrowanie listy konkurentów. Nieznany `key` → `418` `invalid_filtering`. Dozwolone klucze m.in.: `competitor_domain`, `aio_visibility`, `aio_count`, `aio_sov`, `shared_keywords`, `unique_keywords`, `unique_for_competitor` oraz aliasy `statistics.aio_*.current`/`.diff`. Operatory liczbowe: `gt` \| `gte` \| `lt` \| `lte` \| `eq`.
`page`	`number` Numer strony paginacji. Paginacja liczona jest po konkurentach projektu.	`1`
`limit`	`number` Rozmiar strony paginacji (liczba konkurentów na stronę). Odbija się w `pagination.limit`.	`10`

Pułapki typów i struktury: pola competitor_id, shared_keywords, unique_keywords oraz unique_for_competitor są zwracane jako stringi (np. "0"), a nie liczby. Obiekt statistics zawiera te same dziewięć metryk aio_* co akcja getStatistics, ale każda metryka ma wyłącznie {current, previous, diff, percent} — bez pola history; dodatkowo aio_sov niesie jeszcze competitorsAvgSov i competitorsMaxSov. Paginacja liczona jest po konkurentach (w projekcie testowym count: 3). project_id jest wymagane (ProjectAccessRules) — cudzy lub nieistniejący projekt zwraca 418 z Unauthorized access. Projekt testowy 87944 (pies.pl) nie ma bieżącej obecności w AIO, stąd zera w metrykach — struktura odpowiedzi jest pewna, wartości są przykładowe.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data (tablicę konkurentów) oraz pagination. Każdy element data opisuje jednego konkurenta: jego identyfikator i domenę, liczby fraz wspólnych i unikalnych (jako stringi) oraz obiekt statistics z dziewięcioma metrykami aio_*. count w pagination to łączna liczba konkurentów w projekcie.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    {
      "competitor_id": "55578",
      "competitor_domain": "fajnyzwierzak.pl",
      "shared_keywords": "0",
      "unique_keywords": "0",
      "unique_for_competitor": "0",
      "statistics": {
        "aio_visibility": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_sov": { "competitorsAvgSov": 0, "competitorsMaxSov": 0, "current": 0, "previous": 0, "diff": 0, "percent": 0 }
      }
    }
  ],
  "pagination": { "page_count": 2, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 3, "limit": 2 }
}

Pełna

przykładowa-odpowiedź (200)


{
  "success": true,
  "data": [
    {
      "competitor_id": "55578",
      "competitor_domain": "fajnyzwierzak.pl",
      "shared_keywords": "0",
      "unique_keywords": "0",
      "unique_for_competitor": "0",
      "statistics": {
        "aio_visibility": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_count": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_avg_pos": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_citations": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_keywords_total": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_sov": { "competitorsAvgSov": 0, "competitorsMaxSov": 0, "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_utilized_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_unique_keywords": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }
      }
    },
    {
      "competitor_id": "4741",
      "competitor_domain": "psy.pl",
      "shared_keywords": "0",
      "unique_keywords": "0",
      "unique_for_competitor": "0",
      "statistics": {
        "aio_visibility": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_count": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_avg_pos": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_citations": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_keywords_total": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_sov": { "competitorsAvgSov": 0, "competitorsMaxSov": 0, "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_utilized_potential": { "current": 0, "previous": 0, "diff": 0, "percent": 0 },
        "aio_unique_keywords": { "current": 0, "previous": 0, "diff": 0, "percent": 0 }
      }
    }
  ],
  "pagination": {
    "page_count": 2,
    "current_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "count": 3,
    "limit": 2
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`AioCompetitor[]` Konkurenci projektu wraz z metrykami AI Overviews
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number \| null; }` Metadane paginacji — liczone po konkurentach (`count` = łączna liczba konkurentów)

Błędy

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

418 jest zwracane również przy błędach walidacji i dostępu. Brak project_id skutkuje invalid_data, a cudzy lub nieistniejący project_id zwraca Unauthorized access (418), a nie 404 — dostęp weryfikuje ProjectAccessRules.

Powiązane akcje

getStatistics — zbiorcze metryki aio_* domeny projektu (z historią)
getKeywords — frazy projektu z obecnością w AI Overviews
getDistribution — rozkład obecności w blokach AIO
getCompetitors — porównanie z konkurentami (ta strona)
getOpportunities — frazy z szansą na obecność w AIO
getAioDetails — surowa treść bloku AIO dla pojedynczej frazy
getAioSources — źródła cytowane w blokach AIO

AI Overviews: konkurenci (getCompetitors)