Cechy fraz: tabela (`getCharacteristicsTable`)

POST/api/visibility_analysis/reports/keywords/getCharacteristicsTable

Zwraca rozkład fraz domeny według wybranej cechy (characteristics) w formie tabeli: każdy wiersz to jeden kubełek (np. liczba słów we frazie) wraz z liczbą fraz, liczbą pozycji w TOP3/TOP10/TOP50 oraz statystykami widoczności (suma, widoczność całej domeny, udział procentowy). To tabelaryczny odpowiednik akcji getCharacteristicsChart. Opcjonalnie możesz dodać do 10 konkurentów. Wyniki są paginowane po kubełkach — dla words_count łączny count wynosi 10.

Podgląd · 6 z 8 kolumn

Kubełek (liczba słów)	Liczba fraz	TOP3	TOP10	TOP50	Suma widoczności
1	7475	1092	2911	7475	2 006 144,934
2	77199	14 111	31 618	77 199	2 037 763,913

zalando.pl (characteristics: words_count, limit: 2) — rozkład fraz wg liczby słów. Wszystkie adresowalne pola wiersza (count zwracane jest jako string).

Żądanie

POST /api/visibility_analysis/reports/keywords/getCharacteristicsTable

Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


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

Rozszerzony

żądanie-rozszerzone.jsonc


{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "characteristics": "words_count",
  "competitors": ["allegro.pl", "modivo.pl"],
  "page": 1,
  "limit": 2
}

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/keywords/getCharacteristicsTable' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{
    "domain": "zalando.pl",
    "fetch_mode": "topLevelDomain",
    "country_id": 1,
    "characteristics": "words_count",
    "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
`country_id`	`number` Wymagane. Id kraju (bazy danych). Polska = `1`. Nieznana wartość → `418` z komunikatem `Unknown country_id`.
`characteristics`	`"words_count" \| "trends" \| "searches" \| "difficulty" \| "keyword_params" \| "serp_params"` Wymagane. Cecha fraz, według której budowany jest rozkład (walidator `inList`).
`competitors`	`string[]` Tablica maks. 10 domen konkurentów do porównania.
`page`	`number` Numer strony. Paginacja odbywa się po kubełkach (dla `words_count` łącznie 10 wierszy).	`1`
`limit`	`number` Liczba wierszy (kubełków) na stronę.	`10`

Cztery parametry są wymagane: domain, fetch_mode, country_id oraz characteristics. To endpoint POST z ciałem JSON (Content-Type: application/json). Nieznane country_id zwraca 418 z komunikatem Unknown country_id. Uwaga: pole count w wierszach odpowiedzi jest zwracane jako string, a nie liczba.

Odpowiedź

W przypadku powodzenia otrzymujesz data (tablicę wierszy — po jednym na kubełek cechy) oraz pagination. Każdy wiersz zawiera wartość kubełka key (np. liczbę słów we frazie), liczbę fraz count (zwracaną jako string), liczbę fraz w TOP3/TOP10/TOP50 oraz statystyki widoczności: visibility_sum (suma widoczności fraz w kubełku), visibility_domain (łączna widoczność domeny) i visibility_percent (procentowy udział pozycji TOP w kubełku).

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "key": 1, "count": "7475", "top3": 1092, "top10": 2911, "top50": 7475, "visibility_percent": 37.29 /* … */ }
  ],
  "pagination": { "page_count": 5, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 10, "limit": 2 }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`CharacteristicsRow[]` Wiersze tabeli — po jednym na kubełek cechy
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }` Metadane paginacji (paginacja po kubełkach)

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 lub nieznane country_id → odpowiedź invalid_data (dla nieznanego kraju komunikat Unknown country_id). Wartość characteristics spoza listy words_count | trends | searches | difficulty | keyword_params | serp_params jest odrzucana przez walidator inList.

Powiązane akcje

getCharacteristicsTable — rozkład fraz według cechy w formie tabeli z paginacją (ta strona)
getCharacteristicsChart — ten sam rozkład jako serie wykresu (bez paginacji, z etykietą osi Y)
W kontrolerze domain_keywords istnieją przestarzałe (deprecated) aliasy tych akcji — używaj ścieżek z kontrolera keywords.

Cechy fraz: tabela (getCharacteristicsTable)