Historia fraz: spadki (`getLosses`)

POST/api/visibility_analysis/reports/history/keywords/getLosses

Zwraca frazy, których pozycja pogorszyła się między date_min a date_max (tryb MODE_DECREASE tego samego komponentu danych co getData). W danych spadek oznacza dodatni statistics.position.diff — np. przejście z pozycji 2 na 5 daje diff: 3. Struktura żądania i odpowiedzi jest identyczna jak w getData; zmienia się wyłącznie zestaw zwracanych wierszy.

Ta akcja nie zawiera fraz utraconych — i nie jest symetryczna wobec getWins.

Frazy, które wypadły poza TOP50 na date_max, nie pojawią się tutaj, mimo że formalnie „spadły”. Znajdziesz je wyłącznie w getLost. Ta akcja pokazuje więc wyłącznie ruch wewnątrz TOP50: fraza musi rankować zarówno na date_min, jak i na date_max.

Siostrzana getWins działa odwrotnie — zawiera też frazy nowo pozyskane. Konsekwencje przy liczeniu:

Pełny obraz strat = getLosses + getLost. Zbiory są rozłączne, więc możesz je bezpiecznie skleić.
Pełny obraz zysków = samo getWins. Doklejenie getAcquired zdubluje wiersze.
Zestawianie count z getWins i getLosses poró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.

Podgląd · 6 z 24 kolumn

Fraza	ID frazy	KID	Domena	Liczba słów	Pozycja
ochnik	14897112	c9dba6c1c694aa2bd10bceab8716e8d7	zalando.pl	1	5
pinko torebka	11672176	9e41576fb002d977104a4c8f9fac9015	zalando.pl	2	3

zalando.pl, sort: widoczność malejąco — frazy, których pozycja się pogorszyła (dodatni „diff”, ujemna Δ widoczności). 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/getLosses

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/getLosses' \
  --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) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL Wartość `domain` nie istnieje.
`date_min`	`string` Wymagane. Początek zakresu dat, `YYYY-MM-DD`. Musi być nie późniejszy niż `date_max`. Dostępne daty pobierzesz akcją `getDates`.
`date_max`	`string` Wymagane. Koniec zakresu dat, `YYYY-MM-DD`. Musi być nie wcześniejszy niż `date_min`.
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` “Unknown country_id”.
`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. 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ę pogorszyła) oraz pagination. Pozycja 51 to wartość specjalna oznaczająca frazę poza TOP50.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "keyword_id": 14897112, "keyword": "ochnik", "statistics": { "position": { "current": 5, "previous": 2, "diff": 3 }, "visibility": { "current": 22635 } /* … */ } }
  ],
  "pagination": { "page_count": 3004, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 6007, "limit": 2 }
}

Pełna

przykładowa-odpowiedź (200)


{
  "success": true,
  "data": [
    {
      "keyword_id": 14897112,
      "kid": "c9dba6c1c694aa2bd10bceab8716e8d7",
      "domain": "zalando.pl",
      "keyword": "ochnik",
      "words_count": 1,
      "statistics": {
        "position": { "current": 5, "previous": 2, "diff": 3, "changes": { "wins": 0, "losses": 1, "no_changes": 0 }, "history": { "2026-05-17": { "position": 2, "has_serp": true }, "2026-06-21": { "position": 5, "has_serp": true } } },
        "visibility": { "current": 22635, "previous": 78840, "diff": -56205, "percent": -0.7129, "history": null },
        "url": { "current": "zalando.pl/ochnik/", "previous": "zalando.pl/ochnik/", "is_change": 0 },
        "cpc": { "current": 0.42 },
        "searches": { "current": 450000 },
        "trends": { "history": [368000, 301000, 301000, 368000, 450000, 673000, 823000, 823000, 673000, 550000, 450000, 368000], "peak": null },
        "difficulty": { "current": 60 },
        "snippets": { "current": ["map", "people_also_ask", "wiki_right"] }
      }
    },
    {
      "keyword_id": 11672176,
      "kid": "9e41576fb002d977104a4c8f9fac9015",
      "domain": "zalando.pl",
      "keyword": "pinko torebka",
      "words_count": 2,
      "statistics": {
        "position": { "current": 3, "previous": 2, "diff": 1, "changes": { "wins": 0, "losses": 1, "no_changes": 0 }, "history": { "2026-05-25": { "position": 2, "has_serp": true }, "2026-06-26": { "position": 3, "has_serp": true } } },
        "visibility": { "current": 5321.25, "previous": 8672.4, "diff": -3351.15, "percent": -0.3864, "history": null },
        "url": { "current": "zalando.pl/akcesoria-torby-kobiety/pinko/", "previous": "zalando.pl/akcesoria-torby-kobiety/pinko/", "is_change": 0 },
        "cpc": { "current": 0.14 },
        "searches": { "current": 49500 },
        "trends": { "history": [60500, 49500, 49500, 40500, 49500, 40500, 49500, 60500, 40500, 40500, 74000, 74000], "peak": null },
        "difficulty": { "current": 34 },
        "snippets": { "current": ["image_thumbs", "people_also_ask"] }
      }
    }
  ],
  "pagination": { "page_count": 3004, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 6007, "limit": 2 }
}

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, których pozycja się pogorszył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 (taka sama struktura żądania)
getLosses — frazy, które straciły pozycje (ta strona)
getAcquired / getLost — frazy nowo pozyskane / całkowicie utracone w zakresie (taka sama struktura żądania)
getDates — dostępne daty (POST, wymaga tylko country_id)

Historia fraz: spadki (getLosses)