Wordstat API в Yandex Cloud Search API: разбор endpoints, подводные камни, минимальный Python wrapper (2026)

Понадобилась мне семантика - не в смысле «один раз глянуть Wordstat в браузере», а программно, чтобы прогонять по 50-100 фраз в день и складывать результаты в свою базу. Контекст: веду контент-маркетинг для агентства разработки чат-ботов BotKraft, статьи под Яндекс Нейро. Веб-Wordstat для такого объёма не вариант - копировать вручную из таблички полдня. Direct API - слишком дорогой вход: нужен рекламный аккаунт, отдельный OAuth, у меня этого не было и заводить ради одного метода не хотелось.

Случайно полез в новые сервисы Yandex Cloud AI Studio (там сейчас живёт YandexGPT) и обнаружил, что Wordstat теперь есть в Search API v2 - отдельным сервисом без зависимости от Direct. Доступ - обычный API-ключ из AI Studio, тот же что и для YandexGPT. По сути в один клик получаешь ещё и доступ к семантике.

Подключал, по дороге собрал коллекцию граблей. Этим и поделюсь.

Где это вообще лежит

Не путаем три разных сервиса с похожим названием:

• Search API for sites - старый сервис «поиск по сайту», возвращает SERP по запросам, оплата за выдачу

• Search API v2 (новый) - то что в AI Studio, включает Web Search, Image Search, Generative Search и Wordstat

• Yandex Direct API → Reports.Wordstat - старый путь через рекламный аккаунт

Меня интересует второе. Endpoint root для Wordstat: https://searchapi.api.cloud.yandex.net/v2/wordstat/ ^[1]...

Под капотом - gRPC c REST-обёрткой через google.api.http annotations. Полная proto-спецификация в публичном yandex-cloud/cloudapi ^[2] - рекомендую смотреть туда, а не в гипертекстовую документацию: в proto всё точнее и без неоднозначностей.

Четыре метода:

Ничего сверхъестественного. Operators (!слово, +слово, [слово]) и сравнение нескольких фраз в одном запросе - отсутствуют, об этом ниже.

Авторизация и история про folder

Авторизация - заголовок Authorization: Api-Key <ключ>. Ключ создаётся в AI Studio привязанным к Service Account, тот живёт в каком-то folder. Folder ID - обязательное поле folderId в JSON-теле каждого запроса. Без него - ошибка INVALID_ARGUMENT.

И вот тут первая засада: где взять folder ID? В UI AI Studio это, конечно, есть, но прятано за пару кликов в консоли Yandex Cloud → Folders. Документация AI Studio (на момент моего тыка) folder в инструкциях явно не упоминала - будто все априори знают.

Я узнал свой folder через крайне дурацкий путь. Сначала пытался вызвать YandexGPT с подставленным gpt://test/yandexgpt/latest (просто чтобы проверить что ключ работает). API ответил:

Specified folder ID 'test' does not match with service account folder ID 'b1g0gj00k72p1kr6dsc5'

Спасибо ребятам, что зашили имя реального folder в текст ошибки - буквально лайфхак на ровном месте. Тот же folder подошёл и для Wordstat-эндпоинтов.

Если у вас тоже не сразу очевидно где folder - можно либо тыкать в Cloud Console, либо вот так через текст ошибки. Гарантированно даст актуальный.

topRequests - основной метод

Этот метод я использую в 80% случаев. Он возвращает не просто частотность одной фразы, а топ похожих формулировок (results) и семантически близкие запросы (associations). Последнее - золото, об этом отдельно.

Минимальный запрос:

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,
    "regions": ["213"],
    "folderId": "b1g0gj00k72p1kr6dsc5"
  }'

Параметры:

• phrase - основной запрос (до 400 символов, обязательно)

• numPhrases - сколько результатов вернуть, 1-2000, по умолчанию 20

• regions - массив региональных ID (["213"] - Москва, ["2"] - Санкт-Петербург). Опционально

• devices - массив ["DEVICE_ALL"|"DEVICE_DESKTOP"|"DEVICE_PHONE"|"DEVICE_TABLET"]. Опционально

• folderId - обязательно

Ответ:

{
  "totalCount": "21500",
  "results": [
    {"phrase": "чат боты для бизнеса", "count": "1100"},
    {"phrase": "чат бот для бизнеса макс", "count": "145"},
    {"phrase": "ии чат бот для бизнеса", "count": "102"}
  ],
  "associations": [
    {"phrase": "чатбот", "count": "7371"},
    {"phrase": "чатбот нейросеть", "count": "372"}
  ]
}

Почему count - строки, а не числа? Это особенность gRPC→JSON преобразования: protobuf int64 сериализуется в JSON как string, чтобы не терять точность в больших значениях (а JS-number - int53). Чисто гигиенически - оборачивайте int(...) перед арифметикой, иначе словите сюрприз на сравнениях.

Зачем смотреть на associations

Реальная история. Я готовил статью «Чат-бот для бизнеса: как выбрать», уверенный что основной запрос - чат бот для бизнеса. Запросил topRequests, получил totalCount: 21500 и top-1 «чат боты для бизнеса» - 1100 в месяц. Не густо.

Дальше посмотрел в associations. Первая позиция - слово «чатбот» одно. Просто слитное написание. Частотность - 7371. В семь раз больше моего «правильного» запроса.

Ну и кто из нас был «прав». Маркетолог с многолетней практикой Wordstat это бы заметил глазами - там всё это на одном экране. Я как технарь без regular-практики решил: «возьму то что напрашивается». А API заставил меня посмотреть на associations отдельным полем - и уберёг от очевидного, но проигнорированного бага.

Если вы внедряете Wordstat в автоматический пайплайн (а зачем ещё API?) - обязательно дёргайте обе колонки и сравнивайте totalCount ассоциаций с основным запросом. На свой H1 я в итоге поставил «чатбот», а не «чат бот для бизнеса». Прикинул бы вы такое глазами на 50 фразах в день?

dynamics - графики во времени

Возвращает частотность по периодам. Полезно для оценки сезонности: запускать ли ниши в межсезонье, какой месяц брать за baseline.

curl -X POST 'https://searchapi.api.cloud.yandex.net/v2/wordstat/dynamics' 
  -H "Authorization: Api-Key $YANDEX_AI_API_KEY" 
  -H 'Content-Type: application/json' 
  -d '{
    "phrase": "чат бот для бизнеса",
    "period": "PERIOD_MONTHLY",
    "fromDate": "2026-01-01T00:00:00Z",
    "toDate": "2026-03-31T23:59:59Z",
    "folderId": "b1g0gj00k72p1kr6dsc5"
  }'

period - PERIOD_DAILY / PERIOD_WEEKLY / PERIOD_MONTHLY. С префиксом PERIOD_ - это enum в proto, и API строго проверяет. Без префикса - INVALID_ARGUMENT.

Даты - RFC3339 timestamps. И вот тут второй грабль: для PERIOD_MONTHLY поле toDate ОБЯЗАНО быть последним днём месяца. Поставил 2026-04-01T00:00:00Z - получил:

{
  "code": 3,
  "message": "rpc error: code = InvalidArgument desc = The to field value should be the last day of the month",
  "details": [...]
}

Аналогично - для PERIOD_WEEKLY нужен последний день недели. В proto этого ограничения нет, написано просто google.protobuf.Timestamp. Узнаёшь из ответа сервера. Если делаете календарную автоматизацию - закладывайте функцию last_day_of_period(date, period).

Отдаёт response в виде:

{
  "results": [
    {"date": "2026-01-31T00:00:00Z", "count": "1050", "share": 0.0000087},
    {"date": "2026-02-28T00:00:00Z", "count": "1180", "share": 0.0000094},
    {"date": "2026-03-31T00:00:00Z", "count": "1100", "share": 0.0000091}
  ]
}

share - доля запроса от всех Yandex-запросов в этом периоде. Полезно для нормировки если сравниваете тренды разных ниш.

regions - география запросов

Чтобы понимать, где запускать рекламу или какой регион таргетить контентом.

curl -X POST 'https://searchapi.api.cloud.yandex.net/v2/wordstat/regions' 
  -H "Authorization: Api-Key $YANDEX_AI_API_KEY" 
  -H 'Content-Type: application/json' 
  -d '{
    "phrase": "чат бот для бизнеса",
    "region": "REGION_REGIONS",
    "folderId": "b1g0gj00k72p1kr6dsc5"
  }'

region - три варианта: REGION_ALL (всё подряд), REGION_CITIES (только города), REGION_REGIONS (только субъекты РФ).

В каждом элементе ответа интересно поле affinityIndex:

{
  "region": "1",
  "count": "235",
  "share": 0.0000109,
  "affinityIndex": 120.4
}

affinityIndex - отношение доли запроса в этом регионе к доле по стране. Больше 100 - «горячее» среднего, меньше 100 - слабее. Я использую так: при выборе ниши для лендинга смотрю топ-10 регионов с affinityIndex > 130 - там запрос реально греется, можно ехать с офером.

Минус: region в ответе - это ID, а не название. Чтобы превратить в человекочитаемое - нужен справочник из четвёртого метода.

getRegionsTree - справочник регионов

Самый скучный, но без него географические данные мало понятны. Возвращает дерево всех регионов Yandex с ID и label (название). Я его дёргаю один раз и кэширую в локальный JSON, дальше - просто маппинг id→name.

curl -X POST 'https://searchapi.api.cloud.yandex.net/v2/wordstat/getRegionsTree' 
  -H "Authorization: Api-Key $YANDEX_AI_API_KEY" 
  -H 'Content-Type: application/json' 
  -d '{"folderId": "b1g0gj00k72p1kr6dsc5"}'

В ответе - рекурсивная структура regions: [{id, label, children: [...]}]. Размер JSON - около 200 KB, в нём пара тысяч регионов вплоть до районов городов.

Минимальный Python wrapper

Свой воркшоп в 60 строк, без сторонних библиотек (только stdlib):

import json
import os
import ssl
import sys
import urllib.request
import urllib.error

KEY = os.environ["YANDEX_AI_API_KEY"]
FOLDER = os.environ.get("YANDEX_FOLDER_ID", "b1g0gj00k72p1kr6dsc5")
API_BASE = "https://searchapi.api.cloud.yandex.net/v2/wordstat"

# macOS Python: системный CA-bundle часто не подтянут - отключаем строгую проверку.
# В проде - ставьте certifi и нормальный context, тут для локальных скриптов сойдёт.
SSL_CTX = ssl.create_default_context()
SSL_CTX.check_hostname = False
SSL_CTX.verify_mode = ssl.CERT_NONE


def call(path: str, body: dict) -> dict:
    body.setdefault("folderId", FOLDER)
    req = urllib.request.Request(
        f"{API_BASE}/{path}",
        data=json.dumps(body).encode("utf-8"),
        headers={
            "Authorization": f"Api-Key {KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=30, context=SSL_CTX) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        return {"_http_error": e.code, "_body": e.read().decode("utf-8", errors="replace")}


def top(phrase: str, num: int = 20) -> None:
    res = call("topRequests", {"phrase": phrase, "numPhrases": num})
    if "_http_error" in res:
        sys.exit(f"HTTP {res['_http_error']}: {res['_body'][:200]}")

    print(f"n«{phrase}» - всего {res['totalCount']} запросов/месn")
    print("ТОП:")
    for r in res.get("results", []):
        print(f"  {int(r['count']):>8}   {r['phrase']}")
    if res.get("associations"):
        print("nАССОЦИАЦИИ:")
        for r in res["associations"]:
            print(f"  {int(r['count']):>8}   {r['phrase']}")


if __name__ == "__main__":
    top(sys.argv[1] if len(sys.argv) > 1 else "чат бот для бизнеса", num=10)

Запускаешь python3 wordstat.py ^[3] "ваша фраза" - видишь топ + ассоциации. На основе этого скелета у меня выросли отдельные команды dynamics, regions, batch (последняя - прогон по списку из файла, чтобы проверить SEO-семантику разом).

Я специально ушёл от requests и взял голый urllib: меньше зависимостей, легче ставить в CI, никаких внезапных breaking changes от сторонней либы.

Подводные камни (сводно)

1. Folder ID нигде явно не упомянут в инструкциях - узнаётся через текст ошибки YandexGPT (см. выше). В перспективе наверняка добавят в quickstart, но сейчас так

2. PERIOD_MONTHLY требует toDate - последний день месяца. Аналогично для weekly. В proto не описано, узнаёте от сервера

3. macOS Python без сертификатов: ssl.SSLCertVerificationError. Решение - ssl.CERT_NONE для локалки или установить certifi для прода

4. count приходит строкой (proto-quirk для int64). Не забывайте int(...) перед операциями

5. associations может отсутствовать на узких нишевых запросах - пустой массив, не null. Не assume что ключ всегда есть с данными

Чего НЕТ vs веб-Wordstat

До переезда с веб-Wordstat на API стоит понимать что в API чего-то не будет:

• Операторы (!слово, +слово, [слово]) - не поддерживаются. Передать в phrase можно, но точная фразовая частотность не гарантируется

• Сравнение нескольких фраз в одном запросе - нет. Только по одной за вызов

• Левая колонка / правая колонка отдельно - API возвращает только results + associations, без полного списка ассоциаций без частот

• История запросов пользователя - нет (что логично)

Если вам нужна тонкая работа с операторами - открываете wordstat-2.yandex.ru ^[4] в браузере. Если массовая проверка тысячи фраз для контентного пайплайна - этот API.

Куда я это вписал

Конкретно у меня - в пайплайн проверки H1 / подзаголовков / FAQ. Перед публикацией статьи запускаю wordstat.py ^[3] top "<черновой H1>" - смотрю что там в associations. Часто переписываю H1 под более популярную формулировку. Время - секунды, выгода - часы недописанного контента, который никто не нашёл бы.

Из побочного: автоматизировал проверку «не пишем ли мы про мёртвую тему». Если totalCount < 200/мес - статья слишком узкая, или бы взять смежный широкий запрос.

Цены и квоты

Приятный сюрприз: Wordstat API в составе AI Studio Search API на момент написания бесплатен. По общей политике AI Studio без оплаты идут API-вызовы (в том числе Wordstat и embedding-сервисы), хранилище файлов и поисковые индексы; платить вы будете только за токены LLM-моделей через Model Gallery (YandexGPT и подобные). Wordstat сюда не попадает.

Актуальный статус всё-таки лучше глянуть на странице тарифов AI Studio ^[5] — Yandex иногда меняет правила, особенно когда сервис выходит из беты.

Rate limit, конечно, есть — стандартный для Yandex Cloud, где-то 5-10 RPS. Я не упирался при разумном использовании. Для batch-обходов на сотни ключей закладываю time.sleep(0.2) между вызовами просто из вежливости и чтобы не словить 429.

Когда брать, когда нет

Брать, если:

• Регулярно нужна семантика (10+ запросов в день)

• Уже есть Yandex Cloud-аккаунт с AI Studio (зачастую под YandexGPT)

• Не хочется заводить рекламный аккаунт ради Wordstat

Не брать, если:

• Запросов на Wordstat - 5 в неделю. Веб-интерфейс быстрее

• Нужны операторы и тонкая работа с ассоциациями

• Уже глубоко используете Direct API и Wordstat там устраивает

Полезные ссылки

• Полная proto-спецификация ^[6]

• AI Studio docs ^[7]

• Региональные ID Yandex ^[8]

• Цены AI Studio ^[9]

В целом — практичный API за разумные деньги. Главное переживите грабли с folder ID и месячными датами, дальше всё прозрачно.