--- title: "Baza słów kluczowych: wyszukiwarka (`getKeywords`)" source: https://docs.senuto.com/modules/keywords_analysis/ka-keywords-getKeywords api: POST /api/keywords_analysis/reports/keywords/getKeywords --- # Baza słów kluczowych: wyszukiwarka (`getKeywords`) **`POST /api/keywords_analysis/reports/keywords/getKeywords`** Przykładowe żądanie: ```json { "parameters": [ { "data_fetch_mode": "keyword", "value": [ "buty do biegania" ] } ], "match_mode": "wide", "country_id": 1, "limit": 10 } ``` Przykładowe żądanie (rozszerzone): ```json { "parameters": [ { "data_fetch_mode": "keyword", "value": [ "buty do biegania", "nike" ] } ], "match_mode": "medium", "country_id": 1, "filtering": [ { "filters": [ { "key": "searches", "match": "gte", "value": 100000 } ], "conjunction": "and" } ], "order": { "prop": "searches", "dir": "ASC" }, "limit": 20, "page": 1 } ``` Przykładowa odpowiedź: ```json { "success": true, "data": [ { "keyword": "nike airmax", "kid": "c9db40a54eacd9ab571c31b82d0b1ac5", "added": "2021-10-19", "searches": 135000, "cpc": 0.67, "cpc_min": 0.23, "cpc_max": 1.1, "words_count": 2, "variations": [], "variations_number": 0, "snippets": [ "image_thumbs", "pla", "top_bar" ], "trends": [ 90500, 110000, 201000, 165000, 135000, 110000, 110000, 135000, 135000, 110000, 90500, 74000 ] } ], "pagination": { "page_count": 4471, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 8941, "limit": 2 } } ``` Główna **wyszukiwarka bazy słów kluczowych** (Keyword Explorer): zwraca frazy pasujące do zapytania (`parameters`) wraz z metrykami — liczbą wyszukiwań, CPC (min/średnie/max), liczbą słów, trendem 12‑miesięcznym, cechami SERP (`snippets`) i wariacjami frazy. Zapytanie budujesz z jednej lub wielu grup `parameters` (fraza / URL / domena / katalog) oraz trybu dopasowania `match_mode`. | Fraza | KID | Wyszukiwania/mies. | CPC | CPC min | CPC max | Liczba słów | Wariacje | Trend (12 mies.) | Snippety SERP | Dodano | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | nike airmax | c9db40a54eacd9ab571c31b82d0b1ac5 | 135000 | 0.67 | 0.23 | 1.1 | 2 | 0 | [90500,110000,201000,165000,135000,110000,110000,135000,135000,110000,90500,74000] | ["image_thumbs","pla","top_bar"] | 2021-10-19 | | nike air maxes | dda94a2fbd99088b392c017ef4430e4d | 135000 | 0.67 | 0.23 | 1.1 | 3 | 0 | [90500,110000,201000,165000,135000,110000,110000,135000,135000,110000,90500,74000] | ["adwords","image_thumbs","map","pla","top_bar","yellow_pages"] | 2022-08-01 | _parameters keyword „buty do biegania”, match_mode wide, country_id 1. Pominięto zdublowane pola: trend_1..12 (= tablica trends) oraz obiekt statistics (= pola top-level)._ > **Ostrzeżenie:** > Uruchomienie zużywa jednostkę dziennego limitu zapytań Bazy słów kluczowych (`keywords_analysis_queries_per_day`) — patrz [Limity zapytań](/rate-limits). Przeglądanie kolejnych stron już pobranego wyniku nie zużywa kolejnej jednostki. --- ## Żądanie `POST` `/api/keywords_analysis/reports/keywords/getKeywords` ```jsonc filename="żądanie.jsonc" { "parameters": [ { "data_fetch_mode": "keyword", "value": ["buty do biegania"] } ], "match_mode": "wide", "country_id": 1, "limit": 10, "page": 1 } ``` ### Parametry ```ts type KeywordsGetKeywordsRequest = { /** * **Wymagane** (niepusta tablica). Grupy zapytania — każda określa źródło i wartości. */ parameters: Array<{ /** **Wymagane**. Typ źródła: `keyword` | `url` | `domain` | `catalog`. */ data_fetch_mode: 'keyword' | 'url' | 'domain' | 'catalog'; /** **Wymagane** (niepusta tablica). Wartości do dopasowania (frazy/URL-e/domeny). */ value: string[]; }>; /** **Wymagane**. Tryb dopasowania: `wide` | `medium` | `narrow`. */ match_mode: 'wide' | 'medium' | 'narrow'; /** ID kraju (bazy słów), np. `1` (PL 1.0), `200` (PL 2.0). */ country_id?: number; /** * Filtrowanie wyników. Tablica grup — grupy łączone są operatorem OR. * Nieznany `key` zwraca błąd `invalid_filtering` (HTTP 418). Patrz sekcja „Filtrowanie i sortowanie". */ filtering?: Array<{ /** Warunki w grupie. */ filters: Array<{ /** Pole do filtrowania, np. `searches` | `cpc` | `words_count` | `added` | `snippets`. */ key: string; /** Operator porównania (pola liczbowe/daty): `gt` | `gte` | `lt` | `lte` | `eq`. @default eq */ match?: 'gt' | 'gte' | 'lt' | 'lte' | 'eq'; /** Wartość (lub tablica wartości dla filtrów wielowartościowych). */ value: string | number | Array; /** `false` = negacja warunku (wyklucz pasujące). @default true */ complement?: boolean; }>; /** Łączenie warunków w grupie: `and` | `or`. @default and */ conjunction?: 'and' | 'or'; }>; /** * Sortowanie. **Uwaga:** wymagana forma `{ prop, dir }` — inne formy są ignorowane * (wpada domyślne `searches`/`DESC`). */ order?: { /** Pole: `searches` | `cpc` | `cpc_min` | `cpc_max` | `words_count` | `difficulty` | `keyword` | `added` | `trend_1`…`trend_12`. */ prop: string; /** Kierunek: `ASC` | `DESC`. @default DESC */ dir: 'ASC' | 'DESC'; }; /** Liczba wierszy na stronę. @default 10 */ limit?: number; /** Numer strony. @default 1 */ page?: number; } export default KeywordsGetKeywordsRequest ``` ## Filtrowanie i sortowanie Wyniki możesz zawężać opcjonalnym polem `filtering` oraz porządkować polem `order`. Oba są niezależne od `parameters`/`match_mode` (te definiują _co_ przeszukujemy; `filtering`/`order` — _jak zawężamy i porządkujemy_ wynik). Ogólny opis mechanizmu: [Filtrowanie (`filtering`)](/types/filter). ```jsonc filename="filtering + order.jsonc" { "parameters": [{ "data_fetch_mode": "keyword", "value": ["buty do biegania"] }], "match_mode": "wide", "country_id": 1, "filtering": [ { "filters": [ { "key": "searches", "match": "gte", "value": 100000 } ], "conjunction": "and" } ], "order": { "prop": "searches", "dir": "ASC" } } ``` **Filtry** (`filtering[].filters[]`) — dozwolone `key` (nieznany klucz → błąd `invalid_filtering`, HTTP 418): | `key` | Typ / operatory `match` | | -------------------------------------------------------------------------------------- | -------------------------------------- | | `searches`, `words_count` | liczbowy: `gt` `gte` `lt` `lte` `eq` | | `cpc` | walutowy: `gt` `gte` `lt` `lte` `eq` | | `added` | data: `gt` `gte` `lt` `lte` `eq` | | `snippets` | cechy SERP (tablica wartości) | | `speech_parts` | części mowy (tablica wartości) | | `trends_peaks` | szczyty trendu | | `domains`, `group`, `keywords` | dopasowanie tekstowe/wielowartościowe | | `statistics.cpc.current`, `statistics.searches.current`, `statistics.snippets.current` | aliasy pól `cpc`/`searches`/`snippets` | Grupy w `filtering` łączone są operatorem **OR**, a warunki wewnątrz grupy — polem `conjunction` (`and`/`or`, domyślnie `and`). `complement: false` neguje warunek (wyklucza pasujące wiersze). **Sortowanie** (`order`) — **wyłącznie** w formie `{ "prop": , "dir": "ASC" | "DESC" }`. Inne formy (np. `{ "searches": "ASC" }`) są ignorowane i wpada domyślne `searches`/`DESC`. Pola: `searches`, `cpc`, `cpc_min`, `cpc_max`, `words_count`, `difficulty`, `keyword`, `added`, `trend_1`…`trend_12`. > **Ostrzeżenie:** > Nieznany `key` w `filtering` zwraca `success: false` z `error.type = "invalid_filtering"` i statusem **HTTP 418** (nie 400) — jak wszystkie błędy walidacyjne tego API, patrz [Błędy](/types/errors). ## Odpowiedź `data` to lista fraz; `pagination` jak w innych raportach. ```ts type KeywordsGetKeywordsResponse = { success: boolean; data: Array<{ keyword: string; kid: string; /** Data dodania frazy do bazy (RRRR-MM-DD) */ added: string; /** Średnia miesięczna liczba wyszukiwań */ searches: number; cpc: number; cpc_min: number; cpc_max: number; words_count: number; /** Wariacje frazy i ich liczba */ variations: string[]; variations_number: number; /** Cechy SERP */ snippets: string[]; /** Trend 12‑miesięczny (tablica) */ trends: number[]; /** DUPLIKATY: trend_1..trend_12 (= elementy trends[]) oraz `statistics{}` (= pola top-level) */ trend_1?: number; /* … trend_12 */ statistics?: unknown; }>; pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number }; } export default KeywordsGetKeywordsResponse ``` ## Błędy Błędy tego endpointu przychodzą we [wspólnej kopercie ze statusem `418`](/types/errors). ## Powiązane akcje - `keywords/getRelated` — frazy powiązane. - `keywords/getQuestions` — frazy pytające. - `keyword_details/getStatistics` — szczegółowe statystyki pojedynczej frazy.