OpenParable
Skip to content
← Back to skills

Yandex Wordstat

Apps & Automation
yandex-wordstat

Yandex Wordstat is an Agent Skill for apps & automation published in the hashgraph-online/awesome-codex-plugins repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Узкий актуальный справочник по Yandex Search API Wordstat v2: методы, схемы, авторизация, квоты, регионы, устройства и динамика. Для рекламного процесса сначала использовать yandex-direct-unified.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/hashgraph-online/awesome-codex-plugins/blob/HEAD/plugins/nebelov/yandex-direct-for-all/skills/yandex-wordstat/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/yandex-wordstat, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Yandex Wordstat API v2

Этот файл не задает порядок сбора семантики, смысловые решения, минус-слова, структуру кампаний или готовность к сборке.

Для любых задач Яндекс.Директа, ключевых фраз, SQR, семантики и стоп-слов сначала открыть yandex-direct-unified, его обязательные references и keyword-collection-runbook.md. Этот файл использовать только как справочник по текущему Wordstat API.

Канонический транспорт

  • Базовый адрес: https://searchapi.api.cloud.yandex.net.
  • Текущая версия: синхронный REST API v2.
  • Старый https://api.wordstat.yandex.net/v1/* и метод userInfo не использовать.
  • folderId передается в теле каждого запроса.
  • Для локального клиента рабочий сбор идет по целевому гео; вся Россия может использоваться только как явно обозначенный фон.

Авторизация

Разрешены два варианта:

  1. API-ключ: заголовок Authorization: Api-Key <key>.
  2. IAM-токен: заголовок Authorization: Bearer <iam-token>.

Для API-ключа нужна область yc.search-api.execute, а сервисному аккаунту или пользователю — роль search-api.webSearch.user на нужный каталог.

Секреты нельзя печатать, передавать в аргументах процесса или сохранять в raw/manifest. Канонический credential-файл должен находиться в закрытом каталоге 700, иметь владельца рабочего пользователя и права 600.

Общие перечисления

Устройства:

  • DEVICE_ALL;
  • DEVICE_DESKTOP;
  • DEVICE_PHONE;
  • DEVICE_TABLET.

Если передается список devices, в нем не более трех значений. Для topRequests и dynamics список regions содержит не более 100 строковых ID.

Методы

POST /v2/wordstat/topRequests

Назначение: спрос за последние 30 дней, популярные вложенные фразы и ассоциации.

Запрос:

{
  "phrase": "обязательная фраза до 400 символов",
  "numPhrases": 2000,
  "regions": ["регион"],
  "devices": ["DEVICE_ALL"],
  "folderId": "каталог"
}

numPhrases: от 1 до 2000.

Ответ:

{
  "totalCount": 0,
  "results": [{"phrase": "...", "count": 0}],
  "associations": [{"phrase": "...", "count": 0}]
}

Ассоциаций в одном ответе бывает не более 20. Для Директа и results, и associations сохраняются как raw и дальше проходят только workflow yandex-direct-unified.

POST /v2/wordstat/dynamics

Назначение: динамика спроса.

Запрос:

{
  "phrase": "обязательная фраза до 400 символов",
  "period": "PERIOD_MONTHLY",
  "fromDate": "2026-01-01T00:00:00Z",
  "toDate": "2026-07-01T00:00:00Z",
  "regions": ["регион"],
  "devices": ["DEVICE_ALL"],
  "folderId": "каталог"
}

Периоды: PERIOD_MONTHLY, PERIOD_WEEKLY, PERIOD_DAILY. Даты передаются в RFC3339. Для недельной и месячной динамики допустим только оператор +; для дневной поддерживаются все операторы Wordstat.

Ответ:

{
  "results": [{"date": "2026-01-01T00:00:00Z", "count": 0, "share": 0.0}]
}

POST /v2/wordstat/regions

Назначение: распределение спроса за последние 30 дней.

Запрос:

{
  "phrase": "обязательная фраза до 400 символов",
  "region": "REGION_ALL",
  "devices": ["DEVICE_ALL"],
  "folderId": "каталог"
}

Значения region: REGION_ALL, REGION_CITIES, REGION_REGIONS. Путь /v2/wordstat/regionsDistribution неверен: это было смешение имени gRPC-метода с REST-путем.

Ответ:

{
  "results": [
    {"region": "ID", "count": 0, "share": 0.0, "affinityIndex": 0.0}
  ]
}

POST /v2/wordstat/getRegionsTree

Назначение: дерево поддерживаемых регионов.

Запрос содержит только folderId:

{"folderId": "каталог"}

Ответ:

{
  "regions": [
    {"id": "ID", "label": "Название", "children": []}
  ]
}

Метод официально не тарифицируется, но лишние вызовы запрещены.

Квоты и повтор

  • Не более 10 запросов в секунду.
  • Не более 100 запросов в час суммарно для topRequests, dynamics, regions и getRegionsTree; дерево регионов имеет нулевую стоимость, но потребляет запрос квоты.
  • В v2 нет userInfo и ответа с остатком дневной квоты.
  • Сборщик обязан вести локальный почасовой учет, ограничивать скорость и обрабатывать HTTP 429/Retry-After.
  • При ограничении сохраняются raw, manifest, закрытые маски и очередь незакрытых масок. После разрешенного ожидания сбор продолжается с незакрытого элемента без дублей.
  • Ошибка целевой маски должна попасть в wordstat_errors_retry_log.tsv; волна не закрывается, пока повтор не дал результат либо маска явно не помечена blocked с причиной.

Операторы

Поддерживаются операторы Wordstat -, +, !, кавычки, квадратные и круглые скобки. Их семантика применяется по официальной документации Wordstat. Операторная форма маски не является автоматически готовым ключом Директа.

Правила для Директа

  1. Сначала intake-gate, product/routing/protected layers и pre-Wordstat извлечение синонимов.
  2. Затем raw Wordstat/SQR.
  3. После raw: SAFE_STOP только с protected-check, сохраняемый prefilter, затем полный построчный смысловой разбор.
  4. Скрипт не имеет права выбирать ключи, ставить semantic verdict или объявлять coverage PASS.
  5. Каждая raw-строка получает candidate_id либо явное решение с причиной.
  6. Live apply, минус-слова, черновики и любые записи в Директ требуют отдельного явного разрешения пользователя.

Первоисточники