--- title: "Bieżące pozycje (`getData`)" source: https://docs.senuto.com/modules/visibility_analysis/positions api: POST /api/visibility_analysis/reports/positions/getData --- # Bieżące pozycje (`getData`) **`POST /api/visibility_analysis/reports/positions/getData`** Zwraca frazy kluczowe, na które rankuje domena, wraz ze statystykami dla każdej frazy (pozycja, widoczność, URL, CPC, liczba wyszukiwań, trendy, trudność, snippety SERP). Bez parametru `order` wyniki są posortowane po `keyword_id` rosnąco — o kolejności decyduje wyłącznie poprawnie podany `order` (patrz [Parametry](#parametry)). ## Żądanie `POST` `/api/visibility_analysis/reports/positions/getData` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. Wymagane pola: **`domain`** (domena) i **`fetch_mode`** (zakres analizy, np. `topLevelDomain`). ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain" } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "limit": 10, "page": 1, "with_history": true, "order": { "prop": "statistics.visibility.current", "dir": "desc" }, "filtering": [ { "filters": [ { "key": "statistics.position.current", "match": "lte", "value": 10 }, { "key": "keywords", "items": [{ "match": "contain", "value": "buty" }] } ] } ] } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/positions/getData' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain" }' ``` ### Parametry ```ts type PositionsGetDataRequest = { /** * **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; "domena") * - `subdomain` — pojedyncza subdomena * - `catalog` — ścieżka/katalog * - `url` — dokładny URL */ fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url'; /** * Liczba wierszy na stronę. Nieujemna liczba całkowita. * @default 10 */ limit?: number; /** * Numer strony. Nieujemna liczba całkowita. * @default 1 */ page?: number; /** * Dołącz do odpowiedzi mapę historii pozycji (`history`) dla każdej frazy. * @default true */ with_history?: boolean; /** * 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). */ order?: { prop: string; dir: 'asc' | 'desc' }; /** * Filtrowanie — tablica **grup**. Pusta tablica = brak filtrowania. * Filtry w obrębie jednej grupy łączone są operatorem AND. * Pełna lista dostępnych kluczy i przykłady: sekcja "Filtrowanie" poniżej. */ filtering?: { filters: ( | { key: string; match: 'eq' | 'gt' | 'gte' | 'lt' | 'lte'; value: number | string } | { key: 'keywords'; items: { match: 'contain' | 'containsWord' | 'startsWith' | 'endsWith' | 'notContain'; value: string }[] } )[]; }[]; } export default PositionsGetDataRequest ``` > **Ostrzeżenie:** > 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`). > **Ostrzeżenie:** > Zarówno **`domain`**, jak i **`fetch_mode`** są **wymagane**; pominięcie `fetch_mode` zwraca `418` z `invalid_data`. ## Filtrowanie Parametr `filtering` odpowiada polu **Filtry** nad tabelą w raporcie pozycji. To **tablica grup**; każda grupa ma klucz `filters` z listą warunków. Warunki w obrębie jednej grupy łączone są operatorem **AND**. ```jsonc filename="kształt-filtering.jsonc" "filtering": [ { "filters": [ // filtr liczbowy: { key, match, value } { "key": "statistics.position.current", "match": "lte", "value": 10 }, // filtr tekstowy fraz: { key: "keywords", items: [{ match, value }] } { "key": "keywords", "items": [{ "match": "contain", "value": "buty" }] } ] } ] ``` ### Dostępne klucze (`positions/getData`) | Klucz | Typ | Operatory (`match`) | | ------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------- | | `keywords` | tekstowy (przez `items`) | `contain`, `containsWord`, `startsWith`, `endsWith`, `notContain` | | `statistics.position.current` · `.previous` · `.diff` | liczbowy | `eq`, `gt`, `gte`, `lt`, `lte` | | `statistics.visibility.current` · `.previous` · `.diff` | liczbowy | `eq`, `gt`, `gte`, `lt`, `lte` | | `cpc` · `statistics.cpc.current` | liczbowy | `eq`, `gt`, `gte`, `lt`, `lte` | | `statistics.searches.current` | liczbowy | `eq`, `gt`, `gte`, `lt`, `lte` | | `statistics.difficulty.current` | liczbowy | `eq`, `gt`, `gte`, `lt`, `lte` | | `words_count` | liczbowy | `eq`, `gt`, `gte`, `lt`, `lte` | | `is_change` · `statistics.url.is_change` | logiczny | `eq` | | `statistics.url.current` · `.previous` | URL | dopasowanie po adresie URL | | `statistics.snippets.current` | snippety SERP | filtr po typach snippetów | | `statistics.intentions.primary_intent` · `.main_intent` · `.action_type` · `.journey_stage` · `.content_timeliness` | intencje | dostępne tylko dla krajów wspierających intencje | > **Informacja:** > Przykłady dla `zalando.pl` (2026-07-03; baseline bez filtra: `count` = 291 325 — indeks jest odświeżany, więc liczby dryfują z dnia na dzień): > > - `statistics.position.current` `lte` `3` → `count` = 46 360 (frazy w TOP3), > - `keywords` `contain` `"buty"` → `count` = 20 325, > - oba w jednej grupie (AND) → `count` = 2 832, > - `lte` `10` + `"buty"` (AND) → `count` = 7 936. Filtry liczbowe, tekstowe i logiczne opisuje też wspólna strona [`Filter`](/types/filter). ## Przykładowe dane i zastosowania Dane pochodzą z bazy słów kluczowych Senuto (indeksowane pozycje w organicznych wynikach Google) i aktualizowane są cyklicznie — im wyższa popularność frazy (liczba wyszukiwań/mies.), tym częstsza aktualizacja; to inny model niż w Monitoringu (Rank Tracker), gdzie dane liczone są codziennie od dnia założenia projektu ([źródło](https://wiki.senuto.com/pl/articles/71799-jak-czesto-aktualizowane-sa-dane-w-analizie-widocznosci-i-monitoringu)). Pole `statistics.visibility` to **nie** realny ruch z Google Analytics — to szacowany miesięczny ruch organiczny, liczony na bazie widoczności frazy w TOP10, średniej liczby wyszukiwań i CTR wg pozycji ([źródło](https://wiki.senuto.com/en/articles/19052-metrics-in-senuto)). Tak wyglądają **realne wiersze zwrócone przez API** (5 pierwszych wyników dla `zalando.pl`), rozpisane w tabeli. | Fraza | Pozycja | Zmiana pozycji | Wyszukiwania/mies. | Widoczność | URL bieżący | ID frazy | KID | Domena | Liczba słów | Pozycja poprz. | Wzrosty | Spadki | Bez zmian | Widoczność poprz. | Δ widoczności | Widoczność % | URL poprzedni | URL zmiana | CPC | Trend (12 mies.) | Szczyt trendu | Trudność | Snippety SERP | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | zalando | 1 | 0 | 1830000 | 651480 | zalando.pl/ | 13624651 | b8ac304f24a9864f46f86cbebc0820f1 | zalando.pl | 1 | 1 | 0 | 0 | 0 | 651480 | 0 | 0 | zalando.pl/ | 0 | 2.03 | [1830000,1830000,1830000,1830000,1830000,2240000,2240000,1830000,1830000,1500000,2240000,1830000] | | 71 | ["video_thumbs"] | | zalando lounge | 2 | 1 | 823000 | 144189.6 | zalando.pl/ | 3429087 | 2e720c7d15dc72dd3c9643ca1b16ed9c | zalando.pl | 2 | 1 | 0 | 1 | 0 | 292988 | -148798.4 | -0.5079 | zalando.pl/ | 0 | 0.24 | [1000000,823000,823000,823000,823000,1000000,1000000,823000,823000,823000,1000000,823000] | | 41 | [] | | breska | 2 | 0 | 673000 | 117909.6 | zalando.pl/bershka/ | 8961793 | 799275d6ef5fd71542b0775885f3a11a | zalando.pl | 1 | 2 | 0 | 0 | 0 | 117909.6 | 0 | 0 | zalando.pl/bershka/ | 0 | 0.06 | [673000,550000,550000,550000,550000,550000,550000,550000,673000,673000,673000,673000] | | 62 | ["image_thumbs","spell"] | | bershka | 2 | 0 | 550000 | 96360 | zalando.pl/bershka/ | 2843536 | 2684ef5a9bef4d8a830698ab1a5cb1a4 | zalando.pl | 1 | 2 | 0 | 0 | 1 | 96360 | 0 | 0 | zalando.pl/bershka/ | 0 | 0.52 | [450000,450000,550000,550000,550000,550000,550000,550000,550000,450000,550000,550000] | | 77 | ["wiki_right"] | | bersh a | 2 | 0 | 550000 | 96360 | zalando.pl/bershka/ | 16598459 | e0da27950676b2b5df5c8fa3c959e68e | zalando.pl | 2 | 2 | 0 | 0 | 0 | 96360 | 0 | 0 | zalando.pl/bershka/ | 0 | 0.32 | [673000,450000,550000,550000,450000,450000,550000,550000,550000,550000,673000,673000] | | 44 | ["ai_overview","image_thumbs","spell"] | _zalando.pl · 2026-07-05, limit: 5, sort: widoczność malejąco. Wszystkie pola wiersza (poza mapą historii `statistics.position.history` o zmiennych kluczach-datach — jest w JSON i sekcji „Struktura odpowiedzi”)._ Cztery gotowe zastosowania — każda karta pokazuje realne wiersze z żywego API (zalando.pl, 2026-07-03). „Wypróbuj” ładuje kompletny payload do playgroundu na dole i od razu pokazuje pełny wynik. **Quick wins — frazy tuż za TOP10** Pozycje 11–20 z wolumenem ≥ 100: kandydaci do dopchnięcia na 1. stronę Google. _12 614 fraz spełnia ten filtr_ ```json { "filtering": [ { "filters": [ { "key": "statistics.position.current", "match": "gte", "value": 11 }, { "key": "statistics.position.current", "match": "lte", "value": 20 }, { "key": "statistics.searches.current", "match": "gte", "value": 100 } ] } ], "order": { "prop": "statistics.searches.current", "dir": "desc" }, "limit": 10 } ``` | Fraza | Pozycja | Wyszukiwania/mies. | | --- | --- | --- | | sdidas | 11 | 550 000 | | C&A | 12 | 450 000 | | deeze | 20 | 450 000 | [Wiki: quick wins](https://wiki.senuto.com/l/pl/poradniki/jak-znalezc-quick-wins-czyli-frazy-ktorych-pozycje-mozna-latwo-zwiekszyc) **Twoje najsilniejsze frazy (TOP3)** Frazy, na których domena rankuje najwyżej — do pilnowania pozycji i budowy contentu wokół nich. _46 360 fraz w TOP3_ ```json { "filtering": [ { "filters": [ { "key": "statistics.position.current", "match": "lte", "value": 3 } ] } ], "order": { "prop": "statistics.visibility.current", "dir": "desc" }, "limit": 10 } ``` | Fraza | Pozycja | Wyszukiwania/mies. | | --- | --- | --- | | zalando | 1 | 1 830 000 | | zalando lounge | 2 | 823 000 | | breska | 2 | 673 000 | [Wiki: TOP10](https://wiki.senuto.com/en/articles/18043-for-which-keywords-is-your-website-ranking-in-the-top-10) **Tematyczny wycinek („buty”)** Frazy zawierające konkretne słowo (produkt, kategoria) — analiza widoczności w niszy. _20 325 fraz z „buty”_ ```json { "filtering": [ { "filters": [ { "key": "keywords", "items": [ { "match": "contain", "value": "buty" } ] } ] } ], "order": { "prop": "statistics.visibility.current", "dir": "desc" }, "limit": 10 } ``` | Fraza | Pozycja | Wyszukiwania/mies. | | --- | --- | --- | | uggs buty | 1 | 60 500 | | buty zimowe | 1 | 49 500 | | buty zi | 1 | 49 500 | **Frazy, które tracą widoczność** Największe spadki szacowanego ruchu względem poprzedniego pomiaru — lista do pilnej interwencji. _cała domena (291 325 fraz), sortowana po spadku_ ```json { "order": { "prop": "statistics.visibility.diff", "dir": "asc" }, "limit": 10 } ``` | Fraza | Pozycja | Δ widoczności | | --- | --- | --- | | zalando lounge | 2 | −148 798 | | stradivarius | 7 | −66 105 | | bluzę | 4 | −31 350 | ## Odpowiedź Po pomyślnym żądaniu otrzymujesz `data` (tablicę wierszy fraz) oraz `pagination`. ### Surowy JSON **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "keyword_id": 184, "keyword": "toni and paul", "statistics": { "position": { "current": 29 } /* … */ } } ], "pagination": { "page_count": 97041, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 291121, "limit": 10 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "keyword_id": 184, "kid": "0000a7260c00bd42f07edcce28f7c7fa", "domain": "zalando.pl", "keyword": "toni and paul", "words_count": 3, "statistics": { "position": { "current": 29, "previous": 29, "diff": 0, "changes": { "wins": 0, "losses": 0, "no_changes": 0 }, "history": { "2026-05-28": { "position": 29, "has_serp": true } } }, "visibility": { "current": 0, "previous": 0, "diff": 0, "percent": 0, "history": null }, "url": { "current": "zalando.pl/obuwie-meskie/toni-pons/", "previous": "zalando.pl/obuwie-meskie/toni-pons/", "is_change": 0 }, "cpc": { "current": 0 }, "searches": { "current": 10 }, "trends": { "history": [0, 10, 10, 0, 0, 0, 0, 0, 0, 0, 0, 10], "peak": null }, "difficulty": { "current": 33 }, "snippets": { "current": ["image_thumbs", "people_also_ask"] } } } ], "pagination": { "page_count": 97041, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 291121, "limit": 10 } } ``` ### Struktura odpowiedzi ```ts type PositionsResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze fraz */ data: PositionRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type PositionRow = { keyword_id: number; kid: string; domain: string; keyword: string; words_count: number; statistics: { position: { current: number; previous: number; diff: number; changes: { wins: number; losses: number; no_changes: number }; history: Record | [] }; visibility: { current: number; previous: number; diff: number; percent: number; history: null }; url: { current: string; previous: string; is_change: 0 | 1 }; cpc: { current: number }; searches: { current: number }; trends: { history: number[]; peak: number | null }; difficulty: { current: number }; snippets: { current: string[] }; }; } export default PositionsResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, invalid_filtering, unreachable_data, timeout, database, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > **`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 (ta strona) - `getWins` / `getLosses` — frazy, które zyskały / straciły pozycje (taki sam kształt żądania) - `getKeywordHistory` — pełna historia pozycji dla pojedynczej frazy (`keyword_id` + `kid` + `domain` + `fetch_mode`)