---
title: "Szczegóły frazy: propozycje fraz (`getKeywordsPropositions`)"
source: https://docs.senuto.com/modules/keywords_analysis/ka-keyword-details-getKeywordsPropositions
api: POST /api/keywords_analysis/reports/keyword_details/getKeywordsPropositions
---

# Szczegóły frazy: propozycje fraz (`getKeywordsPropositions`)

**`POST /api/keywords_analysis/reports/keyword_details/getKeywordsPropositions`**

Zwraca **propozycje fraz pokrewnych** do podanej — rozszerzenia i warianty do rozważenia przy budowie listy słów kluczowych. Kształt wiersza jest identyczny jak w pytaniach.

Raport odpytujesz **wprost frazą i krajem** — bez wcześniejszego tworzenia zadania w Analizie
SERP. Jedno żądanie zastępuje ścieżkę „utwórz zadanie → sprawdź status → pobierz wynik"
i nie zużywa limitu zadań.

Dla frazy `hamak` w Polsce raport zwrócił **5848** wierszy.

---

## Żądanie

`POST` `/api/keywords_analysis/reports/keyword_details/getKeywordsPropositions`

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

**Żądanie**

```jsonc filename="żądanie.jsonc"
{
  "keyword": "hamak",
  "country_id": 1,
  "limit": 10
}
```

**cURL**

```bash
curl --location --request POST 'https://api.senuto.com/api/keywords_analysis/reports/keyword_details/getKeywordsPropositions' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"keyword":"hamak","country_id":1,"limit":10}'
```

### Parametry

```ts
type KeywordDetailsGetKeywordsPropositionsRequest = {
/** **Wymagane**. Fraza kluczowa, dla której pobierany jest raport. Pusty string zwraca `418`. */
keyword: string;
/**
 * **Wymagane**. Identyfikator kraju; musi istnieć w słowniku krajów — nieznana wartość zwraca
 * `418` z komunikatem `Unknown country_id`. Uwaga: `200` jest tu mapowane na `1`.
 * @default 1
 */
country_id: number;
/**
 * Filtry raportu — tablica grup łączonych operatorem OR. **Działa na tej akcji.**
 * Nieznany `key` zwraca `418` z `invalid_filtering`. Opis mechanizmu: /types/filter
 */
filtering?: Array<{
  filters: Array<{ key: string; match?: 'gt' | 'gte' | 'lt' | 'lte' | 'eq'; value: string | number | Array<string | number> }>;
  conjunction?: 'and' | 'or';
}>;
/** Numer strony wyników. */
page?: number;
/** Liczba wierszy na stronę. */
limit?: number;
}
export default KeywordDetailsGetKeywordsPropositionsRequest
```

> **Ostrzeżenie:**
> Zarówno **`keyword`**, jak i **`country_id`** są **wymagane**. Nieznane `country_id` zwraca `418` z `Unknown country_id`, a wartość **`200` jest mapowana na `1`** — dla Polski trafisz więc do bazy 1.0, nie 2.0.

> **Ostrzeżenie:**
> Metryki są **zdublowane w trzech miejscach**: pola najwyższego poziomu (`searches`, `cpc`, `trends`), płaskie `trend_1` … `trend_12` oraz obiekt `statistics`. Do integracji wybierz jedno źródło — `statistics` różni się tylko tym, że jego lista cech SERP jest bez duplikatów.

## Odpowiedź

Przykład poniżej to **rzeczywista odpowiedź produkcyjna** dla frazy `hamak` (`country_id: 1`),
skrócona do jednego wiersza.

```json filename="przykładowa-odpowiedź"
{
  "success": true,
  "data": [
    {
      "searches": 74000,
      "cpc": 0.79,
      "cpc_min": 0.28,
      "cpc_max": 1.31,
      "words_count": 2,
      "trend_1": 135000,
      "trend_2": 90500,
      "trend_3": 60500,
      "trend_4": 22200,
      "trend_5": 12100,
      "trend_6": 9900,
      "trend_7": 8100,
      "trend_8": 12100,
      "trend_9": 27100,
      "trend_10": 110000,
      "trend_11": 135000,
      "trend_12": 201000,
      "added": "2021-06-22",
      "keyword": "huśtawka ogrodowa",
      "kid": "9c40f1c0405fe5ea7f00bdf8ec639a2f",
      "variations": [
        "hustawka ogrodowa",
        "ogrodowa huśtawka"
      ],
      "variations_number": 2,
      "snippets": [
        "adwords",
        "image_thumbs",
        "map",
        "pla",
        "top_bar",
        "yellow_pages"
      ],
      "trends": [
        135000,
        90500,
        60500,
        22200,
        12100,
        9900,
        8100,
        12100,
        27100,
        110000,
        135000,
        201000
      ],
      "statistics": {
        "snippets": {
          "current": [
            "adwords",
            "image_thumbs",
            "map",
            "pla",
            "top_bar",
            "yellow_pages"
          ]
        },
        "searches": {
          "current": 74000
        },
        "cpc": {
          "current": 0.79
        },
        "cpc_min": {
          "current": 0.28
        },
        "cpc_max": {
          "current": 1.31
        },
        "trends": {
          "history": [
            135000,
            90500,
            60500,
            22200,
            12100,
            9900,
            8100,
            12100,
            27100,
            110000,
            135000,
            201000
          ]
        }
      }
    }
  ],
  "pagination": {
    "page_count": 2924,
    "current_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "count": 5848,
    "limit": 2
  }
}
```

### Struktura odpowiedzi

```ts
type KeywordDetailsGetKeywordsPropositionsResponse = {
success: boolean;
data: Array<{
  keyword: string;
  /** Data dodania frazy do bazy, format `YYYY-MM-DD`. */
  added: string;
  /** Średnia miesięczna liczba wyszukiwań. */
  searches: number;
  cpc: number;
  cpc_min: number | null;
  cpc_max: number | null;
  words_count: number;
  /** Identyfikator frazy w bazie. */
  kid: string;
  /** Warianty zapisu tej samej frazy. */
  variations: string[];
  variations_number: number;
  /** Cechy SERP frazy. Lista może zawierać **powtórzenia** — odsiane w `statistics.snippets.current`. */
  snippets: string[];
  /** 12-elementowy trend wyszukiwań. */
  trends: number[];
  /** Miesięczne wartości trendu, pola `trend_1` … `trend_12`. Duplikują tablicę `trends`. */
  trend_1: number; trend_2: number; trend_3: number; trend_4: number;
  trend_5: number; trend_6: number; trend_7: number; trend_8: number;
  trend_9: number; trend_10: number; trend_11: number; trend_12: number;
  /**
   * Te same metryki co pola najwyższego poziomu, w formie zagnieżdżonej. Nic nowego nie wnosi
   * poza jednym: `statistics.snippets.current` jest listą **bez duplikatów**, podczas gdy
   * `snippets` może powtarzać te same wartości.
   */
  statistics: {
    snippets: { current: string[] };
    searches: { current: number };
    cpc: { current: number };
    cpc_min: { current: number } | [];
    cpc_max: { current: number } | [];
    trends: { history: number[] };
  };
}>;
/** Paginacja liczona z całego zbioru — `count` to liczba wszystkich wierszy. */
pagination: {
  page_count: number; current_page: number;
  has_next_page: boolean; has_prev_page: boolean;
  count: number; limit: number;
};
}
export default KeywordDetailsGetKeywordsPropositionsResponse
```

## Błędy

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

## Powiązane akcje

Wszystkie poniższe raporty przyjmują tę samą parę `keyword` + `country_id`:

- [`getStatistics`](/modules/keywords_analysis/ka-keyword-details-getStatistics) — zbiorcze statystyki frazy.
- [`getQuestions`](/modules/keywords_analysis/ka-keyword-details-getQuestions) — pytania o frazę.
- [`getRelatedKeywords`](/modules/keywords_analysis/ka-keyword-details-getRelatedKeywords) — frazy powiązane.
- [`getTopicLeaders`](/modules/keywords_analysis/ka-keyword-details-getTopicLeaders) — liderzy tematu.
- [`getGroups`](/modules/keywords_analysis/ka-keyword-details-getGroups) — grupy frazy.
- [`getCompetitorsNumber`](/modules/keywords_analysis/ka-keyword-details-getCompetitorsNumber) — liczba konkurentów.