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) — 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).

Podgląd · 6 z 27 kolumn

URL	Frazy	TOP3	TOP3 poprz.	TOP3 Δ	TOP3 %
zalando.pl/bershka/	150	28	28	0	0
zalando.pl/obuwie/ugg/	198	56	56	0	0

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 <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żą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

żą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


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

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; wartość “domain” nie istnieje) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem `Unknown country_id`.
`date_min`	`string` Wymagane. Początek zakresu dat, `YYYY-MM-DD`. Nie może być późniejszy niż `date_max`.
`date_max`	`string` Wymagane. Koniec zakresu dat, `YYYY-MM-DD`. Nie może być wcześniejszy niż `date_min`.
`order`	`{ prop: "statistics.visibility.current" \| "statistics.visibility.previous" \| "statistics.visibility.diff" \| "statistics.visibility.percent"; dir: "asc" \| "desc"; }` 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”.
`limit`	`number` Liczba wierszy na stronę.	`10`
`page`	`number` Numer strony.	`1`

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.

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

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 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`UrlRow[]` Zwrócone wiersze z adresami URL, których widoczność wzrosł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 — 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 — 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

Historia URL-i: wzrosty (getWins)