Historia fraz: wzrosty (getWins)
/api/visibility_analysis/reports/history/keywords/getWinsZwraca frazy, których pozycja poprawiła się między date_min a date_max (tryb MODE_INCREASE tego samego komponentu danych co getData). W danych poprawa oznacza ujemny statistics.position.diff — np. przejście z pozycji 3 na 1 daje diff: -2. Struktura żądania i odpowiedzi jest identyczna jak w getData; zmienia się wyłącznie zestaw zwracanych wierszy.
Ta akcja zawiera też frazy nowo pozyskane — i nie jest symetryczna wobec getLosses.
Frazy, na które domena nie rankowała na date_min, a rankuje na date_max, trafiają również tutaj — jako skok z pozycji 51 (sentinel „poza TOP50”), np. {"current": 26, "previous": 51, "diff": -25}. Nie są odfiltrowane. Jeśli potrzebujesz wyłącznie ruchu wewnątrz TOP50, odrzuć wiersze z statistics.position.previous === 51.
Siostrzana getLosses działa odwrotnie — frazy utracone są z niej wykluczone i występują tylko w getLost. Konsekwencje przy liczeniu:
- Pełny obraz zysków = samo
getWins. DoklejeniegetAcquiredzdubluje wiersze — to podzbiór tej akcji. - Pełny obraz strat wymaga sklejenia
getLosses+getLost(te zbiory są rozłączne). - Zestawianie
countzgetWinsigetLossesporównuje dwie różnie zdefiniowane wielkości — zyski są zawyżone o pozyskane, straty zaniżone o utracone.
Zachowanie może się w przyszłości ujednolicić — na dziś traktuj powyższe jako obowiązujący kontrakt.
| Fraza | ID frazy | KID | Domena | Liczba słów | Pozycja |
|---|---|---|---|---|---|
| nie air max | 1421737 | 1344167bcc1aac3b96cfe7420ae6244e | zalando.pl | 3 | 1 |
| uggs buty | 5591577 | 4bb5c4ba39dc62e9d6d6e1a03dcb344a | zalando.pl | 2 | 1 |
zalando.pl, sort: widoczność malejąco — frazy, których pozycja się poprawiła (ujemny „diff”). 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/getWins
Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.
Struktura żądania
Podstawowy
{
"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 | stringWymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z | |
fetch_mode | "topLevelDomain" | "subdomain" | "catalog" | "url"Wymagane. Sposób interpretacji
Wartość | |
date_min | stringWymagane. Początek zakresu dat, | |
date_max | stringWymagane. Koniec zakresu dat, | |
country_id | numberWymagane. Id kraju (bazy danych). Polska = | |
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).
Dozwolone wartości
| |
limit | numberLiczba wierszy na stronę. | 10 |
page | numberNumer strony. | 1 |
order to pojedynczy obiekt ({ prop, dir }) — nie tablica. Błędna wartość prop zwraca 418 invalid_data z komunikatem (dosłownym): This value is not allow. Please use correct colum name.
Pięć parametrów jest wymaganych: domain, fetch_mode, date_min, date_max oraz country_id, a także pojedynczy obiekt order. Wartość fetch_mode musi być jedną z topLevelDomain / subdomain / catalog / url — wartość domain nie istnieje. order to pojedynczy obiekt { prop, dir }, nie tablica. Pominięcie któregokolwiek wymaganego pola zwraca 418 z invalid_data; nieznane country_id → 418 z komunikatem Unknown country_id.
Filtrowanie
Opcjonalny parametr filtering (tablica grup filtrów) zawęża wyniki. Endpoint korzysta z tego samego mechanizmu i tych samych kluczy filtrów co positions/getData oraz history/keywords/getData — szczegóły i pełną listę kluczy znajdziesz na stronie typów filtrów.
Odpowiedź
W przypadku powodzenia otrzymujesz data (tablicę wierszy z frazami, których pozycja się poprawiła) oraz pagination. Pozycja 51 to wartość specjalna oznaczająca frazę poza TOP50.
Skrócona
{
"success": true,
"data": [
{ "keyword_id": 1421737, "keyword": "nie air max", "statistics": { "position": { "current": 1, "previous": 3, "diff": -2 }, "visibility": { "current": 21538 } /* … */ } }
],
"pagination": { "page_count": 4115, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 8229, "limit": 2 }
}Struktura odpowiedzi
| Name | Type | Default |
|---|---|---|
success | boolean
| |
data | KeywordRow[]Zwrócone wiersze z frazami, których pozycja się poprawiła | |
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. Brak wymaganego pola → invalid_data; nieznane country_id → Unknown country_id; błędny order.prop → This value is not allow. Please use correct colum name.
Znany błąd — odwrócony komunikat. Przy date_min > date_max komunikat reguły DateRangeRules jest odwrócony i brzmi "date_max must be less or equal than date_min". 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)getWins— frazy, które poprawiły pozycje (ta strona)getLosses— frazy, które straciły pozycje (taka sama struktura żądania)getAcquired/getLost— frazy nowo pozyskane / całkowicie utracone w zakresie (taka sama struktura żądania)getDates— dostępne daty (POST, wymaga tylkocountry_id)