Гайд · SEO и контент-завод

Wordstat API в Yandex Cloud: как автоматизировать сбор семантики для SEO и контента

API-ключ из AI Studio, folderId, topRequests и Python-скрипт — без ручного копирования из браузера. Для маркетолога, который прогоняет десятки фраз в день.

Канал Maya Pro — автоматизация и вайбкодинг

Если вы ведёте контент-завод или SEO для бизнеса, ручной Wordstat в браузере быстро упирается в потолок: 50–100 фраз в день — и полдня уходит на копирование. Wordstat API в Yandex Cloud Search API решает это программно: один ключ из AI Studio, четыре метода и минимальный Python-скрипт.

Этот гайд — не пересказ документации. Здесь практический маршрут: от API-ключа до CSV в вашем пайплайне и проверки заголовков перед публикацией.

wordstat.py

python3 wordstat.py "вордстат яндекс"
# → totalCount, top, associations

Зачем автоматизировать Wordstat, если есть браузер

Веб-интерфейс идеален для разовой проверки. API — когда семантика становится процессом.

Когда хватает браузера

Раз в неделю смотрите 3–5 фраз, сравниваете формулировки глазами, правите H1 вручную. Для личного блога или одной посадочной — этого достаточно.

Когда нужен API

Контент-завод, агентство, регулярные лонгриды: десятки семян в день, batch-проверка перед постановкой в очередь, связка с Make/n8n и нейросетями для SEO-текста.

Три разных сервиса: не перепутайте

У Яндекса несколько путей к статистике запросов. Смешать их — типичная ошибка на старте.

Сервис	Для чего	Вход
wordstat.yandex.ru (веб)	Ручной анализ, операторы	Браузер
Direct API → Reports.Wordstat	Рекламные отчёты	Рекламный аккаунт, OAuth
Search API v2 → Wordstat	Программный сбор top/динамика/регионы	API-ключ AI Studio + folderId

Search API v2 — простыми словами: облачный интерфейс Яндекса, куда входит Wordstat рядом с Web Search и Generative Search. Root: https://searchapi.api.cloud.yandex.net/v2/wordstat/

Что понадобится перед стартом

Аккаунт Yandex Cloud

Зарегистрируйте облако и откройте AI Studio — там же создаётся API-ключ для YandexGPT и Search API.

Service Account и API-ключ

Создайте сервисный аккаунт, выпустите ключ формата Api-Key. Этот же ключ пойдёт в заголовок Authorization.

folderId

Обязательное поле в JSON каждого запроса. Без него — INVALID_ARGUMENT. ID папки смотрите в консоли Cloud → Folders или в тексте ошибки при тестовом вызове.

folderId — простыми словами: идентификатор «папки» в Yandex Cloud, к которой привязан ваш сервисный аккаунт. API не примет запрос, если folderId пустой или чужой.

Четыре метода API: что выбрать

topRequests

80% задач: топ похожих запросов за 30 дней + associations — семантически близкие формулировки. Основа сбора ядра.

dynamics

Сезонность и тренд: частотность по дням/неделям/месяцам. Важно: для PERIOD_MONTHLY поле toDate должно быть последним днём месяца.

regions

География спроса и affinityIndex — где запрос «горячее» среднего по стране.

getRegionsTree

Справочник регионов с ID. Скачайте один раз, кэшируйте локально (~200 KB JSON).

Первый запрос topRequests пошагово

curl · topRequests

curl -X POST 'https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests' \
-H "Authorization: Api-Key $YANDEX_AI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"phrase": "вордстат яндекс", "numPhrases": 20, "folderId": "ВАШ_FOLDER_ID"}'

В ответе смотрите три зоны: totalCount (общий объём), results (похожие запросы), associations (ассоциации). Частая ошибка — опираться только на «красивую» фразу в results, игнорируя более частотное слитное написание в associations.

associations — простыми словами: поле, где API показывает альтернативные формулировки аудитории. Иногда там в 5–7 раз больше показов, чем у вашего «правильного» запроса.

Продолжение hero · batch-пайплайн

Массовая проверка фраз без браузера

50–100 семян в день — нормальный режим для контент-завода.
Между вызовами sleep(0.2) — вежливость к rate limit.
Отсев: totalCount < 200 — тема слишком узкая для лонгрида.

Минимальный Python-скрипт

Без сторонних библиотек — только stdlib: urllib, json, переменные окружения YANDEX_AI_API_KEY и YANDEX_FOLDER_ID.

Логика: функция call(path, body) → top(phrase) печатает top + associations → расширьте до batch со списком из файла и записью CSV.

Перед арифметикой оборачивайте count в int() — в JSON это строка из-за int64 в protobuf.

На macOS для локальных тестов иногда нужен ослабленный SSL-контекст; в проде используйте нормальный CA-bundle (certifi).

Типичные ошибки и как их обойти

Нет folderId

Ошибка INVALID_ARGUMENT. Проверьте папку сервисного аккаунта в консоли.

Неверный toDate

Для месячной динамики — только последний день месяца в RFC3339.

count как строка

Сравнения и сортировка ломаются без int(r['count']).

Direct API — простыми словами: старый путь через рекламный кабинет. Если у вас нет Директа и нужна только семантика для контента — Search API v2 проще по входу.

Встройка в контент-завод и Make

Практический цикл Kovcheg: черновой H1 → wordstat.py top "..." → переписать под associations → постановка в очередь лонгрида → генерация текста с учётом кластера.

Связка с нейросетями для SEO: API даёт цифры, LLM — черновик, человек — финальную редактуру. Автоматизировать имеет смысл сбор и фильтр, не публикацию без проверки.

Сравнение: веб, API и Key Collector

Инструмент	Плюсы	Минусы
Веб Wordstat 2.0	Операторы, наглядность	Не масштабируется на сотни фраз
Wordstat API	Скрипты, CI, контент-очередь	Нет операторов, одна фраза за вызов
Key Collector и аналоги	Маски, кластеризация	Десктоп, отдельная лицензия

FAQ

Платный ли Wordstat API?

На момент публикации гайда Wordstat в составе Search API AI Studio описывается как бесплатный сервис; платятся токены LLM. Актуальные тарифы — на странице pricing AI Studio.

Можно ли передать операторы Wordstat в API?

Нет. Точная фразовая частотность с !, +, [] — только в веб-интерфейсе.

Сколько запросов в секунду?

Ориентир 5–10 RPS; для batch добавляйте паузу 0.2 с между вызовами.

Нужен ли рекламный аккаунт Директа?

Для Search API v2 — нет. Для Direct API Reports.Wordstat — да.

Что сделать сегодня: чек-лист из 7 шагов

Создать API-ключ в AI Studio.
Записать folderId папки сервисного аккаунта.
Проверить topRequests на одном семени через curl.
Сравнить results и associations.
Собрать минимальный wordstat.py.
Прогнать batch из 10 фраз в CSV.
Встроить проверку H1 в контент-очередь.

Подписаться на Maya Pro