--- title: "Historia URL-i: wzrosty (`getWins`)" source: https://docs.senuto.com/modules/visibility_analysis/va-history-urls-getWins api: POST /api/visibility_analysis/reports/history/urls/getWins --- # Historia URL-i: wzrosty (`getWins`) **`POST /api/visibility_analysis/reports/history/urls/getWins`** Zwraca adresy URL domeny, których widoczność **wzrosła** między `date_min` a `date_max`. To wariant `MODE_INCREASE` tego samego komponentu co [pełny raport historii URL-i (`getData`)](/modules/visibility_analysis/va-history-urls-getData) — struktura żądania i wierszy odpowiedzi jest identyczna, różni się jedynie zbiór zwracanych URL-i (tylko te z rosnącą widocznością). Dla każdego adresu otrzymujesz liczbę fraz (`keywords_count`) oraz statystyki `{current, previous, diff, percent}`: liczbę fraz w TOP3/TOP10/TOP50, szacowany ruch (`visibility`), średnią pozycję (`position`), sumę pozycji (`summary_position`) oraz liczbę fraz, które zyskały (`wins`) i straciły (`losses`). | URL | Frazy | TOP3 | TOP3 poprz. | TOP3 Δ | TOP3 % | TOP10 | TOP10 poprz. | TOP10 Δ | TOP10 % | TOP50 | TOP50 poprz. | TOP50 Δ | TOP50 % | Widoczność | Widoczność poprz. | Widoczność Δ | Widoczność % | Śr. pozycja | Śr. pozycja poprz. | Śr. pozycja Δ | Suma pozycji | Suma pozycji poprz. | Suma pozycji Δ | Suma pozycji % | Wzrosty (fraz) | Spadki (fraz) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | zalando.pl/bershka/ | 150 | 28 | 28 | 0 | 0 | 41 | 42 | -1 | -0.0238 | 81 | 80 | 1 | 0.0125 | 311733.14 | 311732.88 | 0.27 | 0 | 15 | 15 | 0 | 2345 | 2380 | -35 | -0.0147 | 6 | 5 | | zalando.pl/obuwie/ugg/ | 198 | 56 | 56 | 0 | 0 | 43 | 43 | 0 | 0 | 99 | 99 | 0 | 0 | 103112.67 | 77149.7 | 25962.97 | 0.3365 | 15 | 15 | 0 | 3120 | 3110 | 10 | 0.0032 | 5 | 1 | _zalando.pl (2026-06-20 → 2026-06-29) — URL-e ze wzrostem widoczności. Wszystkie pola wiersza (poza mapami o kluczach-datach — są w JSON). Uwaga: keywords_count, wins i losses przychodzą jako stringi._ --- ## Żądanie `POST` `/api/visibility_analysis/reports/history/urls/getWins` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "date_min": "2026-06-20", "date_max": "2026-06-29", "order": { "prop": "statistics.visibility.current", "dir": "desc" } } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "date_min": "2026-06-20", "date_max": "2026-06-29", "order": { "prop": "statistics.visibility.current", "dir": "desc" }, "limit": 2, "page": 1 } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/history/urls/getWins' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "date_min": "2026-06-20", "date_max": "2026-06-29", "order": { "prop": "statistics.visibility.current", "dir": "desc" } }' ``` ### Parametry ```ts type HistoryUrlsGetWinsRequest = { /** * **Wymagane**. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`. */ domain: string; /** * **Wymagane**. Sposób interpretacji `domain`. * - `topLevelDomain` — cała domena (najczęstszy przypadek; wartość "domain" nie istnieje) * - `subdomain` — pojedyncza subdomena * - `catalog` — ścieżka/katalog * - `url` — dokładny URL */ fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url'; /** * **Wymagane**. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem `Unknown country_id`. */ country_id: number; /** * **Wymagane**. Początek zakresu dat, `YYYY-MM-DD`. Nie może być późniejszy niż `date_max`. */ date_min: string; /** * **Wymagane**. Koniec zakresu dat, `YYYY-MM-DD`. Nie może być wcześniejszy niż `date_min`. */ date_max: string; /** * **Wymagane**. **Pojedyncza** dyrektywa sortowania (jeden obiekt — nie tablica). * * Dozwolone wartości `prop` (tylko 4 — inaczej niż w raporcie historii fraz): * - `statistics.visibility.current` * - `statistics.visibility.previous` * - `statistics.visibility.diff` * - `statistics.visibility.percent` * * Błędny `prop` → `418` `invalid_data` z komunikatem "This value is not allow. Please use correct colum name". */ order: { prop: | 'statistics.visibility.current' | 'statistics.visibility.previous' | 'statistics.visibility.diff' | 'statistics.visibility.percent'; dir: 'asc' | 'desc'; }; /** * Liczba wierszy na stronę. * @default 10 */ limit?: number; /** * Numer strony. * @default 1 */ page?: number; } export default HistoryUrlsGetWinsRequest ``` > **Ostrzeżenie:** > **`order` to pojedynczy obiekt** (`{ prop, dir }`) — nie tablica — i akceptuje wyłącznie 4 właściwości z gałęzi `statistics.visibility.*` wymienione powyżej. Kontroler przyjmuje też opcjonalny parametr `filtering`, jednak zestaw dozwolonych kluczy filtrów dla tego raportu **nie został jeszcze zweryfikowany na żywo** — nie należy zakładać, że filtry znane z innych raportów zadziałają tutaj tak samo. > **Ostrzeżenie:** > Pięć parametrów jest **wymaganych**: **`domain`**, **`fetch_mode`**, **`country_id`**, **`date_min`**, **`date_max`**, a także pojedynczy obiekt **`order`** (`{ prop, dir }` — nie tablica). Wartość `fetch_mode: "domain"` **nie istnieje** — użyj `topLevelDomain`. Dozwolone są **tylko 4** wartości `order.prop` (wszystkie z gałęzi `statistics.visibility.*`). Uwaga na typy: część pól liczbowych przychodzi jako **stringi** (`keywords_count`, `statistics.wins.current`, `statistics.losses.current`). ## Odpowiedź W przypadku powodzenia otrzymujesz `data` (tablicę wierszy z adresami URL, których widoczność wzrosła) oraz `pagination`. Dla przykładowego zapytania (`zalando.pl`, 2026-06-20 → 2026-06-29) raport zwrócił `count` = 1333 URL-i ze wzrostem — wobec 73 353 wszystkich URL-i w akcji `getData`. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "url": "zalando.pl/obuwie/ugg/", "keywords_count": "198", "statistics": { "visibility": { "current": 103112.67, "diff": 25962.97 } /* … */ } } ], "pagination": { "page_count": 667, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 1333, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "url": "zalando.pl/bershka/", "keywords_count": "150", "statistics": { "top3": { "current": 28, "previous": 28, "diff": 0, "percent": 0 }, "top10": { "current": 41, "previous": 42, "diff": -1, "percent": -0.0238 }, "top50": { "current": 81, "previous": 80, "diff": 1, "percent": 0.0125 }, "visibility": { "current": 311733.14, "previous": 311732.88, "diff": 0.27, "percent": 0 }, "position": { "current": 15, "previous": 15, "diff": 0 }, "summary_position": { "current": 2345, "previous": 2380, "diff": -35, "percent": -0.0147 }, "wins": { "current": "6" }, "losses": { "current": "5" } } }, { "url": "zalando.pl/obuwie/ugg/", "keywords_count": "198", "statistics": { "top3": { "current": 56, "previous": 56, "diff": 0, "percent": 0 }, "top10": { "current": 43, "previous": 43, "diff": 0, "percent": 0 }, "top50": { "current": 99, "previous": 99, "diff": 0, "percent": 0 }, "visibility": { "current": 103112.67, "previous": 77149.7, "diff": 25962.97, "percent": 0.3365 }, "position": { "current": 15, "previous": 15, "diff": 0 }, "summary_position": { "current": 3120, "previous": 3110, "diff": 10, "percent": 0.0032 }, "wins": { "current": "5" }, "losses": { "current": "1" } } } ], "pagination": { "page_count": 667, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 1333, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type HistoryUrlsWinsResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze z adresami URL, których widoczność wzrosła */ data: UrlRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type UrlRow = { /** Adres URL (bez protokołu) */ url: string; /** Liczba fraz przypisanych do URL-a — UWAGA: zwracana jako string, np. "150" */ keywords_count: string; statistics: { /** Liczba fraz URL-a na pozycjach 1–3 */ top3: { current: number; previous: number; diff: number; percent: number }; /** Liczba fraz URL-a na pozycjach 4–10 */ top10: { current: number; previous: number; diff: number; percent: number }; /** Liczba fraz URL-a na pozycjach 11–50 */ top50: { current: number; previous: number; diff: number; percent: number }; /** Szacowany ruch (widoczność) URL-a */ visibility: { current: number; previous: number; diff: number; percent: number }; /** Średnia pozycja fraz URL-a (bez pola percent) */ position: { current: number; previous: number; diff: number }; /** Suma pozycji fraz URL-a */ summary_position: { current: number; previous: number; diff: number; percent: number }; /** Liczba fraz, które zyskały pozycje — UWAGA: string, np. "6" */ wins: { current: string }; /** Liczba fraz, które straciły pozycje — UWAGA: string, np. "5" */ losses: { current: string }; }; } export default HistoryUrlsWinsResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, database, timeout, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > **`418`** zwracany jest również dla błędów walidacji — nie tylko przy ograniczeniu liczby żądań (rate limiting). Nieznane `country_id` → `418` z komunikatem `Unknown country_id`. Niedozwolony `order.prop` → `418` `invalid_data` z komunikatem `"This value is not allow. Please use correct colum name"` (pisownia oryginalna). > > **Znany błąd — odwrócony komunikat.** Przy `date_min > date_max` walidator `DateRangeRules` zwraca komunikat `"date_max must be less or equal than date_min"` — treść jest odwrócona (to `date_min` musi być nie późniejszy niż `date_max`). Należy go odczytywać jako niepowodzenie reguły zakresu dat, a nie jako dosłowną instrukcję. ## Powiązane akcje - [`getData`](/modules/visibility_analysis/va-history-urls-getData) — pełna lista URL-i w zakresie dat (strona siostrzana) - `getWins` — URL-e, których widoczność wzrosła w danym zakresie (`MODE_INCREASE`, ta strona) - `getLosses` — URL-e, których widoczność spadła w danym zakresie - `getAcquired` — URL-e nowo pozyskane w zakresie - `getLost` — URL-e całkowicie utracone w zakresie