Konkurenci: ranking (`getRanking`)

POST/api/rank_tracker/reports/competitors/getRanking

Zwraca ranking domeny projektu oraz jej konkurentów według statystyk pozycji i widoczności — porównanie dwóch snapshotów pomiarowych. Dla każdej domeny otrzymujesz zestaw około 26 metryk (rozkład pozycji TOP3/TOP10/TOP50, widoczność organiczna, potencjał, budżet itd.), a każda metryka zawiera wartość starszą, nowszą, różnicę i zmianę procentową. Wynik jest stronicowany po domenach.

Podgląd · 6 z 12 kolumn

Domena	ID	Domena projektu	Widoczność org.	Średnia pozycja	TOP3
pies.pl	87944	tak	0	50	0
fajnyzwierzak.pl	55578	—	—	45,99	—

wiersze z data.data — podwójna koperta: domena projektu (project_domain: true) i konkurent. Pokazano identyfikatory i najważniejsze metryki (recent_value); komplet ~24 metryk (starsza/nowsza/różnica/%) jest w JSON i sekcji „Struktura odpowiedzi”.

Żądanie

POST /api/rank_tracker/reports/competitors/getRanking

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "project_id": null,
  "date_min": "2026-06-20",
  "date_max": "2026-06-29"
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "project_id": null,
  "date_min": "2026-06-20",
  "date_max": "2026-06-29",
  "limit": 2
}

cURL


curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/competitors/getRanking' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "project_id": null, "date_min": "2026-06-20", "date_max": "2026-06-29", "limit": 2 }'

Parametry

Name	Type	Default
`project_id`	`number` Wymagane (walidator `CompetitorsValidator`). ID projektu Rank Tracker. Musi należeć do użytkownika — w przeciwnym razie `418` z komunikatem `Unauthorized access`. Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
`date_min`	`string` Wymagane. Początek zakresu porównania w formacie `YYYY-MM-DD`. Nie może być późniejszy niż dziś ani późniejszy niż `date_max`. Uwaga: jako starszy snapshot API bierze poprzedni dostępny pomiar względem `date_max` (patrz pole `dates` w odpowiedzi), więc `date_min` nie zawsze będzie datą, z którą realnie porównano wyniki.
`date_max`	`string` Wymagane. Koniec zakresu porównania w formacie `YYYY-MM-DD` (≤ dziś, ≥ `date_min`). Odpowiada `dates.last_date` w odpowiedzi.
`limit`	`number` Rozmiar strony paginacji — liczonej po domenach (projekt + konkurenci).	`10`
`page`	`number` Numer strony paginacji.	`1`

Znany bug walidatora: gdy date_min jest późniejsze niż date_max, komunikaty błędów z DateRangeRules są odwrócone (komunikat o date_min dotyczy date_max i odwrotnie). Interpretuj wtedy błąd „na krzyż”.

Pułapki tego endpointu:

Podwójna koperta — zewnętrzne pole data zawiera własny obiekt z polami {success, rows, dates, data[]}. Lista domen siedzi więc w data.data, a nie bezpośrednio w data.
dates pokazuje faktycznie porównane snapshoty, a nie Twój zakres. last_date odpowiada date_max, ale previous_data to poprzedni dostępny pomiar — w zwalidowanym przykładzie 2026-06-28, mimo że w żądaniu podano date_min: 2026-06-20. Każde z pól to obiekt {timestamp, formatted}.
Wiersz domeny projektu różni się od wierszy konkurentów — ma project_domain: true i selectable: false, natomiast wiersze konkurentów mają zamiast tego tablice categories[] i technologies[].
Duplikaty i równoległe konwencje w statistics — metryki out_50 i out50 występują jednocześnie, podobnie jak przedziały w dwóch notacjach (top3/top4_10/top11_20/top21_50 obok 1_3/4_10/11_20/21_50).
Paginacja działa na poziomie zewnętrznym i liczy domeny (count: 4 = domena projektu + 3 konkurentów), a nie frazy.

Odpowiedź

Zwróć uwagę na podwójną kopertę: zewnętrzne data to obiekt z własnymi polami success, rows (łączna liczba domen), dates (faktycznie porównane snapshoty) i data (lista domen). Metadane pagination leżą na poziomie zewnętrznym, obok koperty. W skróconym przykładzie poniżej drugi wiersz (konkurent) pokazuje tylko część metryk — w oryginalnej odpowiedzi każdy wiersz zawiera komplet tych samych około 26 metryk co wiersz domeny projektu, każda w formacie {older_value, recent_value, diff, percent}.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": {
    "success": true,
    "rows": 4,
    "dates": {
      "last_date": { "timestamp": 1782691200, "formatted": "2026-06-29" },
      "previous_data": { "timestamp": 1782604800, "formatted": "2026-06-28" }
    },
    "data": [
      {
        "id": 87944,
        "domain": "pies.pl",
        "project_domain": true,
        "selectable": false,
        "statistics": {
          "organic_potential": { "older_value": 1100.0399999999984, "recent_value": 1100.0399999999984, "diff": 0, "percent": 0 },
          "avg_pos": { "older_value": 50, "recent_value": 50, "diff": 0, "percent": 0 },
          "out_50": { "older_value": 94, "recent_value": 94, "diff": 0, "percent": 0 }
        }
      }
    ]
  },
  "pagination": { "page_count": 2, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 4, "limit": 2 }
}

Pełna

przykładowa-odpowiedź (zwalidowana, 200; 2 z 4 domen)


{
  "success": true,
  "data": {
    "success": true,
    "rows": 4,
    "dates": {
      "last_date": { "timestamp": 1782691200, "formatted": "2026-06-29" },
      "previous_data": { "timestamp": 1782604800, "formatted": "2026-06-28" }
    },
    "data": [
      {
        "id": 87944,
        "domain": "pies.pl",
        "project_domain": true,
        "selectable": false,
        "statistics": {
          "organic_potential": { "older_value": 1100.0399999999984, "recent_value": 1100.0399999999984, "diff": 0, "percent": 0 },
          "ad_keywords": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "ad_pos_avg": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "ad_visibility": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "lost": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "no_change": { "older_value": 94, "recent_value": 94, "diff": 0, "percent": 0 },
          "out_50": { "older_value": 94, "recent_value": 94, "diff": 0, "percent": 0 },
          "avg_pos": { "older_value": 50, "recent_value": 50, "diff": 0, "percent": 0 },
          "ppc_cost": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "top10": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "top11_20": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "top21_50": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "top3": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "top4_10": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "top50": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "organic_visibility": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "wins": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "1_3": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "4_10": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "11_20": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "21_50": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "out50": { "older_value": 94, "recent_value": 94, "diff": 0, "percent": 0 },
          "budget": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 },
          "organic_potential_coverage": { "older_value": 0, "recent_value": 0, "diff": 0, "percent": 0 }
        }
      },
      {
        "id": 55578,
        "domain": "fajnyzwierzak.pl",
        "categories": [],
        "technologies": [],
        "statistics": {
          "lost": { "older_value": 8, "recent_value": 8, "diff": 0, "percent": 0 },
          "no_change": { "older_value": 72, "recent_value": 72, "diff": 0, "percent": 0 },
          "out_50": { "older_value": 75, "recent_value": 72, "diff": -3, "percent": -0.04 },
          "avg_pos": { "older_value": 46.33, "recent_value": 45.99, "diff": -0.34, "percent": -0.0073 },
          "top11_20": { "older_value": 4, "recent_value": 2, "diff": -2, "percent": -0.5 },
          "top21_50": { "older_value": 15, "recent_value": 20, "diff": 5, "percent": 0.3333 },
          "top50": { "older_value": 19, "recent_value": 22, "diff": 3, "percent": 0.1579 },
          "wins": { "older_value": 14, "recent_value": 14, "diff": 0, "percent": 0 }
        }
      }
    ]
  },
  "pagination": {
    "page_count": 2,
    "current_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "count": 4,
    "limit": 2
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` Flaga przetworzenia żądania (poziom zewnętrzny)
`data`	`{ success: boolean; rows: number; dates: { last_date: SnapshotDate; previous_data: SnapshotDate; }; data: RankingRow[]; }` Wewnętrzna koperta — uwaga na podwójne zagnieżdżenie
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number \| null; }` Paginacja na poziomie zewnętrznym; `count` = liczba domen

Błędy

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

Błędy walidacji zwracane są jako 418. Brak project_id, date_min lub date_max → invalid_data. Daty muszą być w formacie YYYY-MM-DD, nie późniejsze niż dziś, a date_min ≤ date_max — przy odwróconym zakresie pamiętaj o zamienionych komunikatach z DateRangeRules. Cudzy lub nieistniejący project_id → 418 z Unauthorized access, a nie 404.

Powiązane akcje

getRanking — ranking domen wg statystyk pozycji/widoczności dla dwóch snapshotów (ta strona)
getMatrix — macierz fraza × domena z pozycjami projektu i konkurentów w dwóch datach (POST, te same wymagane parametry)
Lista konkurentów projektu (domeny widoczne w obu raportach) pochodzi z GET /api/rank_tracker/management/competitors/list

Konkurenci: ranking (getRanking)