Skip to Content
ModułyMonitoringMacierz pozycji

Konkurenci: macierz pozycji (getMatrix)

POST/api/rank_tracker/reports/competitors/getMatrix

Zwraca macierz fraza × domena: dla każdej frazy monitorowanej w projekcie Rank Tracker otrzymujesz pozycje domeny projektu oraz wszystkich jej konkurentów w dwóch datach (date_min i date_max). Oprócz pozycji każdy wiersz zawiera podstawowe metryki frazy (widoczność, potencjał, CPC, liczbę wyszukiwań, snippety SERP). Wynik jest stronicowany po frazach.

Żądanie

POST /api/rank_tracker/reports/competitors/getMatrix

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

Struktura żądania

żądanie-podstawowe.jsonc
{
  "project_id": null,
  "date_min": "2026-06-20",
  "date_max": "2026-06-29"
}

Parametry

NameTypeDefault
project_idnumber

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_minstring

Wymagane. Starsza z dwóch porównywanych dat w formacie YYYY-MM-DD (≤ dziś, ≤ date_max). W odpowiedzi staje się kluczem pierwszego snapshotu w mapie każdej domeny.

date_maxstring

Wymagane. Nowsza z dwóch porównywanych dat w formacie YYYY-MM-DD (≤ dziś, ≥ date_min). W odpowiedzi staje się kluczem drugiego snapshotu — to przy nim pojawiają się has_changes, is_grown i diff.

filtering{ filters: { key: string; match?: "gt" | "gte" | "lt" | "lte" | "eq"; value: string | number | (string | number)[]; complement?: boolean; }[]; conjunction?: "and" | "or"; }[]

Filtrowanie po frazach macierzy. Dozwolone klucze m.in.: position, current_position, last_position, searches, cpc, visibility, keywords, url. Operatory liczbowe: gt | gte | lt | lte | eq. ⚠️ Uwaga: ten endpoint (backend MySQL) na nieznany lub źle sformułowany filtr zwraca HTTP 500 (nie 418) — trzymaj się kluczy z listy i poprawnych typów wartości.

limitnumber

Rozmiar strony paginacji — liczonej po frazach.

10
pagenumber

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:

  1. Klucze dynamiczne — każdy wiersz ma po jednym polu na każdą domenę (np. "pies.pl", "psy.pl", "wamiz.pl", "fajnyzwierzak.pl"). Wartością jest mapa data → snapshot: pod kluczem date_min znajdziesz tylko {position}, a pod kluczem date_max — {position, has_changes, is_grown, diff}, przy czym is_grown pojawia się tylko gdy has_changes: true. Nie da się więc zdeserializować wiersza do sztywnego typu — użyj mapy.
  2. position: 0 oznacza brak domeny w TOP50 dla danej frazy — to nie jest pozycja pierwsza ani błąd.
  3. searches to string (np. "30"), a nie liczba — dotyczy to zarówno pola na poziomie wiersza, jak i statistics.searches.current.
  4. status: "complete" oznacza, że fraza została w pełni przetworzona dla porównywanych dat.
  5. Paginacja liczona jest po frazach (count: 94 = liczba fraz w projekcie), inaczej niż w getRanking, gdzie liczy domeny.

Odpowiedź

data to tablica wierszy — po jednym na frazę. Każdy wiersz łączy stałe pola frazy (keyword, status, searches, snippets, metryki) z dynamicznymi kluczami domen: domena projektu i każdy konkurent to osobne pole, którego nazwa jest nazwą domeny, a wartość — mapą data → snapshot pozycji. Pamiętaj, że position: 0 oznacza brak w TOP50, a searches jest stringiem.

przykładowa-odpowiedź (skrócona)
{
  "success": true,
  "data": [
    {
      "keyword": "ridgeback tajski",
      "status": "complete",
      "searches": "30",
      "pies.pl": {
        "2026-06-20": { "position": 0 },
        "2026-06-29": { "position": 0, "has_changes": false, "diff": 0 }
      },
      "psy.pl": {
        "2026-06-20": { "position": 2 },
        "2026-06-29": { "position": 10, "has_changes": true, "is_grown": false, "diff": 8 }
      }
    }
  ],
  "pagination": { "page_count": 47, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 94, "limit": 2 }
}

Struktura odpowiedzi

NameTypeDefault
successboolean

true przy powodzeniu; przy błędzie false i koperta z error

dataMatrixRow[]

Wiersze macierzy — jeden na frazę

pagination{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number | null; }

Paginacja liczona po frazach (count = liczba fraz w projekcie)

Błędy

NameTypeDefault
successfalse
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

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