Historia fraz: pozyskane (`getAcquired`)

POST/api/visibility_analysis/reports/history/keywords/getAcquired

Zwraca frazy pozyskane w zadanym zakresie dat: na date_min domena nie rankowała w TOP50, a na date_max już rankuje (tryb MODE_GAIN tego samego komponentu danych co getData). W zwracanych wierszach statistics.position.previous ma zawsze wartość sentinela 51 (poza TOP50), statistics.url.previous jest puste, statistics.url.is_change = 1, a statistics.visibility.percent = 1 (100% wzrostu z zera). Struktura żądania jest identyczna jak w getData.

Te wiersze pojawiają się również w getWins. Fraza pozyskana ma position.previous = 51, więc jej diff jest ujemny i spełnia także warunek wzrostu. getAcquired jest podzbiorem getWins — sklejanie obu list zdubluje wiersze.

Uwaga: w drugą stronę jest inaczej. getLost i getLosses są rozłączne i tam sklejenie jest poprawne. Ta asymetria może się w przyszłości ujednolicić.

Podgląd · 6 z 24 kolumn

Fraza	ID frazy	KID	Domena	Liczba słów	Pozycja
plecak nike	12682481	abe87dec4fc0e9b7386f2718c0092aa2	zalando.pl	2	5
air force 1 mid	16378096	dde117ca968b0e7a3cfc124ca6660b30	zalando.pl	4	2

zalando.pl, sort: widoczność malejąco — frazy pozyskane w zakresie. Poprzednia pozycja 51 to sentinel „poza TOP50”. 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/getAcquired

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": 2,
  "page": 1
}

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/history/keywords/getAcquired' \
  --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; wartość “domain” nie istnieje) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL
`date_min`	`string` Wymagane. Początek zakresu dat, `YYYY-MM-DD`. Na tę datę domena nie rankowała w TOP50 na zwracane frazy. Dostępne daty pobierzesz akcją `getDates`.
`date_max`	`string` Wymagane. Koniec zakresu dat, `YYYY-MM-DD`. Na tę datę domena rankuje na zwracane frazy.
`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` 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`
`filtering`	`FilterGroup[]` Tablica grup filtrów — ten sam mechanizm i te same klucze co w `positions/getData` oraz `history/keywords/getData`. Szczegóły: typy filtrów.

order to pojedynczy obiekt ({ prop, dir }) — nie tablica. Używaj ścieżek prop z kropkami wymienionych powyżej; inne wartości zwracają 418 z komunikatem "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 ({ prop, dir } — nie tablica). Wartość fetch_mode = "domain" nie istnieje — używaj topLevelDomain. Nieznane country_id zwraca 418 z komunikatem "Unknown country_id". Pozycja 51 to sentinel oznaczający „poza TOP50” — nie rzeczywistą pozycję w SERP.

Odpowiedź

W przypadku powodzenia otrzymujesz data (tablicę wierszy z frazami pozyskanymi) oraz pagination. Charakterystyka trybu MODE_GAIN: position.previous = 51 (sentinel „poza TOP50”), url.previous = "", url.is_change = 1 (liczbowo), visibility.previous = 0, visibility.percent = 1.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "keyword_id": 12682481, "keyword": "plecak nike", "statistics": { "position": { "current": 5, "previous": 51 }, "visibility": { "current": 2489.85, "previous": 0, "percent": 1 } /* … */ } }
  ],
  "pagination": { "page_count": 1812, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 3623, "limit": 2 }
}

Pełna

przykładowa-odpowiedź (200)


{
  "success": true,
  "data": [
    {
      "keyword_id": 12682481,
      "kid": "abe87dec4fc0e9b7386f2718c0092aa2",
      "domain": "zalando.pl",
      "keyword": "plecak nike",
      "words_count": 2,
      "statistics": {
        "position": { "current": 5, "previous": 51, "diff": -46, "changes": { "wins": 0, "losses": 1, "no_changes": 0 }, "history": { "2026-05-25": { "position": 0, "has_serp": true }, "2026-06-26": { "position": 5, "has_serp": true } } },
        "visibility": { "current": 2489.85, "previous": 0, "diff": 2489.85, "percent": 1, "history": null },
        "url": { "current": "zalando.pl/akcesoria-plecaki/nike/", "previous": "", "is_change": 1 },
        "cpc": { "current": 0.53 },
        "searches": { "current": 49500 },
        "trends": { "history": [27100, 33100, 90500, 201000, 49500, 22200, 27100, 27100, 22200, 22200, 27100, 22200], "peak": null },
        "difficulty": { "current": 60 },
        "snippets": { "current": ["image_thumbs"] }
      }
    },
    {
      "keyword_id": 16378096,
      "kid": "dde117ca968b0e7a3cfc124ca6660b30",
      "domain": "zalando.pl",
      "keyword": "air force 1 mid",
      "words_count": 4,
      "statistics": {
        "position": { "current": 2, "previous": 51, "diff": -49, "changes": { "wins": 0, "losses": 0, "no_changes": 0 }, "history": { "2026-06-26": { "position": 2, "has_serp": true } } },
        "visibility": { "current": 946.08, "previous": 0, "diff": 946.08, "percent": 1, "history": null },
        "url": { "current": "zalando.pl/obuwie/?q=air+force+1+mid", "previous": "", "is_change": 1 },
        "cpc": { "current": 0.8 },
        "searches": { "current": 5400 },
        "trends": { "history": [5400, 3600, 4400, 2900, 2400, 1900, 2400, 5400, 8100, 9900, 9900, 8100], "peak": null },
        "difficulty": { "current": 46 },
        "snippets": { "current": ["image_thumbs"] }
      }
    }
  ],
  "pagination": { "page_count": 1812, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 3623, "limit": 2 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`AcquiredKeywordRow[]` Zwrócone wiersze z frazami pozyskanymi
`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 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 brzmi "date_max must be less or equal than date_min" — treść jest odwrócona; 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 / getLosses — frazy, które zyskały / straciły pozycje w danym zakresie (taka sama struktura żądania)
getAcquired — frazy nowo pozyskane w zakresie (ta strona)
getLost — frazy całkowicie utracone w zakresie (taka sama struktura żądania)
getDates — dostępne daty dla zakresu (POST, wymaga tylko country_id)

Historia fraz: pozyskane (getAcquired)