Reliable Yandex Wordstat Collector
Yandex Wordstat Collector
A Yandex Wordstat frequency CLI collector with crash recovery: a null result is never counted as completed data
Medium risk
We rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.
Why this level
- Every request spends a paid Yandex Search API quota billed on the service account
- The API key with search-api.webSearch.user rights is stored in an environment variable or a file on disk
Install
Manual install
npm test && node ./bin/wordstat.js --phrases "куда вложить деньги,робо эдвайзер" --regions 225,213 --out-dir docs/analysis/wordstat --max-requests 20Install from source, the key is read from WORDSTAT_API_KEY, YANDEX_SEARCH_API_KEY or a file under ~/.config/codex-tools/.
This is third-party code. Review the repository files before installing.
What it does
The tool collects phrase frequencies via the topRequests method of the official Yandex Search API, with retry and jitter on 429 and 5xx. Collection state is kept in wordstat-state-v2.json across three buckets: completed, incomplete, failed, plus a quota ledger. The key idea: a result with totalCount: null is never counted as completed data, it is marked for retry or eventually exhausted after several attempts. An interrupted collection can be resumed with --retry-incomplete. A bundled Codex skill at skills/wordstat also builds, on an SEO request, a vocabulary of 25 nouns, adjectives and verbs, 25 example phrases and 10 prioritized recommendations for a title-plus-subtitle pair.
Who it is for. For people collecting large keyword lists from Wordstat who do not want silently incomplete data at the end.
Good fit when
- You need to collect frequencies for a large phrase list with the ability to resume after a failure
- It matters to distinguish a genuine zero from a temporary API error (a null result)
- You need a Codex skill that collects frequencies itself and builds an SEO vocabulary on request
Not a fit when
- You need trend or seasonality data (dynamics), not implemented yet, only on the roadmap
- You have no Yandex Cloud service account with the search-api.webSearch.user role and active billing
Example request
Collect Wordstat frequencies for buy windows and turnkey window installation in the Moscow and Saint Petersburg regionsLimitations
Needs more than a plain AI Studio key: a service account with the search-api.webSearch.user role on the folder and a key with the yc.search-api.execute scope, plus active billing. No regions or dynamics support yet, no MCP wrapper, not published to npm yet. Wordstat accepts at most 100 requests per hour.
How to disable. Delete the cloned repository and, if you installed the Codex skill, the ~/.codex/skills/wordstat folder.
Security check
- Every request spends a paid Yandex Search API quota billed on the service account
- The API key with search-api.webSearch.user rights is stored in an environment variable or a file on disk
README in short
The bilingual README describes the tool's philosophy (not just fetching data but knowing whether it is truly complete), features: retry with backoff, resumable state, a quota ledger, a null-result policy, atomic writes. It shows a quick start, Yandex Cloud service account setup with exact roles and scopes, reliability CLI flags, the state and summary formats, and the bundled Codex skill with subagent orchestration.
FAQ
What if some phrases fail with an error?
Run node ./bin/wordstat.js --retry-incomplete --out-dir docs/analysis/wordstat, the tool picks up only the incomplete and failed phrase-region pairs from the saved state.
Why isn't a null result counted as completed data?
The author explains that if frequency data feeds SEO pages or product decisions, a totalCount: null row is not progress but risk, so such results go into a separate retry bucket.
Related
Official DataLens (Yandex) skills for Claude Code, Codex and OpenCode: SDK, HTML reports and RLS resolution
A Yandex Metrika MCP server generated from the API spec: 108 methods, 10 tools declared by default, transparent filters and response metadata
An open MCP server and agent skill set for SEO: keyword research, competitors, backlinks and site audits powered by DataForSEO
A Claude Code plugin for SEO audits: technical SEO, E-E-A-T, schema, local and AI search via parallel subagents