Frazy: przypisania grup (`getData`)

POST/api/rank_tracker/reports/keywords/getData

Zwraca listę fraz projektu Rank Tracker wraz z informacją o ich przynależności do grup. Każdy element zawiera id frazy, jej nazwę (keyword) oraz przypisane grupy w dwóch formach: keyword_groups (string) i groups (tablica). Endpoint nie zwraca statystyk pozycji — te udostępnia akcja getData kontrolera positions (/api/rank_tracker/reports/positions/getData). Wynik jest stronicowany.

Fraza	ID	Grupy (string)	Grupy (tablica)
kiedy pierwsza cieczka u psa	8301076	piesek	piesek
jak wozic psa w aucie	19940324	piesek	piesek

projekt i grupa Rank Trackera, limit: 2. Zwróć uwagę: id frazy to string, a te same nazwy grup zwracane są w dwóch formach — keyword_groups (string) i groups (tablica). Wszystkie adresowalne pola wiersza.

Żądanie

POST /api/rank_tracker/reports/keywords/getData

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


// bez group_id — wszystkie frazy projektu
{
  "project_id": null,
  "limit": 2
}

Rozszerzony

żądanie-rozszerzone.jsonc


// z group_id — tylko frazy wskazanej grupy
{
  "project_id": null,
  "group_id": null,
  "limit": 2
}

cURL


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

Parametry

Name	Type	Default
`project_id`	`number` Wymagane. ID projektu Rank Tracker — jedyne pole twardo wymagane przez walidator (`GroupKeywordsValidator`). Musi należeć do użytkownika, inaczej zwracane jest `418` z `Unauthorized access`. Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
`group_id`	`number` Opcjonalne. ID grupy słów kluczowych. Bez tego pola endpoint zwraca wszystkie frazy projektu (zwalidowane: `count: "94"`); z nim — tylko frazy wskazanej grupy (zwalidowane: `count: "62"`).
`limit`	`number` Rozmiar strony paginacji. Odbija się w `pagination.limit`.	`10`
`page`	`number` Numer strony paginacji.	`1`

filtering działa tylko dla pola keyword. Filtr po keyword zawęża wynik poprawnie, ale filtr po groups — mimo że to pole jest w odpowiedzi — kończy się 500. Nieznany klucz również zwraca 500, a nie 418. Puste filtering ([] albo grupa bez warunków) jest bezpieczne i nie zmienia wyniku.

order nie ma efektu na tej akcji — dir: "ASC" i "DESC" zwracają wynik w tej samej, domyślnej kolejności. Sortuj po swojej stronie.

Pułapki potwierdzone na produkcji:

id frazy oraz pagination.count są zwracane jako stringi ("8301076", "94") — w odróżnieniu od pozostałych pól paginacji, które są liczbami. Rzutuj je po swojej stronie.
keyword_groups to jeden string z nazwami grup rozdzielonymi znakiem nowej linii (\n), np. "szcze\nBez grupy". Pole groups zawiera tę samą informację jako tablicę — używaj groups, jeśli nie chcesz parsować stringa.
group_id jest opcjonalne: bez niego endpoint zwraca wszystkie frazy projektu (count podaje ich łączną liczbę), a z nim zawęża wynik do fraz wskazanej grupy (count: "62").

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data (tablicę fraz z przypisaniami grup) oraz pagination. Zwróć uwagę na typy: id frazy i pagination.count to stringi, a keyword_groups to string wieloliniowy (separator \n) — jego tablicowym odpowiednikiem jest groups.

Skrócona

przykładowa-odpowiedź (skrócona, z group_id)


{
  "success": true,
  "data": [
    { "id": "8301076", "keyword": "kiedy pierwsza cieczka u psa", "keyword_groups": "piesek", "groups": ["piesek"] }
  ],
  "pagination": { "page_count": 31, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": "62", "limit": 2 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`KeywordWithGroups[]` Frazy projektu (lub grupy, jeśli podano `group_id`) z przypisaniami grup
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: string; limit: number; }` Metadane paginacji

Błędy

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

418 jest zwracane przy błędach walidacji (invalid_data) — nie tylko przy ograniczaniu liczby żądań. Brak project_id → 418 z {"project_id":{"_required":"This field is required"}}. Cudzy lub nieistniejący project_id zwraca 418 z Unauthorized access, a nie 404.

Powiązane akcje

getData — frazy projektu z przypisaniami grup, bez statystyk pozycji (ta strona)
getProjectKeywords — słowa kluczowe całego projektu
getGroupKeywords — lekka lista (id + keyword) ograniczona do jednej grupy
getSerpHtml — zapis HTML wyników SERP
getBestKeywords / getProjectsStatus — pozostałe akcje pomocnicze kontrolera

Frazy: przypisania grup (getData)