--- title: "Historia URL-i: pozyskane (`getAcquired`)" source: https://docs.senuto.com/modules/visibility_analysis/va-history-urls-getAcquired api: POST /api/visibility_analysis/reports/history/urls/getAcquired --- # Historia URL-i: pozyskane (`getAcquired`) **`POST /api/visibility_analysis/reports/history/urls/getAcquired`** Zwraca adresy URL domeny **pozyskane** w badanym okresie — takie, które zaczęły rankować między `date_min` a `date_max` (tryb `MODE_GAIN`). W odróżnieniu od raportu historii fraz, ten raport agreguje dane **po adresach URL**, a nie po pojedynczych frazach — każdy wiersz opisuje jeden URL wraz ze statystykami: liczbą fraz, przedziałami pozycji (`top3`/`top10`/`top50`), widocznością (szacowany ruch), średnią i sumaryczną pozycją oraz liczbą fraz, które zyskały (`wins`) i straciły (`losses`). | URL | Frazy | TOP3 | TOP3 poprz. | TOP3 Δ | TOP3 % | TOP10 | TOP10 poprz. | TOP10 Δ | TOP10 % | TOP50 | TOP50 poprz. | TOP50 Δ | TOP50 % | Widoczność | Widoczność poprz. | Widoczność Δ | Widoczność % | Śr. pozycja | Śr. pozycja poprz. | Śr. pozycja Δ | Suma pozycji | Suma pozycji poprz. | Suma pozycji Δ | Suma pozycji % | Wzrosty (fraz) | Spadki (fraz) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | zalando.pl/obuwie/ugg/ | 6 | 1 | 1 | 0 | 0 | 3 | 3 | 0 | 0 | 2 | 2 | 0 | 0 | 31198.72 | 5235.75 | 25962.97 | 4.9588 | 10 | 8 | 2 | 62 | 52 | 10 | 0.1923 | 5 | 1 | | zalando.pl/obuwie/?q=nike+air+max | 20 | 5 | 6 | -1 | -0.1667 | 2 | 4 | -2 | -0.5 | 13 | 10 | 3 | 0.3 | 21723.24 | 11914.02 | 9809.23 | 0.8233 | 16 | 17 | -1 | 323 | 349 | -26 | -0.0745 | 15 | 5 | _zalando.pl (2026-06-20 → 2026-06-29) — URL-e pozyskane w okresie. Wszystkie pola wiersza (poza mapami o kluczach-datach — są w JSON). Uwaga: keywords_count, wins i losses przychodzą jako stringi._ --- ## Żądanie `POST` `/api/visibility_analysis/reports/history/urls/getAcquired` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żą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** ```jsonc filename="żą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** ```bash curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/history/urls/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 ```ts type HistoryUrlsGetAcquiredRequest = { /** * **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; wartość "domain" **nie istnieje**) * - `subdomain` — pojedyncza subdomena * - `catalog` — ścieżka/katalog * - `url` — dokładny URL */ fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url'; /** * **Wymagane**. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem "Unknown country_id". */ country_id: number; /** * **Wymagane**. Początek zakresu dat, `YYYY-MM-DD`. Musi być nie późniejszy niż `date_max`. */ date_min: string; /** * **Wymagane**. Koniec zakresu dat, `YYYY-MM-DD`. Musi być nie wcześniejszy niż `date_min`. */ date_max: string; /** * **Wymagane**. **Pojedyncza** dyrektywa sortowania (jeden obiekt — nie tablica). * * Dozwolone wartości `prop` (tylko 4 — inaczej niż w raporcie fraz): * - `statistics.visibility.current` * - `statistics.visibility.previous` * - `statistics.visibility.diff` * - `statistics.visibility.percent` * * Inna wartość → `418` `invalid_data` z komunikatem "This value is not allow. Please use correct colum name" (pisownia oryginalna). */ order: { prop: | 'statistics.visibility.current' | 'statistics.visibility.previous' | 'statistics.visibility.diff' | 'statistics.visibility.percent'; dir: 'asc' | 'desc'; }; /** * Liczba wierszy na stronę. * @default 10 */ limit?: number; /** * Numer strony. * @default 1 */ page?: number; /** * Opcjonalne filtrowanie wyników. Kontroler przyjmuje ten parametr (wg źródła), * ale zestaw dozwolonych kluczy filtrów dla raportu URL-i **nie został jeszcze * zweryfikowany na żywo** — używaj ostrożnie. */ filtering?: unknown; } export default HistoryUrlsGetAcquiredRequest ``` > **Ostrzeżenie:** > **`order` to pojedynczy obiekt** (`{ prop, dir }`) — nie tablica. Ten raport dopuszcza wyłącznie 4 właściwości sortowania (`statistics.visibility.*`) — próba sortowania np. po `keyword` lub `statistics.position.current` zakończy się błędem `418`. > **Ostrzeżenie:** > Wymagane są: **`domain`**, **`fetch_mode`**, **`country_id`**, **`date_min`**, **`date_max`** oraz pojedynczy obiekt **`order`** (`{ prop, dir }` — nie tablica). Dozwolone są **tylko 4** wartości `order.prop` (właściwości `statistics.visibility.*`) — mniej niż w raporcie fraz, który ma ich 11. Wartość `fetch_mode: "domain"` **nie istnieje** — użyj `topLevelDomain`. Uwaga na typy: część pól liczbowych przychodzi jako **stringi** (`keywords_count`, `statistics.wins.current`, `statistics.losses.current`). ## Odpowiedź W przypadku powodzenia otrzymujesz `data` (tablicę wierszy z URL-ami) oraz `pagination`. Dla zapytania (`zalando.pl`, 2026-06-20 → 2026-06-29) raport zwrócił `count` = 1 527 pozyskanych URL-i. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "url": "zalando.pl/obuwie/ugg/", "keywords_count": "6", "statistics": { "visibility": { "current": 31198.72, "previous": 5235.75, "diff": 25962.97 } /* … */ } } ], "pagination": { "page_count": 764, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 1527, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "url": "zalando.pl/obuwie/ugg/", "keywords_count": "6", "statistics": { "top3": { "current": 1, "previous": 1, "diff": 0, "percent": 0 }, "top10": { "current": 3, "previous": 3, "diff": 0, "percent": 0 }, "top50": { "current": 2, "previous": 2, "diff": 0, "percent": 0 }, "visibility": { "current": 31198.72, "previous": 5235.75, "diff": 25962.97, "percent": 4.9588 }, "position": { "current": 10, "previous": 8, "diff": 2 }, "summary_position": { "current": 62, "previous": 52, "diff": 10, "percent": 0.1923 }, "wins": { "current": "5" }, "losses": { "current": "1" } } }, { "url": "zalando.pl/obuwie/?q=nike+air+max", "keywords_count": "20", "statistics": { "top3": { "current": 5, "previous": 6, "diff": -1, "percent": -0.1667 }, "top10": { "current": 2, "previous": 4, "diff": -2, "percent": -0.5 }, "top50": { "current": 13, "previous": 10, "diff": 3, "percent": 0.3 }, "visibility": { "current": 21723.24, "previous": 11914.02, "diff": 9809.23, "percent": 0.8233 }, "position": { "current": 16, "previous": 17, "diff": -1 }, "summary_position": { "current": 323, "previous": 349, "diff": -26, "percent": -0.0745 }, "wins": { "current": "15" }, "losses": { "current": "5" } } } ], "pagination": { "page_count": 764, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 1527, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type HistoryUrlsGetAcquiredResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze z URL-ami */ data: UrlRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type UrlRow = { /** Adres URL (bez protokołu) */ url: string; /** Liczba fraz rankujących na ten URL. **Uwaga: string, nie number.** */ keywords_count: string; statistics: { /** Liczba fraz URL-a w TOP 3 (`{ current, previous, diff, percent }`) */ top3: RangeStat; /** Liczba fraz URL-a w TOP 10 */ top10: RangeStat; /** Liczba fraz URL-a w TOP 50 */ top50: RangeStat; /** Widoczność — szacowany ruch */ visibility: RangeStat; /** Średnia pozycja (bez pola percent) */ position: { current: number; previous: number; diff: number }; /** Suma pozycji */ summary_position: RangeStat; /** Liczba fraz, które zyskały w tym URL-u. **Uwaga: string, nie number.** */ wins: { current: string }; /** Liczba fraz, które straciły w tym URL-u. **Uwaga: string, nie number.** */ losses: { current: string }; }; } type RangeStat = { current: number; previous: number; diff: number; percent: number; } export default HistoryUrlsGetAcquiredResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, database, timeout, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > **`418`** zwracany jest również dla błędów walidacji — nie tylko przy ograniczeniu liczby żądań (rate limiting). Nieznane `country_id` → `418` z komunikatem "Unknown country\_id". Niedozwolony `order.prop` → `418` `invalid_data` z komunikatem "This value is not allow. Please use correct colum name" (pisownia oryginalna). > > **Znany błąd — odwrócony komunikat.** Gdy `date_min` jest **późniejszy** niż `date_max`, reguła `DateRangeRules` zwraca komunikat `"date_max must be less or equal than date_min"` — treść jest odwrócona; należy go odczytywać jako naruszenie reguły zakresu dat, a nie jako dosłowną instrukcję. ## Powiązane akcje - `getData` — pełna lista URL-i w zakresie dat (taka sama struktura żądania) - `getWins` — URL-e, których widoczność wzrosła w zakresie dat - `getLosses` — URL-e, których widoczność spadła w zakresie dat - `getAcquired` — URL-e nowo pozyskane (`MODE_GAIN`, ta strona) - `getLost` — URL-e utracone (przestały rankować w badanym okresie)