Baza słów kluczowych: wyszukiwarka (`getKeywords`)

POST/api/keywords_analysis/reports/keywords/getKeywords

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.

Podgląd · 6 z 11 kolumn

Fraza	KID	Wyszukiwania/mies.	CPC	CPC min	CPC max
nike airmax	c9db40a54eacd9ab571c31b82d0b1ac5	135 000	0,67	0,23	1,1
nike air maxes	dda94a2fbd99088b392c017ef4430e4d	135 000	0,67	0,23	1,1

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

Uruchomienie zużywa jednostkę dziennego limitu zapytań Bazy słów kluczowych (keywords_analysis_queries_per_day) — patrz Limity zapytań. Przeglądanie kolejnych stron już pobranego wyniku nie zużywa kolejnej jednostki.

Żądanie

POST /api/keywords_analysis/reports/keywords/getKeywords

żądanie.jsonc


{
  "parameters": [
    { "data_fetch_mode": "keyword", "value": ["buty do biegania"] }
  ],
  "match_mode": "wide",
  "country_id": 1,
  "limit": 10,
  "page": 1
}

Parametry

Name	Type	Default
`parameters`	`{ data_fetch_mode: "keyword" \| "url" \| "domain" \| "catalog"; value: string[]; }[]` Wymagane (niepusta tablica). Grupy zapytania — każda określa źródło i wartości.
`match_mode`	`"wide" \| "medium" \| "narrow"` Wymagane. Tryb dopasowania: `wide` \| `medium` \| `narrow`.
`country_id`	`number` ID kraju (bazy słów), np. `1` (PL 1.0), `200` (PL 2.0).
`filtering`	`{ filters: { key: string; match?: "gt" \| "gte" \| "lt" \| "lte" \| "eq"; value: string \| number \| (string \| number)[]; complement?: boolean; }[]; conjunction?: "and" \| "or"; }[]` Filtrowanie wyników. Tablica grup — grupy łączone są operatorem OR. Nieznany `key` zwraca błąd `invalid_filtering` (HTTP 418). Patrz sekcja „Filtrowanie i sortowanie”.
`order`	`{ prop: string; dir: "ASC" \| "DESC"; }` Sortowanie. Uwaga: wymagana forma `{ prop, dir }` — inne formy są ignorowane (wpada domyślne `searches`/`DESC`).
`limit`	`number` Liczba wierszy na stronę.	`10`
`page`	`number` Numer strony.	`1`

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

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": <pole>, "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.

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.

Odpowiedź

data to lista fraz; pagination jak w innych raportach.

Name	Type	Default
`success`	`boolean`
`data`	`{ keyword: string; kid: string; added: string; searches: number; cpc: number; cpc_min: number; cpc_max: number; words_count: number; variations: string[]; variations_number: number; snippets: string[]; trends: number[]; trend_1?: number; statistics?: unknown; }[]`
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }`

Błędy

Błędy tego endpointu przychodzą we wspólnej kopercie ze statusem 418.

Powiązane akcje

keywords/getRelated — frazy powiązane.
keywords/getQuestions — frazy pytające.
keyword_details/getStatistics — szczegółowe statystyki pojedynczej frazy.

Baza słów kluczowych: wyszukiwarka (getKeywords)