Pozycje: spadki (`getLosses`)

POST/api/visibility_analysis/reports/positions/getLosses

Zwraca frazy kluczowe, dla których domena straciła pozycje w wybranym okresie (working mode = decrease). Każdy wiersz zawiera te same statystyki co getData (pozycja, widoczność, URL, CPC, liczba wyszukiwań, trendy, trudność, snippety SERP), ale zbiór jest ograniczony do fraz, których pozycja się pogorszyła — wartość diff w position odzwierciedla zmianę na gorsze.

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/getLosses z date_min/date_max.

Frazy utracone nie są tutaj widoczne. Fraza, która wypadła poza TOP50, nie pojawi się w tej akcji, mimo że formalnie „spadła” — zwracany jest wyłącznie ruch wewnątrz TOP50. W rodzinie positions/* nie ma odpowiednika getLost, więc utraconych fraz nie da się stąd pobrać w ogóle; sięgnij po history/keywords/getLost i podaj daty ręcznie.

Siostrzana getWins zachowuje się odwrotnie — zawiera frazy nowo pozyskane (jako skok z pozycji 51). Porównywanie count obu akcji zestawia więc 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
dresy damskie 4f	2864	0009edce5b257ad4363766e56bef5c74	zalando.pl	3	17

zalando.pl — fraza, która straciła pozycję. Dodatni „diff” oznacza spadek. 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/positions/getLosses

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


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

Rozszerzony

żądanie-rozszerzone.jsonc


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

cURL


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

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 straciły pozycje) oraz pagination. W polu position: previous to pozycja wcześniejsza, current — bieżąca, a dodatni diff oznacza spadek (wyższa liczba = gorsza pozycja).

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "keyword_id": 2864, "keyword": "dresy damskie 4f", "statistics": { "position": { "current": 17, "previous": 15, "diff": 2 } /* … */ } }
  ],
  "pagination": { "page_count": 2057, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 4114, "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 (spadki)
`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 (taki sam kształt żądania)
getWins — frazy, które zyskały pozycje (working mode = increase)
getLosses — frazy, które straciły pozycje (ta strona)
getKeywordHistory — pełna historia pozycji dla pojedynczej frazy (keyword_id + kid + domain + fetch_mode)

Pozycje: spadki (getLosses)