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.

Podgląd · 6 z 19 kolumn

Sekcja URL	Frazy	Udział wid. %	Widoczność	Widoczność poprz.	Widoczność Δ
zalando.pl/	26 672	0	1 143 250,66	1 136 367,71	6882,95
zalando.pl/obuwie/	7012	0	471 266,74	444 738,36	26 528,38

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 <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "limit": 2,
  "page": 1
}

cURL


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

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 `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny URL Wartość `"domain"` nie istnieje — użyj `topLevelDomain`.
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`. Nieznana wartość zwraca `418` z komunikatem `Unknown country_id`.
`limit`	`number` Liczba wierszy na stronę.	`10`
`page`	`number` Numer strony.	`1`

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.

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

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 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`SectionRow[]` Zwrócone wiersze z sekcjami URL
`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 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 — widoczność per subdomena (dodatkowo visibility_coverage)
getUrls — widoczność per pojedynczy adres URL

Sekcje domeny (getSections)