Pozycje: dane (getData)
/api/rank_tracker/reports/positions/getDataZwraca monitorowane słowa kluczowe projektu Rank Tracker dla wybranego zakresu dat, wraz z pozycjami dla każdego słowa kluczowego, historią pozycji, widocznością, CPC, liczbą wyszukiwań, snippetami SERP oraz podziałem na desktop/mobile.
| Fraza | ID | KID | Status | Widoczność org. | Widoczność org. poprz. |
|---|---|---|---|---|---|
| slowa kluczowe | 3025571 | 95b343081f25ecf51403b940b739bf78 | complete | 140 | 228 |
projekt Rank Trackera, zakres 2026-06-20 – 2026-06-29, limit: 2. Uwaga na niespójne typy: searches, current_position i diff_position to stringi, a cpc jest liczbą. Wszystkie adresowalne pola wiersza (pominięto mapy o zmiennych kluczach-datach: positions, desktop.positions_history, desktop.history, mobile.positions_history, mobile.history — są w JSON i sekcji „Struktura odpowiedzi”).
Żądanie
POST /api/rank_tracker/reports/positions/getData
Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.
Struktura żądania
Podstawowy
{
"project_id": null,
"date_min": "2026-06-20",
"date_max": "2026-06-29",
"limit": 2,
"page": 1
}Parametry
| Name | Type | Default |
|---|---|---|
project_id | numberWymagane. ID projektu Rank Tracker. Liczba całkowita nieujemna. Musisz mieć dostęp
do projektu (jako właściciel, administrator lub poprzez udostępnienie ACL) — w przeciwnym razie | |
date_min | stringWymagane. Początek zakresu dat, format | |
date_max | stringWymagane. Koniec zakresu dat, format | |
group_id | numberID grupy słów kluczowych w projekcie. Gdy ustawione, raport zwraca pozycje dla tej grupy zamiast dla całego projektu. | 0 |
competitor_id | numberID konkurenta. Gdy ustawione, raport zwraca pozycje dla tego konkurenta (w obrębie projektu lub grupy). | |
page | numberNumer strony. Liczba całkowita nieujemna. | 1 |
limit | numberLiczba wierszy na stronę. Liczba całkowita nieujemna (maxLimit kontrolera = 10000). | 10 |
mode | "desktop" | "mobile"Tryb pobierania pozycji (urządzenie). Po stronie serwera zamieniane na małe litery. | 'desktop' |
order | { prop: string; value: string; }Sortowanie. Obiekt z | |
filtering | { filters: { key: "keywords"; items: { value: string; match: "contain" | "startsWith" | "endsWith" | "exact" | "notContain"; }[]; }[]; }[]Filtrowanie — tablica grup (filtry w grupie łączone AND). Zwalidowany klucz:
|
Warianty wins / losses nie są parametrem w treści żądania — to segment URL (argument typeWinsOrLosses akcji): …/getData (pełny raport), …/getData/wins (słowa kluczowe, które zyskały od wczoraj), …/getData/losses (słowa kluczowe, które spadły). Odpowiednik eksportu: /api/rank_tracker/reports/exports/positions/getData[/wins|/losses].
Wymagane pola w treści żądania to project_id, date_min i date_max (daty w formacie YYYY-mm-dd, obie <= today, przy czym date_min <= date_max). W przeciwieństwie do Analizy widoczności, Rank Tracker nie używa domain / fetch_mode — operuje na project_id (plus opcjonalnie group_id / competitor_id). Ścieżka jest w snake_case i kanoniczna pod /api/rank_tracker/…. Warianty wins / losses to segmenty URL, a nie pola w treści żądania: …/getData/wins i …/getData/losses. Błędy walidacji zwracają 418 (invalid_data).
Filtrowanie
Opcjonalny parametr filtering odpowiada polu Filtry nad tabelą w raporcie pozycji projektu. To tablica grup; filtry w grupie łączone są operatorem AND (zob. wspólny Filter).
Zwalidowany klucz dla tego endpointu to keywords (filtr tekstowy przez items):
{
"project_id": null,
"date_min": "2026-06-17",
"date_max": "2026-06-30",
"filtering": [
{
"filters": [
{ "key": "keywords", "items": [{ "value": "pies", "match": "startsWith" }] }
]
}
]
}Operatory match dla keywords: contain, startsWith, endsWith, exact, notContain.
Zwalidowane na żywo (projekt 124572): bez filtra count = 395; z filtrem keywords startsWith "pies" → count = 8 (frazy „pies berneńczyk”, „pies rysunek”…). Aplikacja dołącza do filtra opcjonalne type: "string" i filterSourceType: "customFilter" — API działa też bez nich.
Odpowiedź
Po pomyślnym żądaniu otrzymujesz data (tablica wierszy słów kluczowych) oraz pagination. Zwróć uwagę, że kilka pól liczbowych zwracanych jest jako ciągi znaków (np. searches, current_position, diff_position, first_position, id), podczas gdy organic_visibility / organic_potential / cpc są liczbami — typowanie jest niespójne.
Skrócona
{
"success": true,
"data": [
{
"id": "3025571",
"keyword": "slowa kluczowe",
"current_position": "3",
"last_position": 2,
"positions": { "2026-06-20": 3, "2026-06-28": 2, "2026-06-29": 2 },
"statistics": { "positions_date_range": { "first": 3, "last": 2, "diff": 1 } }
}
],
"pagination": { "page_count": 198, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 395, "limit": 2 }
}Struktura odpowiedzi
| Name | Type | Default |
|---|---|---|
success | boolean
| |
data | RtPositionRow[]Zwrócone wiersze słów kluczowych | |
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 zwracane jest również dla błędów walidacji — nie tylko dla ograniczeń liczby zapytań. Brakujące lub źle sformatowane project_id / date_min / date_max skutkuje invalid_data wraz z mapą params. Zwróć uwagę na znany błąd w treści komunikatu dla reguły zakresu: brzmi on date_max must be less or equal than date_min, ale logika jest poprawna (date_min <= date_max). Projekt, do którego nie masz dostępu, zwraca Unauthorized access.
Powiązane akcje
getData— bieżące pozycje dla projektu (ta strona)getData/wins/getData/losses— słowa kluczowe, które zyskały / straciły pozycje względem wczoraj (segment URL, ta sama treść żądania)POST /api/rank_tracker/management/projects/getMyActiveProjects— pobranie listy swoich projektów, aby uzyskaćproject_id(zwraca{ id, domain, name })/api/rank_tracker/reports/exports/positions/getData[/wins|/losses]— odpowiednik tego raportu w formie eksportu