Pozycje: wzrosty (`getWins`)

POST/api/visibility_analysis/reports/positions/getWins

Zwraca frazy kluczowe, na których pozycja domeny wzrosła w analizowanym okresie (tryb pracy = increase). Dla każdej frazy zwracany jest ten sam zestaw statystyk co w getData (pozycja, widoczność, URL, CPC, liczba wyszukiwań, trendy, trudność, snippety SERP), ograniczony do fraz z poprawą pozycji. Domyślnie posortowane według wielkości zmiany.

Okres jest zaszyty na sztywno — ok. tygodnia. Ta akcja nie przyjmuje żadnych parametrów dat. Porównywany jest najświeższy dostępny snapshot pozycji z najstarszym snapshotem z ostatniego tygodnia. Jeśli potrzebujesz własnego zakresu, użyj history/keywords/getWins z date_min/date_max.

Wyniki zawierają też frazy nowo pozyskane. Fraza, na którą domena wcześniej nie rankowała, trafia tutaj jako skok z pozycji 51 (sentinel „poza TOP50”) — patrz przykładowa odpowiedź powyżej: {"current": 26, "previous": 51, "diff": -25}. Aby zawęzić wynik do ruchu wewnątrz TOP50, odrzuć wiersze z statistics.position.previous === 51.

Siostrzana getLosses zachowuje się odwrotnie — frazy utracone są z niej wykluczone, a rodzina positions/* nie ma odpowiednika getLost, więc w ogóle ich stąd nie pobierzesz. Porównywanie count obu akcji zestawia dwie różnie zdefiniowane wielkości. Zachowanie może się w przyszłości ujednolicić — na dziś traktuj powyższe jako obowiązujący kontrakt.

Podgląd · 6 z 24 kolumn

Fraza	ID frazy	KID	Domena	Liczba słów	Pozycja
vans zamszowe	225329	030d9b596c2058c07801e2ec87e85a37	zalando.pl	2	1
lakierowane balerinki	7856664	6a890673b2ee1ab050e233749ab4d170	zalando.pl	2	1
śniegowce sorel	6508374	583abba99a976ff8f6276ef42ebab4c7	zalando.pl	2	1
żółty sweterek rozpinany	7993203	6c5f97d43b98e882ad45d9108af77e43	zalando.pl	3	1
quiksilver t-shirt	8270210	702193e9391832d6a07401b1c1fdff47	zalando.pl	2	1

zalando.pl · 2026-07-04, limit: 5, sort: pozycja rosnąco — frazy, które zyskały pozycje. Wszystkie pola wiersza (poza mapą historii pozycji statistics.position.history, która ma zmienne klucze-daty — jest w JSON i sekcji „Struktura odpowiedzi”).

Żądanie

POST /api/visibility_analysis/reports/positions/getWins

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain"
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "limit": 10,
  "page": 1,
  "order": { "prop": "statistics.position.current", "dir": "asc" },
  "filtering": []
}

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/positions/getWins' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain" }'

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; “domena”) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL
`limit`	`number` Liczba wierszy na stronę. Nieujemna liczba całkowita.	`10`
`page`	`number` Numer strony. Nieujemna liczba całkowita.	`1`
`order`	`{ prop: string; dir: "asc" \| "desc"; }` Sortowanie wyników — pojedynczy obiekt, nie tablica. Dozwolone `prop`: `statistics.position.current\|previous\|diff`, `statistics.visibility.current\|previous\|diff`, `statistics.searches.current`, `statistics.cpc.current`, `statistics.difficulty.current`, `statistics.url.is_change`, `words_count`. Zły kształt lub nieznany klucz NIE zwraca błędu — API po cichu wraca do sortu domyślnego (`keyword_id` rosnąco).
`filtering`	`unknown[]` Dyrektywy filtrowania. Pusta tablica = brak filtrowania.

Nazwy parametrów różnią się od starej dokumentacji: jest to filtering (nie filters) oraz order (nie sort_by / sort_order). Uwaga na kształt order: to obiekt { "prop": …, "dir": … } — forma tablicowa [{ field, direction }] jest przez API ignorowana po cichu (zwraca 200 z sortem domyślnym po keyword_id).

Zarówno domain, jak i fetch_mode są wymagane; pominięcie fetch_mode zwraca 418 z invalid_data.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data (tablicę fraz, które zyskały na pozycji) oraz pagination. Ujemna wartość position.diff oznacza poprawę — fraza przesunęła się w górę SERP (mniejszy numer pozycji).

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "keyword_id": 1097, "keyword": "my secret", "statistics": { "position": { "current": 26, "previous": 51, "diff": -25 } /* … */ } }
  ],
  "pagination": { "page_count": 3182, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 6363, "limit": 2 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`PositionRow[]` Zwrócone wiersze fraz (z poprawą pozycji)
`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 jest zwracane również w przypadku błędów walidacji — nie tylko przy ograniczaniu liczby żądań. Brak fetch_mode → {"success":false,"data":{"error":{"type":"invalid_data","params":{"fetch_mode":{"_required":"This field is required"}}}}}.

Powiązane akcje

getData — bieżące pozycje fraz (taki sam kształt żądania)
getWins — frazy, które zyskały pozycje (ta strona)
getLosses — frazy, które straciły pozycje (taki sam kształt żądania)
getKeywordHistory — pełna historia pozycji dla pojedynczej frazy (keyword_id + kid + domain + fetch_mode)

Pozycje: wzrosty (getWins)