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

Żądanie

POST /api/visibility_analysis/reports/positions/getData

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

Wymagane pola: domain (domena) i fetch_mode (zakres analizy, np. topLevelDomain).

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


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

Rozszerzony

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


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

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`
`with_history`	`boolean` Dołącz do odpowiedzi mapę historii pozycji (`history`) dla każdej frazy.	`true`
`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`	`{ filters: ({ key: string; match: "eq" \| "gt" \| "gte" \| "lt" \| "lte"; value: string \| number; } \| { key: "keywords"; items: { match: "contain" \| "containsWord" \| "startsWith" \| "endsWith" \| "notContain"; value: string; }[]; })[]; }[]` 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.

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.

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.

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

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.

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

Tak wyglądają realne wiersze zwrócone przez API (5 pierwszych wyników dla zalando.pl), rozpisane w tabeli.

Podgląd · 6 z 24 kolumn

Fraza	Pozycja	Zmiana pozycji	Wyszukiwania/mies.	Widoczność	URL bieżący
zalando	1	0	1 830 000	651 480	zalando.pl/
zalando lounge	2	1	823 000	144 189,6	zalando.pl/
breska	2	0	673 000	117 909,6	zalando.pl/bershka/
bershka	2	0	550 000	96 360	zalando.pl/bershka/
bersh a	2	0	550 000	96 360	zalando.pl/bershka/

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

Co zwraca ten endpoint w praktyce

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

12 614 fraz spełnia ten filtr

Pozycje 11–20 z wolumenem ≥ 100: kandydaci do dopchnięcia na 1. stronę Google.

Fraza	Pozycja	Wyszukiwania/mies.
sdidas	11	550 000
C&A	12	450 000
deeze	20	450 000

pokaż payload

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

Wiki: quick wins

Twoje najsilniejsze frazy (TOP3)

46 360 fraz w TOP3

Frazy, na których domena rankuje najwyżej — do pilnowania pozycji i budowy contentu wokół nich.

Fraza	Pozycja	Wyszukiwania/mies.
zalando	1	1 830 000
zalando lounge	2	823 000
breska	2	673 000

pokaż payload

{
  "filtering": [
    {
      "filters": [
        {
          "key": "statistics.position.current",
          "match": "lte",
          "value": 3
        }
      ]
    }
  ],
  "order": {
    "prop": "statistics.visibility.current",
    "dir": "desc"
  },
  "limit": 10
}

Wiki: TOP10

Tematyczny wycinek („buty”)

20 325 fraz z „buty”

Frazy zawierające konkretne słowo (produkt, kategoria) — analiza widoczności w niszy.

Fraza	Pozycja	Wyszukiwania/mies.
uggs buty	1	60 500
buty zimowe	1	49 500
buty zi	1	49 500

pokaż payload

{
  "filtering": [
    {
      "filters": [
        {
          "key": "keywords",
          "items": [
            {
              "match": "contain",
              "value": "buty"
            }
          ]
        }
      ]
    }
  ],
  "order": {
    "prop": "statistics.visibility.current",
    "dir": "desc"
  },
  "limit": 10
}

Frazy, które tracą widoczność

cała domena (291 325 fraz), sortowana po spadku

Największe spadki szacowanego ruchu względem poprzedniego pomiaru — lista do pilnej interwencji.

Fraza	Pozycja	Δ widoczności
zalando lounge	2	−148 798
stradivarius	7	−66 105
bluzę	4	−31 350

pokaż payload

{
  "order": {
    "prop": "statistics.visibility.diff",
    "dir": "asc"
  },
  "limit": 10
}

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data (tablicę wierszy fraz) oraz pagination.

Surowy JSON

Skrócona

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

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`PositionRow[]` Zwrócone wiersze fraz
`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 (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)

Bieżące pozycje (getData)

Żądanie

Struktura żądania

Podstawowy

Rozszerzony

cURL

Parametry

Filtrowanie

Dostępne klucze (positions/getData)

Przykładowe dane i zastosowania

Co zwraca ten endpoint w praktyce

Odpowiedź

Surowy JSON

Skrócona

Pełna

Struktura odpowiedzi

Błędy

Powiązane akcje

Bieżące pozycje (`getData`)

Dostępne klucze (`positions/getData`)