---
title: "Cechy fraz: tabela (`getCharacteristicsTable`)"
source: https://docs.senuto.com/modules/visibility_analysis/va-keywords-getCharacteristicsTable
api: POST /api/visibility_analysis/reports/keywords/getCharacteristicsTable
---

# 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.

| Kubełek (liczba słów) | Liczba fraz | TOP3 | TOP10 | TOP50 | Suma widoczności | Widoczność domeny | Udział widoczności (%) |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 7475 | 1092 | 2911 | 7475 | 2006144.9339999994 | 5380498.401999987 | 37.29 |
| 2 | 77199 | 14111 | 31618 | 77199 | 2037763.912999993 | 5380498.401999987 | 37.87 |

_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**

```jsonc filename="żądanie-podstawowe.jsonc"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1,
  "characteristics": "words_count"
}
```

**Rozszerzony**

```jsonc filename="żą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**

```bash
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

```ts
type KeywordsGetCharacteristicsTableRequest = {
/**
 * **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
 */
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**. Cecha fraz, według której budowany jest rozkład (walidator `inList`).
 */
characteristics: 'words_count' | 'trends' | 'searches' | 'difficulty' | 'keyword_params' | 'serp_params';
/**
 * Tablica maks. **10** domen konkurentów do porównania.
 */
competitors?: string[];
/**
 * Numer strony. Paginacja odbywa się po kubełkach (dla `words_count` łącznie 10 wierszy).
 * @default 1
 */
page?: number;
/**
 * Liczba wierszy (kubełków) na stronę.
 * @default 10
 */
limit?: number;
}
export default KeywordsGetCharacteristicsTableRequest
```

> **Ostrzeżenie:**
> 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**

```json filename="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 }
}
```

**Pełna**

```json filename="przykładowa-odpowiedź (200)"
{
  "success": true,
  "data": [
    {
      "top3": 1092,
      "top10": 2911,
      "count": "7475",
      "visibility_sum": 2006144.9339999994,
      "key": 1,
      "top50": 7475,
      "visibility_domain": 5380498.401999987,
      "visibility_percent": 37.29
    },
    {
      "top3": 14111,
      "top10": 31618,
      "count": "77199",
      "visibility_sum": 2037763.912999993,
      "key": 2,
      "top50": 77199,
      "visibility_domain": 5380498.401999987,
      "visibility_percent": 37.87
    }
  ],
  "pagination": { "page_count": 5, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 10, "limit": 2 }
}
```

### Struktura odpowiedzi

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

type CharacteristicsRow = {
/** Wartość kubełka — np. liczba słów we frazie dla `words_count` */
key: number;
/** Liczba fraz w kubełku — uwaga: zwracana jako string */
count: string;
/** Liczba fraz w TOP3 */
top3: number;
/** Liczba fraz w TOP10 */
top10: number;
/** Liczba fraz w TOP50 */
top50: number;
/** Suma widoczności fraz w kubełku */
visibility_sum: number;
/** Łączna widoczność domeny (taka sama we wszystkich wierszach) */
visibility_domain: number;
/** Procentowy udział pozycji TOP w kubełku */
visibility_percent: number;
}
export default KeywordsCharacteristicsTableResponse
```

## 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<string, Record<string, string>>;
  };
};
}
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 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`.