yandex-wordstat

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}]
}