--- title: "Adresy URL (`getUrls`)" source: https://docs.senuto.com/modules/visibility_analysis/va-sections-getUrls api: POST /api/visibility_analysis/reports/sections/getUrls --- # Adresy URL (`getUrls`) **`POST /api/visibility_analysis/reports/sections/getUrls`** Zwraca widoczność domeny w rozbiciu na pojedyncze adresy URL. Każdy wiersz odpowiada jednemu adresowi (pole `url`) i zawiera liczbę fraz oraz statystyki `visibility`, `top3`, `top10` i `top50` w formacie `{current, previous, diff, percent, history}`. Użyj tej akcji, aby znaleźć konkretne podstrony generujące widoczność w wynikach wyszukiwania. | URL | Frazy | Udział wid. % | Widoczność | Widoczność poprz. | Widoczność Δ | Widoczność % | TOP3 | TOP3 poprz. | TOP3 Δ | TOP3 % | TOP10 | TOP10 poprz. | TOP10 Δ | TOP10 % | TOP50 | TOP50 poprz. | TOP50 Δ | TOP50 % | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | zalando.pl/ | 226 | 0 | 963824.36 | 963804.6 | 19.76 | 0 | 119 | 120 | -1 | -0.0083 | 226 | 224 | 2 | 0.0089 | 3035 | 2933 | 102 | 0.0348 | | zalando.pl/bershka/ | 70 | 0 | 311746.17 | 311727.33 | 18.83 | 0.0001 | 28 | 27 | 1 | 0.037 | 70 | 72 | -2 | -0.0278 | 150 | 150 | 0 | 0 | _zalando.pl — adresy URL o najwyższej widoczności. Wszystkie pola wiersza (poza mapami historii `statistics.*.history` o kluczach-datach — są w JSON; w tej odpowiedzi mają wartość null)._ --- ## Żądanie `POST` `/api/visibility_analysis/reports/sections/getUrls` 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 } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "limit": 2, "page": 1 } ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/sections/getUrls' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain", "country_id": 1, "limit": 2 }' ``` ### Parametry ```ts type SectionsGetUrlsRequest = { /** * **Wymagane**. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z `fetch_mode`. */ domain: string; /** * **Wymagane**. Sposób interpretacji `domain`. * - `topLevelDomain` — cała domena * - `subdomain` — pojedyncza subdomena * - `catalog` — ścieżka/katalog * - `url` — dokładny URL * * Wartość `"domain"` nie istnieje — użyj `topLevelDomain`. */ fetch_mode: 'topLevelDomain' | 'subdomain' | 'catalog' | 'url'; /** * **Wymagane**. Id kraju (bazy danych). Polska = `1`. Nieznana wartość zwraca `418` z komunikatem `Unknown country_id`. */ country_id: number; /** * Liczba wierszy na stronę. * @default 10 */ limit?: number; /** * Numer strony. * @default 1 */ page?: number; } export default SectionsGetUrlsRequest ``` > **Ostrzeżenie:** > Ten endpoint **nie obsługuje** parametrów `order` ani `filtering`. Jeśli je wyślesz, API zwróci `200`, ale zostaną **zignorowane** — wyniki wracają w kolejności domyślnej. Zweryfikowane na prod — endpoint ich nie odczytuje. W przeciwieństwie do raportu `positions`, sekcje nie mają sortowania ani filtrowania po stronie API — jedyne parametry sterujące to `limit` i `page`. > **Ostrzeżenie:** > Trzy parametry są **wymagane** (walidator `SectionsValidator`): **`domain`**, **`fetch_mode`** oraz **`country_id`**. Dozwolone wartości `fetch_mode` to `topLevelDomain`, `subdomain`, `catalog` i `url` — wartość `"domain"` **nie istnieje**. Nieznane `country_id` zwraca `418` z komunikatem `"Unknown country_id"`. ## Odpowiedź W przypadku powodzenia otrzymujesz `data` (tablicę adresów URL) oraz `pagination`. Dla `zalando.pl` API zwróciło łącznie 72 773 adresy. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "url": "zalando.pl/", "keywords_count": 226, "statistics": { "visibility": { "current": 963824.36 } /* … */ } }, { "url": "zalando.pl/bershka/", "keywords_count": 70, "statistics": { "visibility": { "current": 311746.17 } /* … */ } } ], "pagination": { "page_count": 36387, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 72773, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "url": "zalando.pl/", "keywords_count": 226, "visibility_percent": 0, "statistics": { "visibility": { "current": 963824.36, "previous": 963804.6, "diff": 19.76, "percent": 0, "history": null }, "top3": { "current": 119, "previous": 120, "diff": -1, "percent": -0.0083, "history": null }, "top10": { "current": 226, "previous": 224, "diff": 2, "percent": 0.0089, "history": null }, "top50": { "current": 3035, "previous": 2933, "diff": 102, "percent": 0.0348, "history": null } } }, { "url": "zalando.pl/bershka/", "keywords_count": 70, "visibility_percent": 0, "statistics": { "visibility": { "current": 311746.17, "previous": 311727.33, "diff": 18.83, "percent": 0.0001, "history": null }, "top3": { "current": 28, "previous": 27, "diff": 1, "percent": 0.037, "history": null }, "top10": { "current": 70, "previous": 72, "diff": -2, "percent": -0.0278, "history": null }, "top50": { "current": 150, "previous": 150, "diff": 0, "percent": 0, "history": null } } } ], "pagination": { "page_count": 36387, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 72773, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type SectionsGetUrlsResponse = { /** `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 = { /** Pojedynczy adres URL, np. "zalando.pl/bershka/" */ url: string; /** Liczba fraz w TOP10 przypisanych do adresu */ keywords_count: number; /** Procentowy udział adresu w widoczności */ visibility_percent: number; statistics: { visibility: StatEntry; top3: StatEntry; top10: StatEntry; top50: StatEntry; }; } type StatEntry = { current: number; previous: number; diff: number; percent: number; history: null; } export default SectionsGetUrlsResponse ``` ## 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). Brak wymaganego pola zwraca `invalid_data` z mapą `params`, a nieznane `country_id` zwraca komunikat `"Unknown country_id"`. ## Powiązane akcje - [`getSections`](/modules/visibility_analysis/va-sections-getSections) — widoczność zagregowana po sekcjach URL (katalogach) domeny - [`getSubdomains`](/modules/visibility_analysis/va-sections-getSubdomains) — widoczność per subdomena (dodatkowo `visibility_coverage`) - `getUrls` — widoczność per pojedynczy adres URL (ta strona)