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

• Search API for sites - старый сервис «поиск по сайту», возвращает SERP по запросам, оплата за выдачу
  
• Search API v2 (новый) - то что в AI Studio, включает Web Search, Image Search, Generative Search и Wordstat
  
• Yandex Direct API → Reports.Wordstat - старый путь через рекламный аккаунт

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

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

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"
  }'

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

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

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": "1",
  "count": "235",
  "share": 0.0000109,
  "affinityIndex": 120.4
}

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"}'

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)

• Folder ID нигде явно не упомянут в инструкциях - узнаётся через текст ошибки YandexGPT (см. выше). В перспективе наверняка добавят в quickstart, но сейчас так
  
• PERIOD_MONTHLY требует toDate - последний день месяца. Аналогично для weekly. В proto не описано, узнаёте от сервера
  
• macOS Python без сертификатов: ssl.SSLCertVerificationError. Решение - ssl.CERT_NONE для локалки или установить certifi для прода
  
• count приходит строкой (proto-quirk для int64). Не забывайте int(...) перед операциями
  
• associations может отсутствовать на узких нишевых запросах - пустой массив, не null. Не assume что ключ всегда есть с данными

• Операторы (!слово, +слово, [слово]) - не поддерживаются. Передать в phrase можно, но точная фразовая частотность не гарантируется
  
• Сравнение нескольких фраз в одном запросе - нет. Только по одной за вызов
  
• Левая колонка / правая колонка отдельно - API возвращает только results + associations, без полного списка ассоциаций без частот
  
• История запросов пользователя - нет (что логично)

• Регулярно нужна семантика (10+ запросов в день)
  
• Уже есть Yandex Cloud-аккаунт с AI Studio (зачастую под YandexGPT)
  
• Не хочется заводить рекламный аккаунт ради Wordstat

• Запросов на Wordstat - 5 в неделю. Веб-интерфейс быстрее
  
• Нужны операторы и тонкая работа с ассоциациями
  
• Уже глубоко используете Direct API и Wordstat там устраивает

• Полная proto-спецификация
  
• AI Studio docs
  
• Региональные ID Yandex
  
• Цены AI Studio