# Seznam.cz Keyword Planner – Search Volume (Hledanost) via Sklik (`budoucnost-ai/seznam-keyword-planner`) Actor

Keyword ideas and Seznam.cz search volume (hledanost) from the official Sklik API: monthly searches for 12 months, CPC in CZK, trend and peak month. Bulk stats for 10,000 keywords, optional Google + Seznam autocomplete expansion. Use your free Sklik token or ours. MCP-ready.

- **URL**: https://apify.com/budoucnost-ai/seznam-keyword-planner.md
- **Developed by:** [Budoucnost AI](https://apify.com/budoucnost-ai) (community)
- **Features:** Limited permissions, Single-tenant, Server interface
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 keyword (your own sklik token)s

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Seznam.cz Keyword Planner – Search Volume (Hledanost) via Sklik

Get **keyword ideas and Seznam.cz search volume (hledanost na Seznam.cz)** for the Czech market – straight from the official **Sklik API** (Seznam's ad platform), the same data you see in the Sklik keyword planner. Every row has the average monthly searches on Seznam.cz, **CPC in CZK**, a **12-month search history**, a simple **trend** (rising / falling / stable) and the **peak month**.

Google Keyword Planner tells you nothing about Seznam, which still handles a large share of Czech searches. This Actor fills that gap, in bulk, without clicking through the Sklik UI.

- **Three modes**: keyword ideas from seeds, exact search volume for your own list of up to 10,000 keywords (100 per API call), or **keywords generated from a web page** by AI (Claude by default – no key needed – or Gemini / OpenAI with your key).
- **Match types** like in Sklik: broad, "phrase", \[exact] – paste Sklik syntax and it just works.
- **URL → keywords**: the AI reads your page and lists what customers search on Google/Seznam (and what they ask ChatGPT, Gemini or Claude), grouped by intent; optional autocomplete reality check and Seznam volumes.
- **Autocomplete add-on**: also collect what Google (cs/CZ) and Seznam suggest while typing your seed (optionally `seed a` … `seed z`) and get Seznam volumes for those long-tail phrases too.
- **Bring your own free Sklik token** (cheaper) **or use ours** (nothing to set up).
- **Shared monthly cache**: Sklik data changes once a month, so repeated keywords come back instantly (`fromCache: true`).
- **Negative keywords** (client-side, before charging) and **sorting by value** (CPC × volume) so the most valuable keywords come first.
- Dedupe across seeds and sources, `minSearchVolume` filter before charging, clean JSON, MCP-ready for AI agents.

### Use cases

- **SEO for the Czech market** – find what people actually search on Seznam.cz and how much.
- **PPC / Sklik campaign planning** – volumes and CPC estimates for keyword lists before you build campaigns.
- **Content planning** – long-tail phrases from Google and Seznam autocomplete with real volumes; seasonality from the 12-month series and `peakMonth`.
- **Market research** – compare brand and category demand (e.g. `bramac` vs `střešní taška`), track trends month to month.
- **AI agents** – an agent can call the Actor with a keyword list and get structured volumes back.

### Input

| Field | Type | Description |
|---|---|---|
| `mode` | `ideas` | `stats` | `ideas` = suggestions for each seed; `stats` = volume for your exact keywords. Default `ideas`. |
| `seeds` | string\[] | Seed keywords for mode ideas (e.g. `elektrokolo`). |
| `keywords` | string\[] | Keywords for mode stats (up to 10,000). |
| `maxIdeasPerSeed` | integer | Ideas requested from Sklik per seed (1–10,000, default 20). |
| `related` | boolean | Include related keywords that do not contain the seed. |
| `orderBy` | `avgSearchCount` | `cpc` | `score` | `keyword` | Which ideas come first. |
| `minSearchVolume` | integer | Drop rows below this monthly volume – dropped rows are not charged. |
| `expandWithAutocomplete` | boolean | Add-on: Google + Seznam autocomplete phrases for each seed, with Seznam volumes. |
| `autocompleteAlphabet` | boolean | With the add-on, also query `seed a` … `seed z`. |
| `sklikApiToken` | secret string | Your own Sklik API token (optional, cheaper rows). |
| `maxItems` | integer | Cap on saved (charged) rows. |
| `useSharedCache`, `cacheDays` | boolean, integer | Shared monthly cache switch and max age (default on, 30 days). |
| `negativeKeywords` | string\[] | Drop ideas/phrases containing these – see below. Dropped rows are free. |
| `sortBy`, `sortDirection` | `value` | `volume` | `cpc` | `keyword` | `trend`, `asc` | `desc` | Dataset order. Default `value` desc. |
| `matchType` | `broad` | `phrase` | `exact` | Mode ideas: Sklik match type (see below). Default `broad`. |
| `expandEverySeed` | boolean | Seeds run shortest first; off = skip a seed already returned by an earlier seed. Default on. |
| `startUrls` | URL\[] | Mode url: pages to generate keywords from (max 50). |
| `llmProvider` | `claude` | `gemini` | `openai` | Mode url: AI provider. Default `claude`. |
| `anthropicApiKey`, `geminiApiKey`, `openaiApiKey` | secret string | Your own key for the chosen provider. Claude works without one (hosted, billed by usage). |
| `llmModel` | string | Model override (defaults `claude-opus-5-5`, `gemini-3.5-flash-lite`, `gpt-6.1-sol`). |
| `maxPageTokens` | integer | Claude: how much of each page is read (default 30,000; hosted max 60,000). |
| `phraseTypes` | `search` | `ai-prompts` | `both` | Mode url: search queries, AI-assistant prompts, or both. Default `search`. |
| `maxGeneratedPhrases` | integer | Mode url: phrases per URL (default 200, max 500). |
| `language`, `country`, `targetAudience` | string | Mode url: language (`cs`), market (`CZ`) and who the searchers are. |
| `sklikForGenerated` | `none` | `stats` | `expand` | Mode url: no Sklik data, volume per phrase (default), or volume + Sklik ideas for each phrase. |
| `verifyAutocomplete` | boolean | Mode url: check each phrase in Google and Seznam autocomplete. |

#### Match types

| Match type | How to set it | What you get |
|---|---|---|
| Broad (default) | `matchType: "broad"` or plain `bramac tegalit` | Every idea Sklik relates to the seed (e.g. 79 ideas for *bramac tegalit*, including reordered words like *bramac montážní návod tegalit*). |
| Phrase | `matchType: "phrase"` or `"bramac tegalit"` in quotes | Ideas containing the seed words in this order (72 ideas – reordered variants dropped). |
| Exact | `matchType: "exact"` or `[bramac tegalit]` | Only the seed itself with its search volume – no ideas. |

Sklik's stats endpoint does not understand quotes or brackets (it returns 0 for them), so in mode `stats` they are stripped automatically. Negative keywords (`-cheap`) are skipped with a warning.

**Several seeds**: seeds are processed from the shortest (fewest words, then fewest characters). With `expandEverySeed` on (default) each seed still gets its own ideas, but a seed already returned by an earlier seed is not looked up again; turn it off to skip such seeds completely and save money.

#### Negative keywords

Sklik's API does not accept negative keywords, so the Actor filters client-side – before any stats lookup or charge. Matching ignores case and diacritics and works on whole words:

| Negative | Drops |
|---|---|
| `křížovce` | any phrase containing the word *křížovce* (e.g. *oblá střešní taška v křížovce*) |
| `levné tašky` | phrases containing both words, in any order |
| `křížov*` | words starting with *křížov* (*křížovka*, *křížovce*, … – also *křižovatka*, since diacritics are ignored) |
| `"v křížovce"` | the contiguous phrase *v křížovce* |
| `[levné tašky]` | only the exact phrase *levné tašky* |

You can also type `-křížovce` among seeds or keywords. Example: seed `střešní taška` with `"negativeKeywords": ["křížovce"]` removes crossword-clue noise like *oblá střešní taška v křížovce* from the ideas. The number of dropped phrases is shown in the run's status message.

#### Sorting

Rows are buffered and saved at the end in `sortBy` order, so **the dataset order reflects `sortBy`**. The default `value` sorts by `valueCzk` = `cpcCzk × seznamSearchVolume` (a rough monthly click value). If `maxItems` or your maximum charge stops the run early, you keep the top rows in this order. Rows without the sort value (e.g. AI prompts without volume) always go last.

#### Example input – keywords from a web page

```json
{
    "mode": "url",
    "startUrls": [{ "url": "https://www.bramac.cz/" }],
    "geminiApiKey": "<your key>",
    "phraseTypes": "both",
    "sklikForGenerated": "stats",
    "verifyAutocomplete": true
}
```

#### Example input – keyword ideas

```json
{
    "mode": "ideas",
    "seeds": ["elektrokolo"],
    "maxIdeasPerSeed": 20,
    "expandWithAutocomplete": true
}
```

#### Example input – search volume for a list

```json
{
    "mode": "stats",
    "keywords": ["bramac", "střešní taška"]
}
```

### How to get your own Sklik API token (free)

1. Log in to [Sklik](https://www.sklik.cz) with any Seznam account – a Sklik account is free and **no ad spend is needed**.
2. Open <https://www.sklik.cz/settings> and find the section **„Přístup k API Drak"**.
3. Generate a token and paste it into the `sklikApiToken` field. It is stored as an encrypted secret input and never logged.

Without a token the Actor uses our hosted Sklik token – it just costs slightly more per row.

### Mode url: which AI and what it costs

| Provider | Key | What you pay |
|---|---|---|
| **Claude** (default) | none – our hosted key | `url-analysis-hosted` per page + `llm-usage-hosted` per unit of actual token usage (below) |
| Claude | your `anthropicApiKey` ([console.anthropic.com](https://console.anthropic.com/settings/keys)) | only `url-analysis`; Anthropic bills tokens to you |
| Gemini | your `geminiApiKey` | only `url-analysis`; Google bills tokens to you |
| OpenAI | your `openaiApiKey` ([platform.openai.com](https://platform.openai.com/api-keys)) | only `url-analysis`; OpenAI bills tokens to you |

**Hosted Claude is billed by real usage**, because pages and phrase lists vary a lot: a long page or a long phrase list uses more `llm-usage-hosted` units than a short one. Units depend on how much of the page the AI reads, how many phrases it writes and whether it searches the web; cheaper models use fewer units. Units are rounded up per page (minimum 1).

Measured example (bmigroup.com/cz/bmi-bramac, 80 phrases, November 2026): Opus 5.5 read ~28k input tokens and wrote ~3.9k → **48 units**; Sonnet 5.5 → **23 units**; Haiku 5.5 → **3 units**. Before each page the Actor checks that your run's maximum cost can cover the worst case (full page budget + maximum output); otherwise it skips the page with a free error row "charge limit too low for LLM analysis". Per-page token usage and units are saved to the run's key-value store as `OUTPUT`.

### How to get a Google Gemini API key (llmProvider gemini)

Create a key at <https://aistudio.google.com/api-keys> and paste it into `geminiApiKey`. Gemini usage is billed by Google to your key (some projects have a free tier, others need billing enabled in AI Studio – the Actor shows Google's error message if the key cannot be used). The key is an encrypted secret input and never logged.

The AI reads each page (Claude: web fetch + web search; Gemini: URL context + Google Search; OpenAI: web search tool), analyses products, brands, services, locations and problems solved, and returns phrases grouped by intent: `brand`, `product`, `problem`, `comparison`, `price`, `local`, `informational`.

### Output

One row per unique keyword:

| Field | Description |
|---|---|
| `keyword` | The keyword as Sklik returns it. |
| `seznamSearchVolume` | Average monthly searches on Seznam.cz (Sklik `avgSearchCount`, average of the last 2 months). |
| `cpcCzk` | Estimated cost per click in CZK (Sklik halers / 100, 2 decimals). |
| `valueCzk` | `cpcCzk × seznamSearchVolume`, rounded to 2 decimals – a monthly click-value proxy (`null` without CPC or volume). |
| `monthlySearches` | `[{ month: "2026-10", searches }]` – last 12 months, oldest first. |
| `trend` | `rising` / `falling` / `stable` – average of the last 3 months vs the 3 before (±10 %); `null` with < 6 months of data. |
| `peakMonth` | Month with the most searches. |
| `seed` | Seed that produced the row (`null` in mode stats). |
| `sources` | Where the keyword came from: `sklik-suggest`, `sklik-stats`, `google-autocomplete`, `seznam-autocomplete`. |
| `mode` | `ideas` or `stats`. |
| `tokenMode` | `own` (your token) or `hosted` (ours). |
| `fromCache` | `true` when the volumes came from the shared monthly cache. |
| `fetchedAt` | When the data was fetched from Sklik (`null` without a Sklik lookup). |
| `matchType` | Match type used for the seed (`broad`, `phrase`, `exact`) or `null`. |
| `generatedBy` | `claude`, `gemini` or `openai` for phrases generated from a web page, else `null`. |
| `llmModel` | Model that generated the phrase. |
| `phraseType` | `search` or `ai-prompt` (mode url). |
| `intent` | `brand`, `product`, `problem`, `comparison`, `price`, `local` or `informational` (mode url). |
| `rationale` | The AI's short reason for the phrase. |
| `sourceUrl` | Page the phrase was generated from. |
| `inGoogleAutocomplete`, `inSeznamAutocomplete` | With `verifyAutocomplete`: whether the phrase (or a longer variant) is suggested while typing; `null` when not checked. |

In mode url, `seznamSearchVolume` is `null` for AI prompts and when `sklikForGenerated` is `none`; those rows are free.

#### Example output

```json
{
    "keyword": "bramac",
    "seznamSearchVolume": 399,
    "cpcCzk": 2.22,
    "monthlySearches": [
        { "month": "2025-11", "searches": 478 },
        { "month": "2025-12", "searches": 350 }
    ],
    "trend": "stable",
    "peakMonth": "2026-03",
    "seed": null,
    "sources": ["sklik-stats"],
    "mode": "stats",
    "tokenMode": "hosted",
    "fromCache": false,
    "fetchedAt": "2026-11-16T00:07:17.264Z"
}
```

If the Sklik API fails mid-run, the rows collected so far are delivered and one free row with `type: "error"` explains what happened.

### Pricing (pay per event)

You pay only for delivered data. The price shown on the Store card is the **own-token** price; if you leave `sklikApiToken` empty, rows are charged at the hosted price instead.

| Event | When | Price |
|---|---|---|
| `keyword` | One keyword row saved, using **your own** Sklik token. | $0.50 / 1,000 |
| `keyword-hosted` | One keyword row saved, using **our hosted** token (no token entered). | $1.00 / 1,000 |
| `autocomplete-expansion` | One seed expanded with Google + Seznam autocomplete (only when at least one phrase was found). | $2.00 / 1,000 seeds |
| `url-analysis-hosted` | One web page analysed by Claude with our hosted key (flat part). | see Pricing tab |
| `llm-usage-hosted` | Hosted Claude usage, per usage unit (see Mode url). | see Pricing tab |
| `url-analysis` | One web page analysed by AI with your own key (only when phrases were returned). Rows without Sklik data (AI prompts, `sklikForGenerated: none`) are included. | see Pricing tab |

Prices may change; the Pricing tab is authoritative.

Rows dropped by `minSearchVolume` or negative keywords, duplicates across seeds and error rows are free. Cached rows cost the same as live ones – the data is identical. The run stops cleanly at your run's maximum charge or `maxItems`.

Example: 3 seeds × 100 ideas with your own token = 300 × `keyword`. The same with autocomplete = 3 × `autocomplete-expansion` + (300 + new long-tail phrases) × `keyword`.

### Why this Actor

- **The only Seznam.cz search volume Actor in the Apify Store** – other keyword tools cover Google only.
- **Official data source** (Sklik API Drak), no scraping of the Sklik UI, no login sharing.
- **Long tail included** via Google and Seznam autocomplete, with real Seznam volumes instead of guesses.
- **Cheap and fast**: 100 keywords per API call, shared monthly cache, filters applied before charging.

### Limits and notes

- Sklik limits API calls to 300 per minute; the Actor throttles itself to ~4 requests per second and backs off on HTTP 429.
- Volumes are Seznam.cz only (not Google). Very rare keywords may be returned with volume 0.
- `seznamSearchVolume` is the average of the last two months as defined by Sklik; the 12-month series is in `monthlySearches`.
- Autocomplete requests are plain, polite requests; if Google or Seznam rate-limits them, those phrases are skipped and the run continues.

### FAQ

**Do I need a Sklik account?** No – leave the token empty and the hosted token is used. With your own free token rows are cheaper.

**Does my token cost anything or touch my campaigns?** No. Keyword planner calls are read-only and need no ad budget.

**How fresh is the data?** Sklik updates monthly. The shared cache never returns data older than `cacheDays` (default 30).

**Can an AI agent use it?** Yes – call it via Apify MCP with `mode: "stats"` and a keyword list; the output is plain JSON.

### Česky

**Hledanost na Seznam.cz** a návrhy klíčových slov z oficiálního Sklik API (API Drak): průměrná měsíční hledanost, CPC v Kč, vývoj za 12 měsíců, trend a měsíc špičky. Režim `ideas` vrací návrhy ke klíčovým slovům, režim `stats` hledanost pro váš seznam (až 10 000 slov). Volitelně doplní fráze z našeptávače Googlu a Seznamu i s jejich hledaností. Vlastní token zdarma vygenerujete na [sklik.cz/settings](https://www.sklik.cz/settings) v sekci „Přístup k API Drak" (stačí jakýkoli Sklik účet, bez kreditu) – řádky jsou pak levnější. Bez tokenu se použije náš.

Typ shody jako ve Skliku: volná (výchozí), frázová (`"bramac tegalit"` nebo `matchType: "phrase"`) a přesná (`[bramac tegalit]` – jen hledanost samotného slova). Více výchozích slov se zpracuje od nejkratšího. Režim `url`: AI (výchozí Claude – bez klíče přes náš účet, účtováno podle skutečně spotřebovaných tokenů; nebo Gemini / OpenAI s vaším klíčem) přečte web firmy a navrhne fráze, které hledají její zákazníci na Googlu a Seznamu, případně dotazy do ChatGPT/Gemini/Claude, roztříděné podle záměru; volitelně ověří našeptávač a doplní hledanost ze Skliku.

Vylučující slova (`negativeKeywords`, nebo `-křížovce` mezi slovy) se filtrují u nás před účtováním: `křížovce` = celé slovo, `křížov*` = začátek slova, `"v křížovce"` = fráze, `[levné tašky]` = přesně. Výsledky se řadí podle `sortBy` – výchozí je hodnota `valueCzk` = CPC × hledanost.

### Changelog

- **1.3** (November 2026) – mode url is provider-agnostic: Claude (default, hosted key billed by actual usage via `url-analysis-hosted` + `llm-usage-hosted`, or your own key), Gemini or OpenAI with your key; `llmModel`, `maxPageTokens`, worst-case charge check, per-page usage in `OUTPUT`.
- **1.2** (November 2026) – negative keywords (client-side, Sklik-like syntax, also `-word` in seeds/keywords), `sortBy`/`sortDirection` with new field `valueCzk`; rows are saved in sorted order so capped runs keep the most valuable keywords.
- **1.1** (November 2026) – match types (broad / phrase / exact, Sklik syntax in input), seed ordering and dedupe (`expandEverySeed`), new mode `url`: keywords and AI prompts generated from web pages by Google Gemini (your key), autocomplete verification, Sklik stats/expansion for generated phrases, event `url-analysis`.
- **1.0** (November 2026) – first version: modes ideas and stats, autocomplete add-on, own/hosted token, shared monthly cache.

Built by [budoucnost-ai](https://apify.com/budoucnost-ai).

# Actor input Schema

## `mode` (type: `string`):

"ideas" = keyword suggestions for each seed (Sklik keyword planner) with volumes. "stats" = Seznam.cz search volume for your exact keyword list (bulk, 100 per API call). "url" = an AI model (Claude by default – our hosted key or yours; or Gemini / OpenAI with your key) reads your web page(s) and proposes phrases customers search, then optionally gets Seznam volumes.

## `seeds` (type: `array`):

One seed per line, in Czech as people type it on Seznam.cz (e.g. "elektrokolo"). Each seed returns up to maxIdeasPerSeed ideas; duplicates across seeds are delivered (and charged) once. Sklik syntax works per seed: "phrase" = phrase match, \[exact] = only the seed itself.

## `keywords` (type: `array`):

Exact keywords to get Seznam.cz search volume for, one per line (up to 10,000). Keywords without Sklik data are returned with volume 0 unless minSearchVolume filters them out. Pasted Sklik syntax ("…", \[…]) is stripped automatically – Sklik stats would return 0 for it; negative keywords (-…) are skipped.

## `maxIdeasPerSeed` (type: `integer`):

How many suggestions to request from Sklik per seed (1–10,000).

## `related` (type: `boolean`):

Also return related keywords that do not contain the seed (Sklik "related" switch). Off = only phrases containing the seed.

## `orderBy` (type: `string`):

Which ideas Sklik returns first when there are more than maxIdeasPerSeed.

## `matchType` (type: `string`):

Like Sklik match types. Phrase sends the seed in double quotes to Sklik (e.g. "bramac tegalit" returns 72 ideas instead of 79 – reordered-word ideas are dropped). Exact returns just the seed's own volume. A seed typed with "…" or \[…] overrides this.

## `expandEverySeed` (type: `boolean`):

Seeds are processed shortest first. On (default): every seed gets its own ideas even if an earlier seed already returned it. Off: a seed already returned by an earlier seed's ideas is skipped (cheaper, less long tail).

## `minSearchVolume` (type: `integer`):

Drop keywords with fewer average monthly searches on Seznam.cz. Dropped rows are not saved and not charged. 0 = keep all.

## `expandWithAutocomplete` (type: `boolean`):

Mode ideas: also collect what Google (cs/CZ) and Seznam suggest while typing each seed, and look up their Seznam.cz volumes. Finds long-tail phrases Sklik suggest misses. Charged once per seed (autocomplete-expansion) plus each new keyword row.

## `autocompleteAlphabet` (type: `boolean`):

With autocomplete expansion, also query "seed a" … "seed z" (27 queries per source per seed) for many more long-tail phrases.

## `negativeKeywords` (type: `array`):

Drop ideas and phrases containing these (case- and diacritics-insensitive, applied before any lookup or charge – dropped rows are free). křížovce = whole word (several words = all of them, any order), křížov\* = word prefix, "v křížovce" = contiguous phrase, \[levné tašky] = only that exact phrase. You can also type -křížovce among seeds or keywords.

## `sortBy` (type: `string`):

Order of rows in the dataset. Value = cpcCzk × seznamSearchVolume (field valueCzk, a monthly click-value proxy). When maxItems or your charge limit caps the run, the top rows in this order are kept.

## `sortDirection` (type: `string`):

Default: descending (ascending for Keyword). Rows without the sort value always go last.

## `startUrls` (type: `array`):

Pages of the company or product to generate keywords for (e.g. homepage, category page). One AI analysis per URL, max 50.

## `llmProvider` (type: `string`):

Claude: leave anthropicApiKey empty to use our hosted key (events url-analysis-hosted + llm-usage-hosted by actual token usage) or add your own key (event url-analysis only). Gemini and OpenAI always use your own key.

## `anthropicApiKey` (type: `string`):

Your own Claude API key from https://console.anthropic.com/settings/keys – Anthropic bills the tokens to you and this Actor charges only url-analysis. Empty = our hosted key, billed by usage. Stored encrypted, never logged.

## `geminiApiKey` (type: `string`):

Your own Gemini API key (llmProvider gemini) – create it at https://aistudio.google.com/api-keys. Google bills usage to your key (free tier where available). Stored encrypted, never logged.

## `openaiApiKey` (type: `string`):

Your own OpenAI API key (llmProvider openai) from https://platform.openai.com/api-keys. Stored encrypted, never logged.

## `llmModel` (type: `string`):

Override the model. Defaults: claude-opus-5-5 (Claude), gemini-3.5-flash-lite (Gemini), gpt-6.1-sol (OpenAI). With the hosted Claude key only claude-opus-5-5, claude-sonnet-5-5 or claude-haiku-5-5 are allowed (Haiku is ~15× cheaper per unit, Sonnet half of Opus).

## `maxPageTokens` (type: `integer`):

Claude only: how much of each fetched page the model reads (web_fetch max_content_tokens). Larger = more context and higher usage. Hosted key: max 60,000.

## `phraseTypes` (type: `string`):

search = short queries people type into Google or Seznam (get Seznam volume). ai-prompts = natural-language questions people ask AI assistants (no search volume exists – returned with null volume, free).

## `maxGeneratedPhrases` (type: `integer`):

Upper limit of phrases Gemini should return per URL.

## `language` (type: `string`):

Language of the generated phrases (ISO code, e.g. cs, sk, en, de).

## `country` (type: `string`):

Market the phrases are for (ISO country code, e.g. CZ, SK).

## `targetAudience` (type: `string`):

Who searches – e.g. "homeowners planning a new roof". Empty = potential customers of the company behind the URL.

## `sklikForGenerated` (type: `string`):

stats = Seznam.cz volume for every generated search phrase (charged per row like other keywords). expand = also run Sklik keyword ideas for each phrase (maxIdeasPerSeed, shortest first, expandEverySeed applies). none = no Sklik lookup; rows are free (included in url-analysis).

## `verifyAutocomplete` (type: `boolean`):

For each generated search phrase, check whether Google and Seznam autocomplete suggest it (or a longer variant) – fields inGoogleAutocomplete / inSeznamAutocomplete. A quick reality check of AI-invented phrases. Free.

## `sklikApiToken` (type: `string`):

Your own Sklik API Drak token – generate it free at https://www.sklik.cz/settings in section "Přístup k API Drak" (any Sklik account, no ad spend needed). With your token rows cost $0.50 / 1,000 (event keyword). Leave empty to use our hosted token at $1.00 / 1,000 (event keyword-hosted). Stored encrypted, never logged.

## `maxItems` (type: `integer`):

Hard cap on saved (charged) keyword rows for the run.

## `useSharedCache` (type: `boolean`):

Reuse Seznam volumes another run fetched this or last month (Sklik data updates monthly). Faster, same data; rows are marked fromCache. Off = always ask Sklik live.

## `cacheDays` (type: `integer`):

Ignore cached data older than this many days. 0 disables the cache.

## Actor input object example

```json
{
  "mode": "ideas",
  "seeds": [
    "elektrokolo"
  ],
  "keywords": [
    "bramac",
    "střešní taška"
  ],
  "maxIdeasPerSeed": 20,
  "related": false,
  "orderBy": "avgSearchCount",
  "matchType": "broad",
  "expandEverySeed": true,
  "minSearchVolume": 0,
  "expandWithAutocomplete": false,
  "autocompleteAlphabet": false,
  "negativeKeywords": [],
  "sortBy": "value",
  "startUrls": [
    {
      "url": "https://www.bramac.cz/"
    }
  ],
  "llmProvider": "claude",
  "maxPageTokens": 30000,
  "phraseTypes": "search",
  "maxGeneratedPhrases": 200,
  "language": "cs",
  "country": "CZ",
  "sklikForGenerated": "stats",
  "verifyAutocomplete": false,
  "maxItems": 10000,
  "useSharedCache": true,
  "cacheDays": 30
}
```

# Actor output Schema

## `keywords` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "seeds": [
        "elektrokolo"
    ],
    "keywords": [
        "bramac",
        "střešní taška"
    ],
    "negativeKeywords": [],
    "startUrls": [
        {
            "url": "https://www.bramac.cz/"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("budoucnost-ai/seznam-keyword-planner").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "seeds": ["elektrokolo"],
    "keywords": [
        "bramac",
        "střešní taška",
    ],
    "negativeKeywords": [],
    "startUrls": [{ "url": "https://www.bramac.cz/" }],
}

# Run the Actor and wait for it to finish
run = client.actor("budoucnost-ai/seznam-keyword-planner").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "seeds": [
    "elektrokolo"
  ],
  "keywords": [
    "bramac",
    "střešní taška"
  ],
  "negativeKeywords": [],
  "startUrls": [
    {
      "url": "https://www.bramac.cz/"
    }
  ]
}' |
apify call budoucnost-ai/seznam-keyword-planner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,budoucnost-ai/seznam-keyword-planner"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cw6FLw5SPGvefTFdI/builds/9zffR1HwmVCHtkItp/openapi.json
