# Yandex Keyword Suggest Scraper (`apt_marble/yandex-keyword-suggest-scraper`) Actor

Turn one seed term into thousands of the real search queries people type on Yandex, ranked in Yandex's own suggestion order, for the city and market you sell into. Covers Russian, Kazakh and Turkish. Gives you the queries themselves — not an estimate of how often they are searched.

- **URL**: https://apify.com/apt\_marble/yandex-keyword-suggest-scraper.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Categories:** SEO tools
- **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.25 / 1,000 keyword founds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Yandex Keyword Suggest Scraper

Give it a topic and it gives you back the actual search queries people type into Yandex around that topic — thousands of them, in the order Yandex itself suggests them, for the exact city and market you sell into. It is built for SEO and PPC teams working the Russian-speaking market, where the usual Western keyword tools have thin coverage and the official planner is behind a login. **Important, and stated up front: this returns the queries people type, not a figure for how many times they type them. No such figure is published anywhere on this source, and this actor will never show you one.**

### What you can do with it

- **Build a long-tail keyword universe from one seed.** One topic, expanded with buying words, question words, letters and digits, becomes thousands of distinct real queries in a single run.
- **Do local SEO properly.** The same seed returns genuinely different lists in Moscow, Yekaterinburg, Kazan and Minsk — different local brands, different phrasing, different intent. Pick the city you actually sell in.
- **Find the brands that own a category in each city.** Where Yandex treats a query as a shortcut to a particular company, the company's name and web address come back with the keyword — a fast way to see who dominates a niche in a market you do not know yet.
- **Separate buying intent from browsing.** Turn on the shopping-intent set and the informational noise drops away, leaving the phrasing people use when they mean to purchase.
- **Feed a content plan.** Question-shaped queries ("how", "what", "where", "which") come back grouped and ready to become articles.
- **Cover Kazakh and Turkish markets too**, with the same seed workflow and each market's own alphabet.

### What you get

One row per distinct keyword, per seed term. An abridged real record:

```json
{
  "seed": "пицца",
  "keyword": "пицца мия екатеринбург",
  "queryPrefix": "пицца ",
  "position": 3,
  "expansionLevel": 0,
  "source": "search",
  "language": "ru",
  "regionId": 54,
  "regionName": "Yekaterinburg",
  "resolvedRegionCode": 11162,
  "wordCount": 3,
  "characterCount": 22,
  "containsSeed": true,
  "siteTitle": null,
  "siteDomain": null,
  "collectedAt": "2026-08-17T11:57:32.414Z"
}
```

### Input reference

| Setting | Type | Default | What it does |
| --- | --- | --- | --- |
| Seed terms | list of text | — | The topics you want ideas for, one per line. Up to 50 per run. This is the only setting you must fill in. |
| Market | choice | Russian | Which market's suggestions to collect: Russian, Kazakh or Turkish. Sets both the language you get back and the ordering they arrive in. |
| Region | choice | Moscow, Russia | The city or country whose searchers you want. 17 Russian cities plus Belarus, Kazakhstan, Uzbekistan and Turkey. Local brands and local phrasing differ sharply between cities, and this is what makes the output usable for local work. |
| Expansion depth | whole number, 0–2 | 1 | How far past the seed to go. `0` returns only what the source suggests for the seed as typed. `1` also pairs the seed with buying words, question words, letters and digits — the usual choice, and typically a few thousand ideas per seed. `2` re-expands everything found at level 1 and produces the deepest list. |
| Maximum keywords per seed | whole number, 1–25000 | 2000 | Stops each seed once this many distinct keywords have been collected. This is your main control on how large and how expensive a run is. |
| Also collect shopping-intent and word-completion suggestions | yes / no | no | Adds two further short sets to every seed: shopping-intent queries, which strip informational noise and leave purchase phrasing, and single-word completions, which surface word stems the main list misses. |
| Extra words to combine with each seed | list of text | empty | Your own words to pair with every seed, on top of the built-in buying and question words. Useful for brand names, model numbers or an industry's own vocabulary. Up to 40. |
| Speed | whole number, 1–30 | 10 | How many parts of the job to work on at once. Higher finishes sooner. Leave it alone unless you have a reason not to. |

### Output fields

| Field | Description |
| --- | --- |
| `seed` | The seed term this keyword was found for. |
| `keyword` | The search query itself, exactly as the source publishes it. |
| `queryPrefix` | The starting point that surfaced this keyword. Group by this to see which angle produced which ideas. |
| `position` | Where the source placed this keyword in its own suggestion order for that starting point. `1` is first. This is a rank, not a count, and not a volume. Empty on the one row per completion starting point that the source publishes outside its ranked list, because that row has no rank of its own. |
| `expansionLevel` | `0` for the seed itself, `1` for the first round of combinations, `2` for the deepest round. |
| `source` | Which set the keyword came from: `search`, `shopping` or `completion`. |
| `language` | The market that was collected: `ru`, `kk` or `tr`. |
| `regionId` | The region code you chose. |
| `regionName` | The plain-English name of that region. |
| `resolvedRegionCode` | The region grouping the source actually applied to this answer. `0` means the source did not apply the region you chose for that particular answer — a condition you can see and filter on rather than one hidden from you. Empty where the source publishes no grouping. |
| `wordCount` | How many words the keyword contains. Useful for isolating long-tail phrases. |
| `characterCount` | How many characters the keyword contains. |
| `containsSeed` | Whether the keyword still contains your seed term. Deep expansion drifts, and this lets you keep or drop the drift deliberately. |
| `siteTitle` | Where the source treats the query as a shortcut to a specific company, that company's name. Empty for ordinary keywords — and empty means empty, never a guess. |
| `siteDomain` | The web address of that company, in the same case. Empty for ordinary keywords. |
| `collectedAt` | When the keyword was collected, as a timestamp. |

### Pricing

You pay per keyword, and only for keywords that actually reach your results.

| What you pay for | Price |
| --- | --- |
| Each distinct keyword written to your results | $0.00025 — that is **$0.25 per 1,000 keywords** |

A keyword is written once per seed term, so you are never billed twice for the same idea inside one seed. There is no second charge of any kind: the expansion is the product, not an upgrade.

**Worked example.** One seed at the default settings, capped at 2,000 keywords, costs **$0.50**. A ten-seed research sprint at the same cap costs **$5.00**. If you push a single seed to the maximum of 25,000 keywords, that run costs **$6.25**. Set "Maximum keywords per seed" and you have set your bill.

A seed the source publishes nothing for produces no rows, and therefore costs you nothing.

### Limits & what this actor cannot do

- **It does not tell you how often a keyword is searched.** There is no volume, popularity, traffic, competition or difficulty figure anywhere in what this source publishes, so there is none in the output. What you do get is the source's own ordering, which reflects what it suggests first — a useful signal, but a rank, never a number. If you need volume figures, this is not the tool.
- The source publishes a limited number of suggestions for any one starting point. Depth is what turns that into thousands of ideas; a single starting point on its own returns a few dozen at most.
- **The company shortcut is rare.** `siteTitle` and `siteDomain` are filled only on the few queries the source itself treats as a shortcut to a particular company, and that is a small minority of any list — measured at 3 rows in 312 across eight commercial topics, roughly 1%. It is a genuine signal about who owns a query, not a column you can expect on most rows, and the rest are empty rather than guessed.
- The word-completion set is short by design — the source publishes only a handful of completions for any stem, and no setting increases it.
- The shopping-intent set is shorter still, and it ignores the region you choose. Those rows reflect the source's default market, not your city. The main set does honour your region.
- Some region and market pairings are not applied by the source. When that happens the affected rows carry a resolved region code of `0` and the run says so plainly, rather than passing another market's results off as yours.
- Results are a snapshot at the moment of collection. The source's suggestions change continuously, and two runs an hour apart will not match exactly.
- The actor reports what the source publishes to the public. It does not sign in, sees nothing behind a login, and cannot reveal anything the source keeps private.
- Deep expansion drifts away from the seed. The large majority of keywords still contain the seed exactly — above 96% on the deep runs we measured — and the rest are related queries the source associates with it. `containsSeed` marks each row so you can keep or drop the drift deliberately.
- A seed the source refuses to answer is reported as a failed seed, with a count you can see in the run summary. It is never reported as "no keywords found". If the source stops answering partway through a seed, the run stops that seed, keeps what it already collected and says so, rather than presenting a truncated list as a complete one.
- Turkey can only be collected together with the Turkish market, because that is the only combination the source honours. The run refuses the other combinations rather than quietly returning a different market's results.
- How long a run takes depends on how large the job is and on the source's own response times. No fixed speed is promised.
- The source's terms govern automated access. You are responsible for using the data lawfully and in line with those terms, including any applicable privacy law.

### FAQ

**Does it tell me how many people search each keyword?**
No, and nothing that looks like it will. This source does not publish a search-volume figure of any kind, and inventing one would be worse than useless. You get the queries themselves and the order the source ranks them in. Many teams pair this list with their own click or conversion data, which is more reliable than a third-party estimate anyway.

**Do I need an account on the source site?**
No. Nothing is signed in to and nothing is set up.

**Does it need my login or password?**
No. It never asks for one and could not use one.

**Can I schedule it?**
Yes. Run it on any schedule you like and watch how a market's queries shift week to week.

**How many keywords will one seed actually give me?**
At depth `1`, a few thousand for a broad commercial topic. At depth `2` a single broad seed can pass ten thousand distinct queries. A narrow or obscure seed returns far fewer, because the source genuinely has less to suggest for it. Your "Maximum keywords per seed" setting is the ceiling in every case.

**Which markets and languages does it cover?**
Russian, Kazakh and Turkish, each with its own alphabet and its own ordering. Regionally you can choose 17 Russian cities, Minsk and Belarus nationwide, Almaty, Astana and Kazakhstan nationwide, Tashkent, and Turkey nationwide.

**Why do the same seeds give different results in different cities?**
Because people in different cities search for different things, and the source knows it. A pizza query in Yekaterinburg surfaces a chain that only exists there. That is precisely what makes this useful for local work, and it is why the region setting is worth choosing deliberately.

# Actor input Schema

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

The topics you want keyword ideas for. One term per line. Each seed is expanded into the real queries people type around it. Up to 50 seeds per run.

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

Which market's suggestions to collect. This sets the language the suggestions come back in and the ranking they are ordered by.

## `regionId` (type: `string`):

The city or country whose searchers you want. Local brands and local phrasing differ sharply between cities, and this is what makes the list usable for local SEO. Turkey is meant to be used with the Turkish market.

## `expansionDepth` (type: `integer`):

How far to go beyond the seed itself. 0 returns only what the source suggests for the seed as typed. 1 also combines the seed with buying words, question words, letters and digits — this is the usual choice and returns a few thousand keywords per seed. 2 then re-expands everything found at level 1 and returns the deepest list.

## `maxKeywordsPerSeed` (type: `integer`):

Stop each seed once this many distinct keywords have been collected. This is the main control on how big and how expensive a run is.

## `includeVerticalSuggestions` (type: `boolean`):

Adds two further sets of suggestions to each seed: shopping-intent queries, which strip out informational noise and leave the terms people use when they intend to buy, and single-word completions, which surface stems the main list misses. Both are small and both add rows you pay for.

## `extraModifiers` (type: `array`):

Your own words to pair with every seed, in addition to the built-in buying and question words. Useful for brand names, model numbers or an industry's own vocabulary. Up to 40.

## `maxConcurrency` (type: `integer`):

How many parts of the job to work on at once. Higher finishes sooner; lower is gentler on the source. Leave the default unless you have a reason to change it.

## Actor input object example

```json
{
  "seeds": [
    "кроссовки",
    "доставка еды"
  ],
  "language": "ru",
  "regionId": "213",
  "expansionDepth": 1,
  "maxKeywordsPerSeed": 1000,
  "includeVerticalSuggestions": false,
  "extraModifiers": [
    "nike",
    "adidas",
    "2026"
  ],
  "maxConcurrency": 5
}
```

# Actor output Schema

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

Every keyword collected, in the scannable column order.

## `keywordsCsv` (type: `string`):

The same keywords as a spreadsheet download.

## `keywordsFull` (type: `string`):

Every keyword with every field, including the ones the table view hides.

## `runSummary` (type: `string`):

How many seeds were collected, how many had nothing published, and how many could not be read.

# 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": [
        "кроссовки"
    ],
    "expansionDepth": 1,
    "maxKeywordsPerSeed": 1000
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/yandex-keyword-suggest-scraper").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": ["кроссовки"],
    "expansionDepth": 1,
    "maxKeywordsPerSeed": 1000,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/yandex-keyword-suggest-scraper").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": [
    "кроссовки"
  ],
  "expansionDepth": 1,
  "maxKeywordsPerSeed": 1000
}' |
apify call apt_marble/yandex-keyword-suggest-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apt_marble/yandex-keyword-suggest-scraper"
        }
    }
}

```

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/j5IWuKwTqcZ8xeBBW/builds/3HznYK1tRJIdPFqYs/openapi.json