Вордстат API через Yandex Search API

Вордстат нужен, когда контент-завод или SEO-система должны писать под реальный спрос. Он показывает, как люди ищут услугу, какие формулировки живые, где есть сезонность и какие регионы стоит смотреть отдельно.

Сейчас автоматический доступ к этим данным идет через Wordstat API в Yandex Search API. Для владельца проекта задача такая - подготовить каталог в Yandex Cloud, выдать роль, получить ключ и передать разработчику несколько значений. Код и запросы начинаются ниже, в блоке для разработчика.

Для владельца проекта

В этой части нет команд и кода. Нужно открыть Yandex Cloud, выбрать или создать каталог для проекта и подготовить доступ к Wordstat API.

Где что взять

Начните отсюда. Это не справка для разработчика, а список мест, где берутся нужные значения.

• Аккаунт и каталог - откройте консоль Yandex Cloud или инструкцию как создать каталог, затем выберите каталог проекта;
• folderId - откройте инструкцию как посмотреть идентификатор каталога и скопируйте строку folderId;
• сервисный аккаунт - откройте инструкцию как создать сервисный аккаунт;
• роль - откройте инструкцию как назначить роль сервисному аккаунту и выдайте роль search-api.webSearch.user на каталог;
• API-ключ - откройте инструкцию как создать API-ключ или путь через Yandex AI Studio, затем проверьте область yc.search-api.execute;
• методы Вордстата - откройте справку Wordstat в Yandex Search API, если нужно сверить методы и ограничения.

После этого сделайте пять вещей.

1. Откройте консоль Yandex Cloud и создайте или выберите каталог для проекта.
2. Создайте сервисный аккаунт для проекта.
3. Выдайте этому аккаунту роль search-api.webSearch.user на каталог через настройку ролей.
4. Создайте API-ключ с областью yc.search-api.execute.
5. Сохраните folderId каталога.

Для проекта обычно удобнее API-ключ, а не IAM-токен. Ключ можно положить в .env и не обновлять вручную каждый час.

Что передать разработчику

Разработчику нужны два значения.

• YANDEX_SEARCH_API_KEY - API-ключ;
• YANDEX_SEARCH_FOLDER_ID - folderId каталога.

Если вместо API-ключа используется IAM-токен, передайте токен и сразу скажите, что это временный токен. Его срок жизни ограничен, поэтому для постоянной автоматизации он менее удобен.

Ключ не отправляют в открытый документ, публичную таблицу или общий чат. Передайте его как пароль или через защищенный канал.

Если вы только готовите доступ, дальше можно не читать. Ниже начинается техническая проверка для разработчика.

Для разработчика

Сначала проверьте, что ключ и каталог работают. Самый безопасный первый запрос - список регионов. Он не требует ключевой фразы и не тарифицируется.

curl \
  --request POST \
  --header "Authorization: Api-Key <API-ключ>" \
  "https://searchapi.api.cloud.yandex.net/v2/wordstat/getRegionsTree" \
  > regions_tree.json

Если используется IAM-токен, заголовок будет таким.

Authorization: Bearer <IAM-токен>

В ответе будет дерево регионов. Например, Россия - 225, Москва - 213, Санкт-Петербург - 2. Для контент-завода обычно сначала выбирают Россию или конкретный регион продаж, а уже потом расширяют семантику.

Получить топ запросов

Метод GetTop возвращает популярные запросы за последние 30 дней. В REST API он вызывается через topRequests.

Создайте body.json.

{
  "phrase": "телеграм бот для бизнеса",
  "numPhrases": 100,
  "regions": ["213"],
  "devices": ["DEVICE_ALL"],
  "folderId": "<идентификатор_каталога>"
}

Затем выполните запрос:

curl \
  --request POST \
  --header "Authorization: Api-Key <API-ключ>" \
  --data "@body.json" \
  "https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests" \
  > result.json

В ответе будут два полезных блока.

• results - запросы, которые содержат заданные слова;
• associations - похожие запросы по смыслу.

Ассоциации нельзя сразу брать в SEO-структуру или рекламу. Сначала проверьте интент, потому похожая фраза может означать другой товар, другую услугу или информационный запрос без заявки.

Что еще умеет Wordstat API

Для Вордстата доступны четыре основных метода.

• GetTop - топ запросов по ключевой фразе;
• GetDynamics - динамика частоты по дням, неделям или месяцам;
• GetRegionsDistribution - распределение запросов по регионам;
• GetRegionsTree - дерево регионов.

Для GetDynamics есть отдельное ограничение. При детализации по дням поддерживаются все операторы, а при детализации по неделям и месяцам - только оператор +.

Цена и лимиты

Для России сейчас действуют такие цены.

• GetTop - 20 ₽ за 1000 запросов;
• GetDynamics - 20 ₽ за 1000 запросов;
• GetRegionsDistribution - 50 ₽ за 1000 запросов;
• GetRegionsTree - не тарифицируется.

Для Wordstat действует отдельное ограничение - 10 запросов в секунду и 100 запросов в час на получение статистики. Поэтому в контент-заводе лучше не дергать API на каждую статью в момент генерации. Надежнее собрать семантику пачкой, сохранить результат и переиспользовать его в контент-плане.

Как это используется в контент-заводе

В рабочем контент-заводе маршрут обычно такой.

1. Человек задает услугу, регион и список тем.
2. Система запрашивает Вордстат через Yandex Search API.
3. Запросы раскладываются по интентам и кластерам.
4. Нецелевые формулировки отсекаются.
5. Для нормальных кластеров готовятся темы, заголовки, структура и внутренние ссылки.
6. Контент-завод пишет материалы под проверенный спрос, а не просто по идеям из головы.

Перед автоматизацией важно решить регион, список услуг, частоту обновления семантики и место хранения результата. Для маленького проекта хватит таблицы. Для регулярного конвейера удобнее хранить данные в базе или JSON-очереди тем.

Частые ошибки

• выдали ключ, но забыли folderId;
• создали сервисный аккаунт, но не назначили роль search-api.webSearch.user;
• пытаются использовать старый токен от Вордстата вместо ключа или IAM-токена Yandex Search API;
• берут ассоциации как готовые SEO-запросы без проверки интента;
• не учитывают лимит 100 статистических запросов в час;
• запускают сбор по всем регионам, хотя проекту нужен один город;
• отправляют API-ключ в открытый документ.

Если доступа к Yandex Search API пока нет, можно начать с ручной выгрузки тем, собрать структуру контент-завода и подготовить таблицу кластеров. Но для регулярной автоматической семантики сейчас нужно ориентироваться на официальный Wordstat API внутри Yandex Search API.

Официальные источники

• API Вордстата в справке Яндекс Вордстата
• Wordstat в документации Yandex Search API
• Аутентификация в API Yandex Search API
• Консоль Yandex Cloud
• Создать каталог в Yandex Cloud
• Посмотреть идентификатор каталога
• Создать сервисный аккаунт
• Назначить роль сервисному аккаунту
• Создать API-ключ для сервисного аккаунта
• Получить API-ключ в Yandex AI Studio
• Получить топ результатов по ключевой фразе
• Правила тарификации Yandex Search API
• Квоты и лимиты Yandex Search API

Для подготовки тем, источников и правил публикации смотрите гайд Контент-завод и автопостинг.