Skip to Content
ModułyBaza słów kluczowychGrupy frazy

Szczegóły frazy: grupy frazy (getGroups)

POST/api/keywords_analysis/reports/keyword_details/getGroups

Zwraca grupy tematyczne fraz powiązanych z podanym słowem kluczowym wraz z liczbą fraz w grupie (keywords_sum). Pozwala zobaczyć strukturę tematu, zanim zejdziesz do pojedynczych fraz.

Raport odpytujesz wprost frazą i krajem — bez wcześniejszego tworzenia zadania w Analizie SERP. Jedno żądanie zastępuje ścieżkę „utwórz zadanie → sprawdź status → pobierz wynik” i nie zużywa limitu zadań.

Żądanie

POST /api/keywords_analysis/reports/keyword_details/getGroups

Nagłówki: Authorization: Bearer <token>, Content-Type: application/json. Parametry przekazuje się w treści żądania.

żądanie.jsonc
{
  "keyword": "hamak",
  "country_id": 1,
  "limit": 10
}

Parametry

NameTypeDefault
keywordstring

Wymagane. Fraza kluczowa, dla której pobierany jest raport. Pusty string zwraca 418.

country_idnumber

Wymagane. Identyfikator kraju; musi istnieć w słowniku krajów — nieznana wartość zwraca 418 z komunikatem Unknown country_id. Uwaga: 200 jest tu mapowane na 1.

1
filteringRecord<string, unknown>[]

Ignorowane przez tę akcję. Sprawdzone na produkcji: poprawny filtr nie zmienia liczby wyników, a nieznany key zwraca 200 zamiast 418. Filtruj po stronie klienta.

pagenumber

Numer strony wyników.

limitnumber

Liczba wierszy na stronę.

Zarówno keyword, jak i country_id są wymagane. Nieznane country_id zwraca 418 z Unknown country_id, a wartość 200 jest mapowana na 1 — dla Polski trafisz więc do bazy 1.0, nie 2.0.

Parametr filtering nie działa na tej akcji. Sprawdzone na produkcji: poprawny filtr nie zmienia liczby wyników, a nieznany klucz zwraca 200 zamiast 418. Zawężaj wyniki po swojej stronie.

Paginacja jest pozorna. Dla limit 1, 3, 10 i 100 API zwróciło odpowiednio 1, 3, 10 i 100 wierszy, a count zawsze równał się liczbie zwróconych wierszy przy page_count: 1 i has_next_page: false. Nie stronicuj — pobierz całość jednym dużym limit.

Odpowiedź

Przykład poniżej to rzeczywista odpowiedź produkcyjna dla frazy hamak (country_id: 1), skrócona do jednego wiersza.

przykładowa-odpowiedź
{
  "success": true,
  "data": [
    {
      "group": "do hamaka",
      "keywords_sum": 234
    }
  ],
  "pagination": {
    "page_count": 1,
    "current_page": 1,
    "has_next_page": false,
    "has_prev_page": false,
    "count": 2,
    "limit": 2
  }
}

Struktura odpowiedzi

NameTypeDefault
successboolean
data{ group: string; keywords_sum: number; }[]
pagination{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }

Paginacja pozorna. count równa się liczbie zwróconych wierszy, page_count to zawsze 1, a has_next_page zawsze false — niezależnie od limit. Nie da się na tym zbudować pętli stronicującej; pobierz całość jednym dużym limit.

Błędy

Błędy tego endpointu przychodzą we wspólnej kopercie ze statusem 418.

Powiązane akcje

Wszystkie poniższe raporty przyjmują tę samą parę keyword + country_id:

Ostatnia aktualizacja:
Pytania o frazęLiderzy tematu