Keyword research tool: build a semantic core

Try it

play_arrowOpen the interactive demo

Thirteen stages, one accumulating core

Each stage changes a status and records the reason, so a phrase is never deleted and every decision can be explained. Free stages sit between the paid ones, so you check the pool before you buy the next answer.

• check_circleFreeFree, runs locally
• paymentsPaidPaid provider call
• publicWebPublic web pages, no provider quota

1. 1uploadcheck_circleFree

   Import

   Bring what you already have: a CSV or one sheet of an XLSX. Map query, frequency, group, subgroup, URL and comment, then add, update or replace. The preview shows new, existing and duplicate rows before anything is written.

   phrases
2. 2travel_explorepaymentsPaid

   Collect · Yandex Wordstat

   Expands your seeds by region and re-expands strong phrases up to the depth you set. The queue is deduplicated, and --resume continues an interrupted run without asking for the same phrase again.

   phrases, expansions, provenance
3. 3cleaning_servicescheck_circleFree

   Clean

   Applies the project filters (intent, stop words, informational patterns), flags frequency outliers and groups phrases by lemma. A phrase with observed impressions or positions is never cut by frequency rules.

   status, route, lemma group
4. 4hubcheck_circleFree

   Graph

   Builds a word graph of the pool. Homonym candidates go to review and candidate clusters land in anomalies.md, before you pay for anything else.

   anomalies.md
5. 5storefrontcheck_circleFree

   Site match

   A phrase belongs in the core only when the site offers it. Phrases without any term from catalog.txt go to review as off-catalog.

   review list
6. 6workspacespaymentsPaid

   Cluster · Yandex Search API

   Fetches one top 10 per phrase and caches it, so a repeated run pays only for new phrases. Phrases that share pages form a cluster; --method louvain regroups the cached results to break long chains.

   SERP cache, clusters, landing candidates
7. 7rulecheck_circleFree

   Relevance

   If no site of your kind from vendors.txt appears in a phrase's top 10, the topic is probably off scope. The phrase goes to review; nothing is deleted.

   review list
8. 8groupscheck_circleFree

   Competitors

   Reads the cached results: which domains hold your clusters and which words they use in titles. Candidates go to synonyms.txt.

   competitors.md, synonyms.txt
9. 9manage_searchpublicWeb

   Mine

   Opens the most frequent competitor pages from the collected results and reads their title, description, H1 and first H2 headings. Topical two- and three-word phrases go to synonyms.txt.

   competitor_mining.md, synonyms.txt
10. 10sync_altpaymentsPaid

    Synonyms · Yandex Wordstat

    Checks the candidates in synonyms.txt. Only phrases with demand join the core; then collect --resume grows the pool from them.

    checked phrases
11. 11targetpaymentsPaid

    Exact frequency · Arsenkin

    Buys the exact !W frequency once per lemma group, at the end, when the pool has stopped changing. Above the project's budget gate it needs --yes.

    exact frequency, task receipts
12. 12table_viewcheck_circleFree

    Report and Excel

    report.md and clusters.csv for reading, an XLSX workbook (Summary, Core, Info, Clusters, Rejected) for the client, pool.csv and pool.json for other tools.

    report.md, XLSX, CSV, JSON
13. 13insightscheck_circleFree

    Landing and insights

    After launch, pick each cluster's landing page from measured candidates, then read weekly cluster signals from your local Search Console, Webmaster and Metrika data and turn chosen ones into checklist tasks.

    landing, weekly signals, tasks

Where the data comes from

The collection pipeline runs on Yandex data. Google demand, rank tracking and search analytics are separate toolkit commands that work next to the core.

Inside the pipeline

Paid

Yandex Wordstat

collect · synonyms

Base frequency, refinements and similar queries through the Yandex Cloud API. API key and folder ID; hourly quota.

Paid

Yandex Search API

cluster

One top 10 per phrase and region, cached with its fetch time and region. The async endpoint only.

Paid

Arsenkin

exact

The exact !W frequency the Wordstat API does not give. Billed at task creation; the task_id is kept, so a timed-out result is fetched again, not bought again.

Next to the core

Paid

DataForSEO

google-keywords

Google search volume, competition and seed expansion. Sandbox by default.

Paid

Wordstat one-offs

keywords-expand · keywords-seasonality · regions-tree

Expand one phrase, read its demand by month, browse the region tree (the tree is free).

Free

Topvisor

topvisor-read

Reads projects, keywords and recorded position history from your existing account. Paid checks cannot be launched from the toolkit.

Free

Search Console · Webmaster · Metrika

semantics insights

Weekly cluster signals from data the toolkit already synced locally. The insights step itself makes no provider calls.

Pay once, see the plan first

Every paid stage has an offline plan: the region, the engine, the query source and an upper bound of requests or tasks. No provider client is created by a plan.

When a provider price cannot be established offline, the plan says so instead of guessing a number.

Import and export

Real output from the CLI

Captured from the synthetic example project that ships with the toolkit. Its phrases are Russian, as Yandex demand is, and its frequencies are invented. No paid call was made.

$ seohead semantics clean --project ./core
$ seohead semantics graph --project ./core
$ seohead semantics sitematch --project ./core
clean: kept=34 review=4 dropped=3 | lemma groups=41 (median base=720, outlier>36000)
graph: homonyms=0, to review=0, candidate clusters=7 -> anomalies.md
sitematch: catalog terms=11 | off-catalog->review=8 | kept and matching the site=26

$ seohead semantics cluster --project ./core --dry-run
"mode": "estimate", "stage": "cluster", "paid": true,
"provider": "yandex_search",
"request_estimate": {"unit": "requests", "count": 26, "kind": "upper_bound"},
"money_estimate": null,
"money_unavailable_reason": "provider pricing is not available from this offline preflight",
"paid_calls_made": 0

$ seohead semantics status --project ./core
dropped=3 | kept=26 | review=12 | _total=41 | _exact=0 | _expanded=0 | _clusters=0
provider units: {'yandex_requests': 0, 'arsenkin': 0}
next: seohead semantics exact --project ./core

$ seohead semantics export --project ./core --scope no-landing --dry-run
"mode": "preview", "scope": "no-landing", "rows": 41,
"planned_files": ["core/semantics/pool.csv", "core/semantics/pool.json"]

seohead semantics status --project ./my-core

Hand the core to an agent

Ten MCP tools expose the same stages and reads. A paid call returns the plan and needs confirm_paid=true to send work.

• seo_semantics_statusCounters, provider units and the next stage
• seo_semantics_runFree stages
• seo_semantics_mineCompetitor pages, no provider quota
• seo_semantics_paidPaid stages: plan first, then confirm_paid=true
• seo_semantics_clustersPaged cluster list
• seo_semantics_cluster_showOne cluster with its landing evidence
• seo_semantics_cluster_queriesPhrases of a cluster with the retained top 10
• seo_semantics_set_landingAssign or clear a landing page
• seo_semantics_insightsWeekly signals by cluster and source
• seo_semantics_insights_tasksChosen signals into the checklist

Keep exploring