--- title: "Historia URL-i: przegląd (`getData`)" source: https://docs.senuto.com/modules/visibility_analysis/va-history-urls-getData api: POST /api/visibility_analysis/reports/history/urls/getData --- # Historia URL-i: przegląd (`getData`) **`POST /api/visibility_analysis/reports/history/urls/getData`** Zwraca pełną listę adresów URL domeny wraz z porównaniem statystyk widoczności między `date_min` a `date_max`. W odróżnieniu od raportu historii fraz, ten raport agreguje dane **po adresach URL** — dla każdego adresu otrzymujesz liczbę fraz (`keywords_count`) oraz zestaw statystyk `{current, previous, diff, percent}`: liczbę fraz w TOP3/TOP10/TOP50, szacowany ruch (`visibility`), średnią pozycję (`position`), sumę pozycji (`summary_position`) oraz liczbę fraz, które zyskały (`wins`) i straciły (`losses`). Wyniki są sortowane według pojedynczej dyrektywy sortowania. | 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/ | 3084 | 251 | 116 | 135 | 1.1638 | 104 | 108 | -4 | -0.037 | 2729 | 2860 | -131 | -0.0458 | 963643.78 | 963614.83 | 28.95 | 0 | 30 | 32 | -2 | 94624 | 99195 | -4571 | -0.0461 | 156 | 12 | | zalando.pl/bershka/ | 149 | 29 | 27 | 2 | 0.0741 | 40 | 44 | -4 | -0.0909 | 80 | 78 | 2 | 0.0256 | 311727.2 | 311733.03 | -5.83 | 0 | 15 | 15 | 0 | 2326 | 2342 | -16 | -0.0068 | 5 | 5 | _zalando.pl (2026-06-20 → 2026-06-29). 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/getData` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "date_min": "2026-06-20", "date_max": "2026-06-29", "order": { "prop": "statistics.visibility.current", "dir": "desc" } } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "date_min": "2026-06-20", "date_max": "2026-06-29", "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/getData' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "date_min": "2026-06-20", "date_max": "2026-06-29", "order": { "prop": "statistics.visibility.current", "dir": "desc" } }' ``` ### Parametry ```ts type HistoryUrlsGetDataRequest = { /** * **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`. Nie może być późniejszy niż `date_max`. */ date_min: string; /** * **Wymagane**. Koniec zakresu dat, `YYYY-MM-DD`. Nie może być 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 historii fraz): * - `statistics.visibility.current` * - `statistics.visibility.previous` * - `statistics.visibility.diff` * - `statistics.visibility.percent` * * Błędny `prop` → `418` `invalid_data` z komunikatem "This value is not allow. Please use correct colum name". */ 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; } export default HistoryUrlsGetDataRequest ``` > **Ostrzeżenie:** > **`order` to pojedynczy obiekt** (`{ prop, dir }`) — nie tablica — i akceptuje wyłącznie 4 właściwości z gałęzi `statistics.visibility.*` wymienione powyżej. Kontroler przyjmuje też opcjonalny parametr `filtering`, jednak zestaw dozwolonych kluczy filtrów dla tego raportu **nie został jeszcze zweryfikowany na żywo** — nie należy zakładać, że filtry znane z innych raportów zadziałają tutaj tak samo. > **Ostrzeżenie:** > Pięć parametrów jest **wymaganych**: **`domain`**, **`fetch_mode`**, **`country_id`**, **`date_min`**, **`date_max`**, a także pojedynczy obiekt **`order`** (`{ prop, dir }` — nie tablica). Wartość `fetch_mode: "domain"` **nie istnieje** — użyj `topLevelDomain`. Dozwolone są **tylko 4** wartości `order.prop` (wszystkie z gałęzi `statistics.visibility.*`) — to mniej niż w raporcie historii fraz. 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 adresami URL) oraz `pagination`. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "url": "zalando.pl/", "keywords_count": "3084", "statistics": { "visibility": { "current": 963643.78 }, "top3": { "current": 251 } /* … */ } } ], "pagination": { "page_count": 36677, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 73353, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "url": "zalando.pl/", "keywords_count": "3084", "statistics": { "top3": { "current": 251, "previous": 116, "diff": 135, "percent": 1.1638 }, "top10": { "current": 104, "previous": 108, "diff": -4, "percent": -0.037 }, "top50": { "current": 2729, "previous": 2860, "diff": -131, "percent": -0.0458 }, "visibility": { "current": 963643.78, "previous": 963614.83, "diff": 28.95, "percent": 0 }, "position": { "current": 30, "previous": 32, "diff": -2 }, "summary_position": { "current": 94624, "previous": 99195, "diff": -4571, "percent": -0.0461 }, "wins": { "current": "156" }, "losses": { "current": "12" } } }, { "url": "zalando.pl/bershka/", "keywords_count": "149", "statistics": { "top3": { "current": 29, "previous": 27, "diff": 2, "percent": 0.0741 }, "top10": { "current": 40, "previous": 44, "diff": -4, "percent": -0.0909 }, "top50": { "current": 80, "previous": 78, "diff": 2, "percent": 0.0256 }, "visibility": { "current": 311727.2, "previous": 311733.03, "diff": -5.83, "percent": 0 }, "position": { "current": 15, "previous": 15, "diff": 0 }, "summary_position": { "current": 2326, "previous": 2342, "diff": -16, "percent": -0.0068 }, "wins": { "current": "5" }, "losses": { "current": "5" } } } ], "pagination": { "page_count": 36677, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 73353, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type HistoryUrlsResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze z adresami URL */ 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 przypisanych do URL-a — UWAGA: zwracana jako string, np. "3084" */ keywords_count: string; statistics: { /** Liczba fraz URL-a na pozycjach 1–3 */ top3: { current: number; previous: number; diff: number; percent: number }; /** Liczba fraz URL-a na pozycjach 4–10 */ top10: { current: number; previous: number; diff: number; percent: number }; /** Liczba fraz URL-a na pozycjach 11–50 */ top50: { current: number; previous: number; diff: number; percent: number }; /** Szacowany ruch (widoczność) URL-a */ visibility: { current: number; previous: number; diff: number; percent: number }; /** Średnia pozycja fraz URL-a (bez pola percent) */ position: { current: number; previous: number; diff: number }; /** Suma pozycji fraz URL-a */ summary_position: { current: number; previous: number; diff: number; percent: number }; /** Liczba fraz, które zyskały pozycje — UWAGA: string, np. "156" */ wins: { current: string }; /** Liczba fraz, które straciły pozycje — UWAGA: string, np. "12" */ losses: { current: string }; }; } export default HistoryUrlsResponse ``` ## 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.** Przy `date_min > date_max` walidator `DateRangeRules` zwraca komunikat `"date_max must be less or equal than date_min"` — treść jest odwrócona (to `date_min` musi być nie późniejszy niż `date_max`). Należy go odczytywać jako niepowodzenie reguły zakresu dat, a nie jako dosłowną instrukcję. ## Powiązane akcje - `getData` — pełna lista URL-i w zakresie dat (ta strona) - [`getWins`](/modules/visibility_analysis/va-history-urls-getWins) — URL-e, których widoczność wzrosła w danym zakresie (taka sama struktura żądania) - `getLosses` — URL-e, których widoczność spadła w danym zakresie - `getAcquired` — URL-e nowo pozyskane w zakresie - `getLost` — URL-e całkowicie utracone w zakresie