Historia fraz: przegląd (`getData`)

POST/api/visibility_analysis/reports/history/keywords/getData

Zwraca frazy, na które domena rankowała w wybranym zakresie dat, wraz ze statystykami dla każdej frazy (pozycja, widoczność, URL, CPC, liczba wyszukiwań, trendy, trudność, snippety SERP) oraz osadzoną mapą history z historią pozycji. Użyj jej, aby sprawdzić, jak wyglądał zestaw fraz domeny i jej rankingi w wybranym oknie historycznym. Wyniki są sortowane według pojedynczej dyrektywy sortowania.

Podgląd · 6 z 24 kolumn

Fraza	ID frazy	KID	Domena	Liczba słów	Pozycja
zalando	13624651	b8ac304f24a9864f46f86cbebc0820f1	zalando.pl	1	1

zalando.pl, sort: widoczność malejąco. Wszystkie pola wiersza (poza mapą historii statistics.position.history, która ma zmienne klucze-daty — jest w JSON i sekcji „Struktura odpowiedzi”).

Żądanie

POST /api/visibility_analysis/reports/history/keywords/getData

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "date_min": "2026-06-20",
  "date_max": "2026-06-29",
  "country_id": 1,
  "order": { "prop": "statistics.visibility.current", "dir": "desc" }
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "date_min": "2026-06-20",
  "date_max": "2026-06-29",
  "country_id": 1,
  "order": { "prop": "statistics.visibility.current", "dir": "desc" },
  "limit": 10,
  "page": 1
}

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/history/keywords/getData' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{
    "domain": "zalando.pl",
    "fetch_mode": "topLevelDomain",
    "date_min": "2026-06-20",
    "date_max": "2026-06-29",
    "country_id": 1,
    "order": { "prop": "statistics.visibility.current", "dir": "desc" }
  }'

Parametry

Name	Type	Default
`domain`	`string` Wymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`.
`fetch_mode`	`"topLevelDomain" \| "subdomain" \| "catalog" \| "url"` Wymagane. Sposób interpretacji `domain`. `topLevelDomain` — cała domena (najczęstszy przypadek; stara wartość “domain” mapuje się tutaj) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL
`date_min`	`string` Wymagane. Początek zakresu dat, `YYYY-MM-DD`. Musi być nie późniejszy niż dzisiaj i nie późniejszy niż `date_max`.
`date_max`	`string` Wymagane. Koniec zakresu dat, `YYYY-MM-DD`. Musi być nie późniejszy niż dzisiaj i nie wcześniejszy niż `date_min`.
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`.
`order`	`{ prop: "keyword" \| "statistics.position.current" \| "statistics.position.previous" \| "statistics.position.diff" \| "statistics.visibility.current" \| "statistics.visibility.previous" \| ... 4 more ... \| "statistics.url.is_change"; dir: "asc" \| "desc"; }` Wymagane. Pojedyncza dyrektywa sortowania (jeden obiekt — nie tablica). `prop` to jedna z dozwolonych właściwości sortowalnych; `dir` to kierunek. Dozwolone wartości `prop`: `keyword` `statistics.position.current` `statistics.position.previous` `statistics.position.diff` `statistics.visibility.current` `statistics.visibility.previous` `statistics.visibility.diff` `statistics.difficulty.current` `statistics.searches.current` `statistics.cpc.current` `statistics.url.is_change`
`limit`	`number` Liczba wierszy na stronę.	`10`
`page`	`number` Numer strony.	`1`

order to pojedynczy obiekt ({ prop, dir }) — nie tablica. Używaj ścieżek prop z kropkami wymienionych powyżej; dowolne inne pola są odrzucane.

Pięć parametrów jest wymaganych: domain, fetch_mode, date_min, date_max oraz country_id, a także pojedynczy obiekt order. Pominięcie któregokolwiek wymaganego pola zwraca 418 z invalid_data.

Filtrowanie

Opcjonalny parametr filtering (tablica grup, filtry w grupie łączone operatorem AND) zawęża wyniki. Ten endpoint korzysta z tego samego mechanizmu i tych samych kluczy filtrów co Pozycje → Filtrowanie (dzielą komponent danych) — m.in. keywords (przez items: contain/startsWith/endsWith/notContain) oraz liczbowe statistics.position.current, statistics.visibility.current, statistics.cpc.current, statistics.difficulty.current, statistics.searches.current, words_count (eq/gt/gte/lt/lte).

żądanie-z-filtrowaniem.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "date_min": "2026-05-01",
  "date_max": "2026-06-29",
  "country_id": 1,
  "order": { "prop": "statistics.visibility.current", "dir": "desc" },
  "filtering": [
    {
      "filters": [
        { "key": "statistics.position.current", "match": "lte", "value": 3 },
        { "key": "keywords", "items": [{ "match": "contain", "value": "buty" }] }
      ]
    }
  ]
}

Zwalidowane na żywo (zalando.pl): bez filtra count = 300 894; z powyższym filtrem (TOP3 + fraza zawiera „buty”) → count = 2 832.

Odpowiedź

W przypadku powodzenia otrzymujesz data (tablicę wierszy z frazami) oraz pagination.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "keyword_id": 13624651, "keyword": "zalando", "statistics": { "position": { "current": 1 }, "visibility": { "current": 651480 } /* … */ } }
  ],
  "pagination": { "page_count": 145940, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 291879, "limit": 10 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`KeywordRow[]` Zwrócone wiersze z frazami
`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 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"}}}}}.

Znany błąd — mylący komunikat. Gdy zakres dat jest poprawny (date_min <= date_max), ale wystąpi naruszenie DateRangeRules, zwrócony komunikat brzmi "date_max must be less or equal than date_min". Treść jest błędna (sama logika działa poprawnie) — należy go odczytywać jako niepowodzenie reguły zakresu dat, a nie jako dosłowną instrukcję.

Powiązane akcje

getData — frazy w zakresie dat (MODE_DATA, ta strona)
getWins / getLosses — frazy, które zyskały / straciły pozycje w danym zakresie (taka sama struktura żądania)
getAcquired / getLost — frazy nowo pozyskane / całkowicie utracone w zakresie (taka sama struktura żądania)
getDates — dostępne daty dla zakresu (lżejsze wywołanie, używa osobnego walidatora)

Historia fraz: przegląd (getData)