Historia fraz: dostępne daty (`getDates`)

POST/api/visibility_analysis/reports/history/keywords/getDates

Zwraca listę dostępnych punktów czasowych (dat) dla raportów historii fraz w danym kraju. Wywołaj tę akcję przed raportami historii (getData, getWins, getLosses, getAcquired, getLost) — wartości value z odpowiedzi nadają się wprost do pól date_min / date_max. Lista dat jest wspólna dla całej bazy danego kraju, dlatego żądanie nie wymaga domain ani fetch_mode.

Żądanie

POST /api/visibility_analysis/reports/history/keywords/getDates

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "country_id": 1
}

Parametry

Name	Type	Default
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`. Liczba całkowita większa od zera; musi istnieć w bazie krajów — nieznana wartość zwraca `418` z komunikatem `"Unknown country_id"`.

Wymagane jest tylko country_id (walidator GetDatesValidator używa wyłącznie CountryRules) — w odróżnieniu od pozostałych akcji tego kontrolera nie podawaj domain ani fetch_mode. country_id musi być liczbą całkowitą większą od zera i istnieć w bazie krajów; nieznana wartość zwraca 418 z komunikatem "Unknown country_id". Uwaga na granulację listy: historia jest miesięczna (pierwszy dzień miesiąca), a tylko ostatni tydzień ma punkty dzienne.

Odpowiedź

W przypadku powodzenia data jest obiektem (nie tablicą) zawierającym listę dostępnych dat (data.data), sugerowane zakresy (data.config) oraz pola default_min_date / default_max_date. Lista data.data miała 78 pozycji: zaczyna się od punktów miesięcznych (od "2020-01-01" / „Styczeń 2020”), a kończy punktami dziennymi z ostatniego tygodnia (np. "2026-07-01" / „Wczoraj”). Etykiety label i label_short są po polsku.

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`{ data: DateEntry[]; config: { default: { date_min: DateEntry; date_max: DateEntry; }; recent: { date_min: DateEntry; date_max: DateEntry; }; }; default_min_date: string \| null; default_max_date: string \| null; }`

Błędy

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

418 zwracany jest również dla błędów walidacji — nie tylko przy ograniczeniu liczby żądań (rate limiting). Brak wymaganego pola → {"success":false,"data":{"error":{"type":"invalid_data","params":{"country_id":{"_required":"This field is required"}}}}}. Nieznany country_id → 418 z komunikatem "Unknown country_id".

Powiązane akcje

getData — frazy w zakresie dat
getWins / getLosses — frazy, które zyskały / straciły pozycje w danym zakresie
getAcquired / getLost — frazy nowo pozyskane / całkowicie utracone w zakresie
getDates — dostępne daty dla zakresu (ta strona)

Historia fraz: dostępne daty (getDates)