---
title: "Cechy fraz: wykres (`getCharacteristicsChart`)"
source: https://docs.senuto.com/modules/visibility_analysis/va-keywords-getCharacteristicsChart
api: GET /api/visibility_analysis/reports/keywords/getCharacteristicsChart
---

# Cechy fraz: wykres (`getCharacteristicsChart`)

**`GET /api/visibility_analysis/reports/keywords/getCharacteristicsChart`**

Zwraca dane do wykresu rozkładu fraz domeny według wybranej cechy (`characteristics`) — np. liczby słów we frazie, trendów, liczby wyszukiwań, trudności, parametrów frazy lub parametrów SERP. Wynik to tablica serii (po jednej na domenę): każda seria zawiera etykietę osi Y oraz mapę kubełek → liczba fraz. Opcjonalnie możesz dodać do 10 konkurentów, aby porównać rozkłady na tym samym wykresie.

**Rozkład fraz wg długości (characteristics: words_count)**

| Wartość | fraz |
| --- | --- |
| 1 | 7475 |
| 2 | 77199 |
| 3 | 119515 |
| 4 | 62457 |
| 5 | 17151 |
| 6 | 3838 |
| 7 | 981 |
| 8 | 326 |
| 9 | 121 |
| 10 | 51 |

_zalando.pl. Kubełek = liczba słów we frazie, wartość = liczba fraz o tej długości. Inne wartości `characteristics` dają inne kubełki._

---

## Żądanie

`GET` `/api/visibility_analysis/reports/keywords/getCharacteristicsChart`

Nagłówki: `Authorization: Bearer <token>`. Parametry przekazywane w query stringu.

### Struktura żądania

**Podstawowy**

```text filename="query-string.txt"
/api/visibility_analysis/reports/keywords/getCharacteristicsChart
  ?domain=zalando.pl
  &fetch_mode=topLevelDomain
  &country_id=1
  &characteristics=words_count
```

**cURL**

```bash
curl --location --request GET 'https://api.senuto.com/api/visibility_analysis/reports/keywords/getCharacteristicsChart?domain=zalando.pl&fetch_mode=topLevelDomain&country_id=1&characteristics=words_count' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE'
```

### Parametry

```ts
type KeywordsGetCharacteristicsChartRequest = {
/**
 * **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 na tym samym wykresie.
 * W query stringu przekazywana jako JSON, np. `competitors=["allegro.pl","modivo.pl"]`.
 */
competitors?: string[];
}
export default KeywordsGetCharacteristicsChartRequest
```

> **Ostrzeżenie:**
> Cztery parametry są **wymagane**: **`domain`**, **`fetch_mode`**, **`country_id`** oraz **`characteristics`**. To endpoint **GET** — parametry przekazujesz w query stringu, a `competitors` (tablicę) serializujesz jako JSON. Nieznane `country_id` zwraca `418` z komunikatem `Unknown country_id`; `characteristics` spoza dozwolonej listy jest odrzucane przez walidator (`inList`).

## Odpowiedź

W przypadku powodzenia otrzymujesz `data` — tablicę serii, po jednej na każdą domenę (analizowaną i ewentualnych konkurentów). Każda seria zawiera `domain`, etykietę osi Y `label_y` (zwracaną **po angielsku**, np. `"Number of keywords"`), flagę `is_main` (czy to domena główna z żądania) oraz obiekt `data` z mapą kubełek → liczba fraz pod kluczem równym wybranej wartości `characteristics`. Endpoint nie zwraca paginacji.

**Skrócona**

```json filename="przykładowa-odpowiedź (skrócona)"
{
  "success": true,
  "data": [
    { "domain": "zalando.pl", "label_y": "Number of keywords", "is_main": true, "data": { "words_count": { "1": 7475, "2": 77199 /* … */ } } }
  ]
}
```

**Pełna**

```json filename="przykładowa-odpowiedź (200)"
{
  "success": true,
  "data": [
    {
      "domain": "zalando.pl",
      "label_y": "Number of keywords",
      "is_main": true,
      "data": {
        "words_count": {
          "1": 7475,
          "2": 77199,
          "3": 119515,
          "4": 62457,
          "5": 17151,
          "6": 3838,
          "7": 981,
          "8": 326,
          "9": 121,
          "10": 51
        }
      }
    }
  ]
}
```

### Struktura odpowiedzi

```ts
type KeywordsCharacteristicsChartResponse = {
/** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */
success: boolean;
/** Serie wykresu — po jednej na domenę (główna + ewentualni konkurenci) */
data: CharacteristicsSeries[];
}

type CharacteristicsSeries = {
/** Domena, której dotyczy seria */
domain: string;
/** Etykieta osi Y — zwracana po angielsku, np. "Number of keywords" */
label_y: string;
/** Czy to domena główna z żądania (false dla konkurentów) */
is_main: boolean;
/**
 * Dane serii pod kluczem równym wybranej wartości `characteristics`
 * (np. `words_count`) — mapa kubełek → liczba fraz.
 * Dla `words_count` kubełki to liczby słów "1".."10".
 */
data: Record<string, Record<string, number>>;
}
export default KeywordsCharacteristicsChartResponse
```

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

- `getCharacteristicsChart` — rozkład fraz według cechy jako serie wykresu (ta strona)
- `getCharacteristicsTable` — ten sam rozkład w formie tabelarycznej z paginacją i statystykami TOP3/TOP10/TOP50 oraz widocznością
- W kontrolerze `domain_keywords` istnieją **przestarzałe (deprecated) aliasy** tych akcji — używaj ścieżek z kontrolera `keywords`.