--- title: "Sekcje domeny (`getSections`)" source: https://docs.senuto.com/modules/visibility_analysis/va-sections-getSections api: POST /api/visibility_analysis/reports/sections/getSections --- # Sekcje domeny (`getSections`) **`POST /api/visibility_analysis/reports/sections/getSections`** Zwraca widoczność domeny zagregowaną po sekcjach URL (katalogach). Każdy wiersz odpowiada jednej sekcji (`url_section`) i zawiera liczbę fraz oraz statystyki `visibility`, `top3`, `top10` i `top50` w formacie `{current, previous, diff, percent, history}`. Użyj tej akcji, aby zobaczyć, które części serwisu (np. `zalando.pl/obuwie/`) generują widoczność w wynikach wyszukiwania. | Sekcja 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/ | 26672 | 0 | 1143250.66 | 1136367.71 | 6882.95 | 0.0061 | 7886 | 7848 | 38 | 0.0048 | 26672 | 26441 | 231 | 0.0087 | 73530 | 72995 | 535 | 0.0073 | | zalando.pl/obuwie/ | 7012 | 0 | 471266.74 | 444738.36 | 26528.38 | 0.0596 | 2727 | 2732 | -5 | -0.0018 | 7012 | 7023 | -11 | -0.0016 | 14666 | 14641 | 25 | 0.0017 | _zalando.pl — sekcje 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/getSections` 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/getSections' \ --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 SectionsGetSectionsRequest = { /** * **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 SectionsGetSectionsRequest ``` > **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 (`dir: 'asc'` i `'desc'` dają identyczną kolejność) — 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ę sekcji URL) oraz `pagination`. Dla `zalando.pl` API zwróciło łącznie 4528 sekcji. **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": [ { "url_section": "zalando.pl/", "keywords_count": 26672, "statistics": { "visibility": { "current": 1143250.66 } /* … */ } }, { "url_section": "zalando.pl/obuwie/", "keywords_count": 7012, "statistics": { "visibility": { "current": 471266.74 } /* … */ } } ], "pagination": { "page_count": 2264, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 4528, "limit": 2 } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": [ { "url_section": "zalando.pl/", "keywords_count": 26672, "visibility_percent": 0, "statistics": { "visibility": { "current": 1143250.66, "previous": 1136367.71, "diff": 6882.95, "percent": 0.0061, "history": null }, "top3": { "current": 7886, "previous": 7848, "diff": 38, "percent": 0.0048, "history": null }, "top10": { "current": 26672, "previous": 26441, "diff": 231, "percent": 0.0087, "history": null }, "top50": { "current": 73530, "previous": 72995, "diff": 535, "percent": 0.0073, "history": null } } }, { "url_section": "zalando.pl/obuwie/", "keywords_count": 7012, "visibility_percent": 0, "statistics": { "visibility": { "current": 471266.74, "previous": 444738.36, "diff": 26528.38, "percent": 0.0596, "history": null }, "top3": { "current": 2727, "previous": 2732, "diff": -5, "percent": -0.0018, "history": null }, "top10": { "current": 7012, "previous": 7023, "diff": -11, "percent": -0.0016, "history": null }, "top50": { "current": 14666, "previous": 14641, "diff": 25, "percent": 0.0017, "history": null } } } ], "pagination": { "page_count": 2264, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 4528, "limit": 2 } } ``` ### Struktura odpowiedzi ```ts type SectionsGetSectionsResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Zwrócone wiersze z sekcjami URL */ data: SectionRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }; } type SectionRow = { /** Sekcja URL (katalog) domeny, np. "zalando.pl/obuwie/" */ url_section: string; /** Liczba fraz w TOP10 przypisanych do sekcji */ keywords_count: number; /** Procentowy udział sekcji 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 SectionsGetSectionsResponse ``` ## 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` — widoczność zagregowana po sekcjach URL (katalogach) domeny (ta strona) - [`getSubdomains`](/modules/visibility_analysis/va-sections-getSubdomains) — widoczność per subdomena (dodatkowo `visibility_coverage`) - [`getUrls`](/modules/visibility_analysis/va-sections-getUrls) — widoczność per pojedynczy adres URL