Wordstat API: подключение за 15 минут

Зачем это

Вордстат руками — это 20 фраз за вечер. По API — несколько тысяч фраз за один прогон, с реальной частотностью, сразу в CSV, откуда их забирает кластеризация и контент-план. Разница между «я примерно представляю спрос» и «у меня ядро из 2500 фраз с цифрами» — это разница между сайтом-угадайкой и сайтом под живой спрос.

Второе применение — агент. Claude Code с этим ключом сам проверяет гипотезы по темам: «а сколько ищут X», «что ещё спрашивают вокруг», «растёт спрос или падает». Без ключа он такие вопросы гадает — и это самая частая причина выдуманных цифр в SEO-планах.

Что понадобится

• Аккаунт Яндекса — тот, на котором будет жить облако. Рабочий, не одноразовый: к нему привязывается биллинг.
• Банковская карта — для активации биллинга. Пополнять баланс не нужно, но карта должна быть привязана: без активного биллинга API отвечает 403. При привязке спишется и вернётся ~11 ₽ — проверка карты.
• 15 минут. Ничего устанавливать не надо, всё в браузере.

Программисткой части ноль: на выходе — две строки (ключ и Folder ID), которые ты вставляешь в свой .env.

Шаг за шагом — подробно

Дальше те же три действия, но с деталями: куда именно кликать, что скопировать и где обычно спотыкаются.

Шаг 1. Открой Yandex AI Studio

Иди на aistudio.yandex.ru и нажми «Войти». Это витрина Yandex Cloud для ИИ-сервисов — через неё удобнее всего создать ключ для Search API. Авторизуйся тем аккаунтом Яндекса, на котором хочешь держать облако: сменить его потом = завести всё заново.

Если облака ещё нет — консоль предложит создать его и каталог (folder) по умолчанию. Соглашайся, названия оставь дефолтные.

Шаг 2. Привяжи карту к биллингу

Search API работает только при активном платёжном аккаунте. В консоли открой Биллинг → Создать платёжный аккаунт, укажи физлицо/ИП и привяжи карту. Новому аккаунту дают стартовый грант — 4000 ₽ на 60 дней (общий на любые сервисы облака, не «под Вордстат»).

Пополнять баланс не нужно. Но пропустить этот шаг нельзя: самый частый 403 — именно непривязанная карта.

Шаг 3. Создай API-ключ

В AI Studio нажми «Создать API-ключ». В описании напиши что-то понятное — например Wordstat · SEO-завод: через полгода ты не вспомнишь, какой ключ куда воткнут. Если предлагается выбрать область действия — оставь доступ к Search API (yc.search-api.execute).

Ключ создаётся на сервисный аккаунт — это «робот» внутри твоего облака, от имени которого пойдут запросы. Если сервисного аккаунта ещё нет, консоль создаст его сама.

Шаг 4. Скопируй ключ сразу

Яндекс показывает значение ключа один раз. Закрыл окно, не скопировав — ключ придётся удалять и создавать заново. Сразу положи его в .env проекта или в менеджер паролей. Ключ выглядит как AQVN… и в чат, репозиторий и скриншоты не попадает никогда.

Шаг 5. Возьми Folder ID

Открой console.yandex.cloud и зайди в нужный каталог. Folder ID — в адресной строке после /folders/, начинается с b1.

https://console.yandex.cloud/folders/b1gk7a9m3x2q0p8s5vwd
                                     └──────── это Folder ID ────────┘

Шаг 6. Проверь роль сервисного аккаунта

Часто всё уже работает и этот шаг можно пропустить — но если проверка из следующего раздела вернула 403 при верном Folder ID, дело в правах. В каталоге открой Права доступа (IAM) и посмотри, есть ли у сервисного аккаунта, на который выпущен ключ, роль search-api.webSearch.user.

Нет — нажми «Назначить роли» → в поле «Кому выдать доступ» выбери свой сервисный аккаунт → в поиске ролей введи search-api.webSearch.user → сохрани. Права применяются за несколько секунд.

Шаг 7. Поставь бюджет-предохранитель

Пять минут, которые снимают единственный денежный риск, — подробности ниже. Кратко: Биллинг → Бюджеты → Создать бюджет, тип «Расходы», 300–500 ₽/мес, пороги 50/80/100%.

Проверка запросом

Прежде чем куда-то вставлять ключ — убедись, что он живой. Подставь свои значения и выполни в терминале:

curl -s -X POST https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests \
  -H "Authorization: Api-Key ТВОЙ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"phrase":"натяжные потолки","numPhrases":5,"regions":["225"],"folderId":"ТВОЙ_FOLDER_ID"}'

Рабочий ответ выглядит так (это реальный ответ, полученный при подготовке инструкции):

{
 "results": [
  {"phrase": "натяжной потолок",              "count": "1163278"},
  {"phrase": "натяжной потолок цена",         "count": "63663"},
  {"phrase": "потолок под натяжной потолок",  "count": "58147"},
  {"phrase": "установка натяжных потолков",   "count": "52940"},
  {"phrase": "натяжные потолки фото",         "count": "46835"}
 ],
 "associations": [
  {"phrase": "натяжка потолка", "count": "4367"}
 ],
 "totalCount": "1163344"
}

Регионы: 225 — вся Россия, 213 — Москва, 2 — Санкт-Петербург. Полный справочник кодов отдаёт эндпоинт /getRegionsTree.

Куда вставлять ключ

Правило одно: ключ живёт только в .env (в .gitignore), никогда — в конфиге, коде, .md-файлах и переписке.

YANDEX_CLOUD_API_KEY=AQVN...
YC_FOLDER_ID=b1g...

Если сайтов несколько — ключ общий на все, держи его в одном месте и подтягивай оттуда, чтобы не размножать копии:

mkdir -p ~/Projects/.secrets
printf 'YANDEX_CLOUD_API_KEY=AQVN...\nYC_FOLDER_ID=b1g...\n' > ~/Projects/.secrets/yandex-cloud.env
chmod 600 ~/Projects/.secrets/yandex-cloud.env

Если у тебя SEO-завод

Впиши те же две переменные в .env рядом с site.config.yml и проверь, что завод их видит:

python3 engine/seo-agent/orchestrator.py doctor       # ключ виден? модуль включился?
python3 engine/seo-agent/scripts/collect_semantics.py # сиды → живое ядро + wordstat_seed.csv
python3 engine/seo-agent/scripts/refine_semantics.py  # чистка ядра под кластеризацию

Сид-фразы (по одной на строку, 25–30 «голов» ниши) лежат в engine/seo-agent/data/wordstat_seeds.txt. Флаг WORDSTAT_LIVE=1 в .env заставляет модуль семантики обновлять ядро самостоятельно перед каждой кластеризацией.

Деньги и предохранитель

Честно, без «всё бесплатно, не переживай»:

• Сами вызовы Wordstat сейчас не тарифицируются — в Search API платный только веб-поиск (порядка 50–200 ₽ за 1000 запросов) и токены LLM-моделей. Если ты дёргаешь только Вордстат, списаний быть не должно.
• Грант 4000 ₽ на 60 дней — общая скидка новому платёжному аккаунту, а не «пакет запросов Вордстата». Закончится — Вордстат продолжит работать.
• ⚠️ Статус «бесплатно» может смениться при выходе сервиса из беты. Это единственный реальный риск: раз в пару месяцев поглядывай на страницу тарифов Search API.
• ⚠️ Жёсткого стоп-крана в облаке нет. Бюджеты только шлют уведомления — сами ничего не выключают. Не рассчитывай, что лимит остановит списание.

Как закрыть риск за пять минут: Консоль → Биллинг → Бюджеты → Создать бюджет → тип «Расходы», сумма 300–500 ₽/мес, пороги уведомлений 50/80/100%. Вторым сделай бюджет типа «Остаток средств» — он предупредит, когда грант подходит к концу. Крайняя мера, если облако больше ни для чего не нужно: после гранта отвязать карту — тогда списывать физически не с чего.

Что умеет API

Четыре метода, общий корень https://searchapi.api.cloud.yandex.net/v2/wordstat/, во всех — заголовок Authorization: Api-Key … и поле folderId в теле.

Сезонность запроса

curl -s -X POST https://searchapi.api.cloud.yandex.net/v2/wordstat/dynamics \
  -H "Authorization: Api-Key ТВОЙ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"phrase":"натяжные потолки","regions":["225"],"period":"PERIOD_MONTHLY",
       "fromDate":"2026-01-01T00:00:00Z","toDate":"2026-06-30T00:00:00Z","folderId":"ТВОЙ_FOLDER_ID"}'

География спроса

curl -s -X POST https://searchapi.api.cloud.yandex.net/v2/wordstat/regions \
  -H "Authorization: Api-Key ТВОЙ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"phrase":"натяжные потолки","regions":["225"],"folderId":"ТВОЙ_FOLDER_ID"}'

В ответе у каждого региона есть affinityIndex: 100 — «как в среднем по стране», заметно выше — регион, где тема аномально популярна. Это и есть кандидаты на гео-страницы.

Лимиты и грабли

• ⚠️ 100 запросов в час (search-api.wordstatRequestsPerHour). Превысил — 429. Значит: один прогон = не больше 100 сид-фраз, а если сайтов несколько — разноси сборы по времени, по сайту в час.
• 🩸 Самая дорогая ошибка: «не смог померить» превращается в «спроса нет». Сам API честно отдаёт 429. Но обёртка с ретраями почти всегда написана так: попытки кончились — return {}. Дальше int(resp.get("totalCount") or 0) — и в базе появляется частотность 0, неотличимая от честного нуля. Я на этом попался на живом проекте: замер 503 страниц показал «93% без спроса», хотя на самом деле их было 40–48% — остальное просто не поместилось в квоту. Проверять надо не только исключение, но и пустой ответ: нет поля totalCount — это «не замерено», такие фразы не пишем в кэш и домеряем позже.
• count приходит строкой, а не числом (protobuf int64). Всегда оборачивай в int(), иначе сортировка по частотности молча сломается.
• Операторы не поддерживаются — ни "кавычки", ни !словоформа, ни +предлог, ни [порядок]. Через API доступна только широкая частотность. Нужна точная — руками в веб-интерфейсе.
• Одна фраза за вызов, сравнить несколько в одном запросе нельзя. numPhrases — от 1 до 2000.
• associations шумят и бывают пустыми. На узких нишах — пустой массив; на широких лезут однословки, которые шире исходной фразы («потолок» 3.3 млн против «натяжной потолок» 1.16 млн). Однословки из ядра лучше вычищать.
• Не долби чаще ~5 запросов в секунду — ставь паузу 0.2–0.3 с между вызовами.
• macOS: при SSLCertVerificationError в Python подсунь сертификаты certifi — это не проблема ключа.

Если не работает

Когда 100 запросов в час не хватает

Сотня в час — это про десятки фраз, а не про сотни. Если нужно померить весь бэклог тем или все страницы сайта разом, Вордстат через Yandex Cloud физически не тянет: 500 фраз растянутся на пять часов. Тогда его ставят первым в цепочку — как бесплатный — а остаток добирают платным источником.

Порядок именно такой: кэш → бесплатный Вордстат → платный добор. И обязательно общий кэш на все проекты — фраза, померенная один раз, больше не должна стоить денег никогда. У меня это обычный JSON-файл в домашней папке; за счёт него повторные прогоны почти ничего не тратят.

Две вещи, на которых легко потерять данные при доборе. Первая — у Арсенкина любая пунктуация в фразе роняет всю задачу целиком, а не одну строку: одна запятая в списке из 180 фраз — и не замерилось ничего. Чистите фразы по белому списку (буквы, цифры, пробел) и делите пачку пополам при ошибке валидации. Вторая — у XMLRiver старый метод wordstat/json отключён, живой сейчас wordstat/new/json, а нулевой баланс приходит не HTTP-ошибкой, а текстом внутри ответа.

Скрипт: ядро в CSV

Рабочий минимум на чистом Python — ни одной внешней библиотеки. Кладёшь сид-фразы в SEEDS, получаешь wordstat_seed.csv с длинным хвостом и частотностью.

#!/usr/bin/env python3
"""Wordstat API: собрать длинный хвост по сид-фразам в CSV. Только стандартная библиотека."""
import csv, json, os, time, urllib.request

KEY    = os.environ["YANDEX_CLOUD_API_KEY"]
FOLDER = os.environ["YC_FOLDER_ID"]
URL    = "https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests"
REGION = "225"        # 225 — вся Россия, 213 — Москва, 2 — Санкт-Петербург

SEEDS = ["натяжные потолки", "натяжной потолок в спальню"]   # не больше 100 фраз в час!

def top(phrase, num=100):
    body = json.dumps({"phrase": phrase, "numPhrases": num,
                       "regions": [REGION], "folderId": FOLDER}).encode("utf-8")
    req = urllib.request.Request(URL, data=body, headers={
        "Authorization": "Api-Key " + KEY, "Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.load(r)

rows = {}
for seed in SEEDS:
    data = top(seed)
    for item in data.get("results", []) + data.get("associations", []):
        rows[item["phrase"]] = int(item["count"])      # count приходит СТРОКОЙ
    print(seed, "→ всего фраз:", len(rows))
    time.sleep(0.3)                                    # не долбить чаще ~5 rps

with open("wordstat_seed.csv", "w", newline="", encoding="utf-8") as f:
    w = csv.writer(f); w.writerow(["phrase", "count"])
    for phrase, count in sorted(rows.items(), key=lambda kv: -kv[1]):
        w.writerow([phrase, count])
print("готово → wordstat_seed.csv")

set -a; . ~/Projects/.secrets/yandex-cloud.env; set +a
python3 collect.py

Два сида выше дают на выходе ~220 фраз. Тридцать сидов — пара тысяч, и это уже ядро, из которого строится структура сайта.

Промпт для Claude Code

Если не хочется возиться руками — отдай подключение агенту. Он проведёт по шагам, положит ключи куда надо и сам проверит, что всё живое.

Помоги подключить Wordstat API через Yandex Cloud (Search API v2).
Проведи меня по шагам: AI Studio → биллинг с картой → API-ключ → Folder ID из URL после /folders/
→ роль search-api.webSearch.user. Спрашивай по одному шагу и жди, пока я сделаю.

Когда получу ключ и Folder ID:
1. Запиши их в .env как YANDEX_CLOUD_API_KEY и YC_FOLDER_ID (chmod 600, .env — в .gitignore).
   В чат, конфиги и .md-файлы значения НЕ выводи.
2. Проверь живым запросом на POST https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests
   с телом {"phrase":"<моя тема>","numPhrases":5,"regions":["225"],"folderId":...} и покажи ответ.
3. Если 403 — проверь по порядку: folderId, привязана ли карта, есть ли роль. Скажи, что чинить.
Помни: лимит 100 запросов в час, count приходит строкой, операторы (!, +, "", []) не поддерживаются.