yandex-webmaster

yandex-webmaster

Working with the Yandex Webmaster API v4. Managing sites, analyzing indexing, search queries, recrawling pages, links, feeds.

Config

Required YANDEX_WEBMASTER_TOKEN в config/.env. Scope: webmaster:hostinfo + webmaster:verify. Instruction: config/README.md.

For alice.sh (Share of Voice, without a public API), you additionally need SESSION_ID — a cookie from the browser. Details in config/README.md и references/ALICE_EFFICIENCY.md.

Philosophy

Cache-first — the list of sites and user_id are cached for a long time. Reports are cached by the host+params key. Diagnostics, quotas, statuses — always live.
Context window hygiene — stdout is limited to 30 lines. Full data in TSV/file. The cache is available via grep/rg.
Host resolution — all scripts accept --host <domain> (search the hosts.tsv cache) or --host-id <id> (direct ID). The first call to hosts.sh automatically caches the list.
No destructive ops — the skill does not delete sites, sitemaps, or feeds. Read and add only.

Workflow

STOP! Before any analysis:

Get the list of sites:
```
bash scripts/hosts.sh
```
Ask the user (if the site is not obvious from the context):
```
"О каком сайте идёт речь?
Укажите домен или host_id из списка."
```
To search the cache:
```
bash scripts/hosts.sh --search "example"
```
--host и hosts.sh --search accept a full Cyrillic domain (for example, хорошие-данные.рф) or a site URL (https://хорошие-данные.рф/). The domain is automatically converted to IDNA by means of python3; the scheme and port of the URL are preserved. Latin script and ready-made xn--… names do not require Python. Searching by an arbitrary part of a Cyrillic name is not supported: specify the full domain. The cache and results retain the original ASCII addresses and host_id of Yandex.

Get a summary for the site:

bash scripts/summary.sh --host example.com

Run the required reports for the user's task.

Scripts

General call pattern:

bash scripts/<script>.sh --host <domain> [--action <action>] [params...]

Site management

Script	Description	Key params
`hosts.sh`	List of sites	`--search "text"`, `--no-cache`
`host_info.sh`	Site info + owners	—
`add_site.sh`	Add site	`--url <url>`
`verify.sh`	Site verification	`--action get\|start`, `--method DNS\|HTML_FILE\|META_TAG`

Site statistics

Script	Description	Key params
`summary.sh`	Summary: SQI, pages, issues	—
`sqi_history.sh`	SQI history	`--date-from`, `--date-to`
`diagnostics.sh`	Site issues (live)	—

Search queries

Script	Description	Key params
`popular_queries.sh`	Top queries	`--order-by`, `--device`, `--limit`
`queries_history.sh`	Query history	`--query-id` (optional), `--device`
`query_analytics.sh`	Advanced analytics (POST)	`--text-indicator`, `--filter-*`, `--region-ids`

Indexing

Script	Description	Key params
`indexing.sh`	Indexing history/samples	`--action history\|samples`
`important_urls.sh`	Important URLs	`--action list\|history`, `--url`
`archive_export.sh`	Export all pages	`--action start\|status`, `--task-id`

Pages in search

Script	Description	Key params
`insearch.sh`	Pages in results	`--action history\|samples`
`search_events.sh`	Appearance/disappearance	`--action history\|samples`

Recrawl

Script	Description	Key params
`recrawl.sh`	URL recrawl	`--action submit\|status\|list\|quota`, `--url`, `--task-id`

Links

Script	Description	Key params
`internal_links.sh`	Broken internal links	`--action samples\|history`, `--indicator`
`external_links.sh`	External links	`--action samples\|history`

Sitemaps

Script	Description	Key params
`sitemaps.sh`	Sitemap management	`--action list\|user-list\|info\|add\|recrawl-limit\|recrawl`

Alice / Share of Voice (SSR scraping)

Script	Description	Key params
`alice.sh`	Performance in Alice: SoV timeline, competitors, queries where the site is/isn't present	`--action summary\|sov\|competitors\|with-site\|without-site\|fetch`, `--no-cache`

⚠ No public API — data is parsed from window._initData HTML page. To load, SESSION_ID cookie в config/.envis required. A valid cache is used for 24 hours without loading the page; --no-cache и --action fetch force-update it. If the update fails, the command exits with an error, keeping the previous JSON. Diagnostics and retries: references/ALICE_EFFICIENCY.md.

Feeds and PRO

Script	Description	Key params
`feeds.sh`	YML feeds	`--action list\|add\|change\|add-status`, `--type`, `--region-ids`
`search_export.sh`	PRO SERP export	`--action dates\|limits\|start\|status`
`regions.sh`	Region reference	`--filter "москва"`

General parameters

Param	Description
`--host <domain>`	Site domain/URL (search by hosts.tsv)
`--host-id <id>`	Direct host_id (format: `http:example.com:80`)
`--action <act>`	Script subcommand
`--date-from`	Period start YYYY-MM-DD (history: default 90 days ago)
`--date-to`	Period end YYYY-MM-DD
`--limit N`	Number of records
`--offset N`	Offset
`--no-cache`	Skip cache

Cache strategy

Cache in cache/:

user_id.txt — user ID (permanent)
hosts.json + hosts.tsv — list of sites (permanent, invalidated on add/verify)
host_*/queries/*.tsv — query results (session, hash-keyed)
host_*/indexing/*.tsv — indexing data (session)
host_*/insearch/*.tsv — search data (session)
host_*/links/*.tsv — link data (session)
host_*/alice/init.json — verified Alice object, shared across all actions alice.sh, cache lifetime — 24 hours
host_*/alice/raw.html — the last fully retrieved HTML for diagnostics, without version history
Diagnostics, quotas, recrawl statuses — not cached (always live)

Advanced scenarios

API limits

Query Analytics: 10,000 requests/hour per domain
Scripts automatically handle 429 (Retry-After ≤ 60s → retry, otherwise fail)
Site limit: 1703 per account
Feed limit: 5000 per site, 50 per batch
Export limit: max. 100 date+URL combinations