---
title: "Baza słów kluczowych: histogramy zbioru (`getStatistics`)"
source: https://docs.senuto.com/modules/keywords_analysis/ka-keywords-getStatistics
api: POST /api/keywords_analysis/reports/keywords/getStatistics
---

# Baza słów kluczowych: histogramy zbioru (`getStatistics`)

**`POST /api/keywords_analysis/reports/keywords/getStatistics`**

Zwraca **rozkłady (histogramy) dla całego zbioru fraz** pasujących do zapytania — w trzech wymiarach: liczby wyszukiwań, trudności frazy i kosztu kliknięcia. Każdy wymiar to lista kubełków `{ start, end, value }`, gdzie `value` to liczba fraz w kubełku. Służy do oceny, jak wygląda cały zbiór, przed pobraniem pojedynczych wierszy przez [`getKeywords`](/modules/keywords_analysis/ka-keywords-getKeywords).

---

## Żądanie

`POST` `/api/keywords_analysis/reports/keywords/getStatistics`

Nagłówki: `Authorization: Bearer <token>`, `Content-Type: application/json`.
Parametry przekazuje się w **treści żądania**.

**Żądanie**

```jsonc filename="żądanie.jsonc"
{
  "parameters": [
    {
      "data_fetch_mode": "keyword",
      "value": [
        "buty do biegania"
      ]
    }
  ],
  "match_mode": "wide",
  "country_id": 1
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/keywords_analysis/reports/keywords/getStatistics' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"parameters": [{"data_fetch_mode": "keyword", "value": ["buty do biegania"]}], "match_mode": "wide", "country_id": 1}'
```

### Parametry

```ts
type KeywordsGetStatisticsRequest = {
/**
 * **Wymagane**. Zapytanie do bazy: lista obiektów `{ data_fetch_mode, value }`.
 * Tryb `keyword` przyjmuje listę fraz w `value`.
 */
parameters: Array<{ data_fetch_mode: 'keyword' | string; value: string[] }>;
/** **Wymagane**. Szerokość dopasowania frazy: `wide` | `medium` | `narrow`. */
match_mode: 'wide' | 'medium' | 'narrow';
/** **Wymagane**. Identyfikator kraju; nieznana wartość zwraca `418` z `Unknown country_id`. */
country_id: number;
/** Filtry — tablica grup łączonych OR. Nieznany `key` zwraca `418` z `invalid_filtering`. */
filtering?: Array<{
  filters: Array<{ key: string; match?: 'gt' | 'gte' | 'lt' | 'lte' | 'eq'; value: string | number | Array<string | number> }>;
  conjunction?: 'and' | 'or';
}>;
}
export default KeywordsGetStatisticsRequest
```

> **Ostrzeżenie:**
> Pole **`end` ostatniego kubełka to string `"*"`**, nie liczba — oznacza „bez górnej granicy". Parser oczekujący liczby wywróci się na ostatnim elemencie każdego histogramu.

> **Ostrzeżenie:**
> Wywołanie **zużywa jednostkę** dziennego limitu `keywords_analysis_queries_per_day`. Ta sama para `parameters` + `match_mode` policzona ponownie zużywa kolejną jednostkę.

> **Ostrzeżenie:**
> **`match_mode` jest wymagane** i przyjmuje wyłącznie `wide`, `medium` albo `narrow` — inna wartość zwraca `418`.

## Odpowiedź

Przykład to **rzeczywista odpowiedź produkcyjna**, skrócona.

```json filename="przykładowa-odpowiedź"
{
  "success": true,
  "data": {
    "searches": [
      {
        "start": 0,
        "end": 0,
        "value": 90
      },
      {
        "start": 10,
        "end": 10,
        "value": 1120
      },
      {
        "start": 20,
        "end": 20,
        "value": 305
      },
      {
        "start": 3600,
        "end": "*",
        "value": 9
      }
    ],
    "difficulty": [
      {
        "start": 1,
        "end": 10,
        "value": 0
      },
      {
        "start": 11,
        "end": 20,
        "value": 0
      }
    ],
    "cpc": [
      {
        "start": 0,
        "end": 0.49,
        "value": 1376
      },
      {
        "start": 0.5,
        "end": 0.99,
        "value": 669
      }
    ]
  }
}
```

### Struktura odpowiedzi

```ts
type KeywordsGetStatisticsResponse = {
success: boolean;
/** Trzy histogramy; każdy to lista kubełków. */
data: {
  /** Rozkład liczby wyszukiwań. */
  searches: Array<{ start: number; end: number | '*'; value: number }>;
  /** Rozkład trudności frazy (skala 1–100). */
  difficulty: Array<{ start: number; end: number | '*'; value: number }>;
  /** Rozkład kosztu kliknięcia. */
  cpc: Array<{ start: number; end: number | '*'; value: number }>;
};
}
export default KeywordsGetStatisticsResponse
```

## Błędy

Błędy tego endpointu przychodzą we [wspólnej kopercie ze statusem `418`](/types/errors).

## Powiązane akcje

- [`getKeywords`](/modules/keywords_analysis/ka-keywords-getKeywords) — pojedyncze frazy z metrykami.
- [`getGroups`](/modules/keywords_analysis/ka-keywords-getGroups) — ten sam zbiór pogrupowany tematycznie.
- [`getResultsStatistics`](/modules/keywords_analysis/ka-keywords-getResultsStatistics) — sumaryczne statystyki zbioru.