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