yandex-search-api

Parse Yandex SERP via Yandex Cloud Search API v2 (sync + async).

Config

Для работы нужен сервисный аккаунт Яндекс.Облака. Пошаговая инструкция (6 шагов, ~10 минут): config/README.md.

Краткий чеклист:

ID каталога Яндекс.Облака → в config.json
Файл ключа сервисного аккаунта → в config/service_account_key.json
Проверка: bash scripts/iam_token_get.sh

macOS: может потребоваться brew install openssl — подробности в config/README.md.

Workflow

STOP! Before any search:

Определи регион:
- Если пользователь указал город/регион — найди ID автоматически:
```
bash scripts/search_region.sh --name "Казань"
```
- Если регион не понятен из контекста — СПРОСИ и ЖДИ ответа:
```
"Для какого региона искать?
- Вся Россия (по умолчанию)
- Москва
- Конкретный город (какой?)"
```
  НЕ ПРОДОЛЖАЙ пока пользователь не ответит!
- Полученное название → search_region.sh --name "..." → получаешь ID
- Для неоднозначных случаев (Москва город vs область) — уточни у пользователя
Режим поиска берётся из config.json → search.mode (по умолчанию sync). Не спрашивай — используй то, что в конфиге.
Verify config: bash scripts/iam_token_get.sh
Run search с полученным region ID
Present results with position, title, URL, snippet

Scripts

iam_token_get.sh

Generate or validate IAM token from Service Account key.

bash scripts/iam_token_get.sh

Token is cached in cache/iam_token.json and auto-refreshed when expired.

web_search_sync.sh

Synchronous search — one query at a time, immediate results.

# Single query
bash scripts/web_search_sync.sh \
  --query "купить дымоход" \
  --region-id 213

# Batch from file
bash scripts/web_search_sync.sh \
  --file queries.txt \
  --region-id 225 \
  --results 20

Param	Required	Default	Values
`--query, -q`	yes*	-	Search text
`--file, -f`	yes*	-	File with queries (one per line)
`--region-id, -r`	no	from config (225)	Region ID
`--results, -n`	no	10	Results per page (1-100)
`--page, -p`	no	0	Page number
`--search-type`	no	SEARCH_TYPE_RU	SEARCH_TYPE_RU / SEARCH_TYPE_TR / SEARCH_TYPE_COM / SEARCH_TYPE_KK / SEARCH_TYPE_BE / SEARCH_TYPE_UZ
`--family-mode`	no	FAMILY_MODE_MODERATE	FAMILY_MODE_NONE / FAMILY_MODE_MODERATE / FAMILY_MODE_STRICT

* Either --query or --file is required.

Results saved to cache/results/<hash>.json (parsed) and cache/results/<hash>.raw (XML).

web_search_async.sh

Asynchronous batch search — submit many queries, poll for results.

# Submit batch and wait
bash scripts/web_search_async.sh \
  --file queries.txt \
  --region-id 213

# Resume after timeout/interrupt
bash scripts/web_search_async.sh --resume

Param	Required	Default	Values
`--file, -f`	yes	-	File with queries
`--region-id, -r`	no	from config (225)	Region ID
`--poll-interval`	no	10	Poll interval (minutes)
`--max-wait`	no	120	Max wait before timeout (minutes)
`--resume`	no	-	Continue polling pending ops

Async workflow:

Script submits all queries as async operations
Polls every poll_interval minutes for completion
Downloads and parses results as they complete
If max_wait exceeded: prints summary + resume command
On restart with --resume: continues from cache/ops/, no duplicates

NOTE for agent: Async execution can take minutes to hours. The script handles polling automatically. If it times out, re-run with --resume to continue.

regions_tree.sh

Show common region IDs.

bash scripts/regions_tree.sh

search_region.sh

Find region ID by name.

bash scripts/search_region.sh --name "Казань"

Output Format

Each search result contains:

position — rank in SERP
title — page title
url — page URL
snippet — text snippet (up to 300 chars)
domain — site domain

Results cached in cache/results/:

<hash>.raw — raw XML from API
<hash>.json — parsed JSON array

Popular Region IDs

Region	ID
Россия	225
Москва	213
Москва и область	1
Санкт-Петербург	2
Екатеринбург	54
Новосибирск	65
Казань	43

Run bash scripts/regions_tree.sh for full list.

Pricing

Yandex Search API v2 pricing (as of 2025):

Sync requests: billed per request
Async requests: billed per request
Free tier available (check current limits)
See: https://yandex.cloud/ru/docs/search-api/pricing

Example Session

User: Найди топ выдачи яндекса по запросу "купить сэндвич дымоход" в Москве

Claude: Уточню: Москва-город или Москва и область?

User: Москва город

Claude: [Находит ID региона]
        bash scripts/search_region.sh --name "Москва"
        → Москва = 213

        [Проверяет токен]
        bash scripts/iam_token_get.sh

        [Выполняет поиск — 1 запрос, автоматически sync]
        bash scripts/web_search_sync.sh --query "купить сэндвич дымоход" --region-id 213

        Результаты поиска (топ-10):

        1. Сэндвич-дымоходы купить в Москве — Леруа Мерлен
           https://leroymerlin.ru/...
           Широкий ассортимент сэндвич-дымоходов...

        2. Дымоходы сэндвич — купить в интернет-магазине
           https://...
           ...

User: Проверь выдачу по запросам из файла queries.txt в Казани

Claude: [Находит ID региона]
        bash scripts/search_region.sh --name "Казань"
        → Казань = 43

        [Проверяет токен]
        bash scripts/iam_token_get.sh

        [Режим sync из конфига — запускает батч по одному]
        bash scripts/web_search_sync.sh --file queries.txt --region-id 43