Baza słów kluczowych: statystyki frazy (`getStatistics`)

GET/api/keywords_analysis/reports/keyword_details/getStatistics

Zwraca zbiorcze statystyki dla pojedynczej frazy kluczowej w wybranym kraju: liczbę wyszukiwań (searches), koszt kliknięcia (cpc), szacowaną wartość frazy (rank_value), listę cech SERP (params) oraz 12-miesięczny trend wyszukiwań (trends). To akcja zwracająca pojedynczy obiekt — bez paginacji.

Żądanie

GET /api/keywords_analysis/reports/keyword_details/getStatistics

Nagłówki: Authorization: Bearer <token>. Parametry przekazuje się w query stringu — nie w treści żądania.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "keyword": "hamak",
  "country_id": 1
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "keyword": "hamak",
  "country_id": 1,
  "page": 1,
  "limit": 10
}

cURL


curl --location --request GET 'https://api.senuto.com/api/keywords_analysis/reports/keyword_details/getStatistics?keyword=hamak&country_id=1' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE'

Parametry

Name	Type	Default
`keyword`	`string` Wymagane. Bazowa fraza kluczowa, dla której pobierane są statystyki (`searches`, `cpc`, `trends`, `rank_value`, `params`). Walidator: requirePresence + notEmptyString.
`country_id`	`number` Wymagane. Identyfikator kraju. Liczba całkowita większa od 0, musi istnieć w tabeli `Countries` — nieznana wartość zwraca `418` z komunikatem `Unknown country_id`. Uwaga: `country_id=200` jest mapowane na `1` w kontrolerze (alias legacy).	`1`
`page`	`number` Z `PaginationRules`. Opcjonalny i walidowany, lecz bez efektu dla tej akcji — `getStatistics` nie zwraca paginacji ani nie stosuje stronicowania.
`limit`	`number` Z `PaginationRules`. Opcjonalny i bez efektu dla tej akcji (brak paginacji w odpowiedzi).

Parametry muszą trafić do query stringu. Przekazanie ich w treści żądania (body) skutkuje 418, ponieważ kontroler czyta wyłącznie getQuery() i waliduje query, ignorując body.

To jest metoda GET — parametry przekazuje się w query stringu, nie w treści żądania. Wysłanie tego samego JSON-a w body (np. metodą POST) skutkuje 418 z invalid_data, ponieważ body jest ignorowane, a walidator widzi brak wymaganych pól. Zarówno keyword, jak i country_id są wymagane; nieznane country_id zwraca 418 z komunikatem Unknown country_id. Parametry page i limit są walidowane, lecz nie mają wpływu na tę akcję (brak paginacji w odpowiedzi).

Odpowiedź

Po pomyślnym żądaniu otrzymujesz kopertę { success, data }, gdzie data to pojedynczy obiekt ze statystykami frazy. Brak pola pagination — to akcja pojedynczego obiektu.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": {
    "searches": 22200,
    "cpc": 0.71,
    "rank_value": 5588.31
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`{ searches: number; cpc: number; rank_value: number; params: string[]; trends: number[]; }` Statystyki frazy (pojedynczy obiekt)

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). Brak keyword → {"success":false,"data":{"error":{"type":"invalid_data","params":{"keyword":{"_required":"This field is required"}}}}}. Nieznane country_id → 418 z komunikatem Unknown country_id. Wysłanie parametrów w body zamiast w query stringu również zwraca 418 (_required dla keyword i country_id).

Powiązane akcje

getStatistics — zbiorcze statystyki frazy (ta strona)
Pozostałe akcje raportu keyword_details przyjmują tę samą parę identyfikującą frazę: keyword + country_id.

Baza słów kluczowych: statystyki frazy (getStatistics)