Wordstat GetTop API: как получить реальные запросы и что делать с results и associations

Wordstat GetTop API — это метод из Yandex Search API v2, который отдает частотность и похожие формулировки по seed-фразе программно, без ручного копирования из веб-интерфейса Wordstat. Доступ открывается через обычный API-ключ Yandex Cloud AI Studio, тот же, что выдается для YandexGPT, без рекламного аккаунта Directа. В статье разберем, чем этот метод отличается от старого Wordstat API, что означают поля results и associations и как собрать рабочий Python-скрипт для сбора семантики пачками.

Search API v2 добавил Wordstat в один пакет с YandexGPT: авторизация одним ключом, без Direct и без рекламного кабинета. Метод GetTop за один вызов отдает и топ похожих фраз, и ассоциативные запросы с частотностью за 30 дней. В статье: разбор параметров, готовый Python-код и сравнение с автоматизацией через Make.

Что такое Wordstat GetTop API и зачем он вайбкодеру?

GetTop — это метод Search API v2, который по одной ключевой фразе возвращает похожие запросы (results) и смежные по смыслу формулировки (associations) с частотой за месяц.

Метод живет по адресу https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests и принимает POST-запрос с телом в JSON. Он не показывает историю по датам и не строит карту регионов — для этого есть соседние методы GetDynamics и GetRegionsDistribution. GetTop нужен ровно для одной задачи: понять, что вообще ищут по теме, и с какой частотой.

Для вайбкодера, который пишет статьи или собирает семантику для SEO-агента, это разница между «скопировать вручную из таблички полчаса» и «прогнать список из 200 фраз за пять минут». Учитывая, что портал строится на программатик-контенте, ручной сбор ключей просто не масштабируется.

Чем Search API v2 отличается от старого Wordstat API через Direct?

Старый Wordstat API требует рекламный аккаунт Yandex Direct и отдельный OAuth. Новый Search API v2 работает через тот же ключ, что и YandexGPT в AI Studio, и не завязан на Direct вообще.

Раньше единственный путь к программному Wordstat шел через Yandex Direct: заявка в поддержку Direct, привязка к рекламному кабинету, отдельная авторизация. Для человека без запущенной рекламы это лишний барьер ради одного метода. Search API v2 убрал эту зависимость: ключ создается в AI Studio, доступ дают через сервисный аккаунт с ролью search-api.webSearch.user.

Заявку на доступ все равно нужно подавать в обоих случаях, но для Search API v2 это происходит внутри знакомого интерфейса AI Studio, а не через отдельную форму поддержки Direct.

Как получить доступ к Wordstat GetTop без Direct?

Нужен аккаунт Yandex Cloud, сервисный аккаунт с ролью search-api.webSearch.user и API-ключ с областью действия yc.search-api.execute. Дальше — идентификатор каталога (folder ID) в теле каждого запроса.

Шаги простые, но два момента ломают людей регулярно. Folder ID нигде явно не подписан в интерфейсе, его нужно искать в Yandex Cloud → Folders или через свойства сервисного аккаунта. Без этого поля в теле запроса метод отвечает ошибкой INVALID_ARGUMENT, и по тексту ошибки не всегда сразу понятно, в чем дело.

Второй момент — выбор способа авторизации. Api-Key проще для разовых скриптов и cron-задач, IAM-токен безопаснее для продакшена, потому что у него короче срок жизни. Для статьи и одиночного пайплайна хватает API-ключа: создаете его один раз в AI Studio и кладете в переменную окружения.

Что означают results и associations в ответе GetTop?

results — это топ похожих формулировок исходной фразы с частотой за 30 дней. associations — семантически близкие запросы, которые пользователи искали в той же сессии. Оба массива идут в одном ответе.

Вот минимальный пример ответа на фразу «купить собаку»:

{
  "totalCount": "48885",
  "results": [
    { "phrase": "купить собаку", "count": "48885" }
  ],
  "associations": [
    { "phrase": "сколько стоит пудель", "count": "613" }
  ]
}

results показывает морфологические и близкие вариации запроса — то, что реально забивают в поиск. associations — совсем другие фразы, которые ассоциативно связаны с темой: их ищет та же аудитория, но другими словами. Для SEO это отдельный источник LSI-ключей, который часто дает более частотную формулировку, чем та, что казалась очевидной с самого начала.

Важный технический нюанс: поле count приходит строкой, а не числом. Так gRPC сериализует 64-битные целые в JSON, чтобы не терять точность на больших значениях. Перед арифметикой оборачивайте значение в int(), иначе сравнения посчитают строки, а не числа.

Как параметры запроса влияют на результат?

Кроме обязательной фразы, метод принимает numPhrases (сколько строк вернуть), regions (гео), devices (тип устройства) и folderId (идентификатор каталога).

Регионы задаются числовыми ID: 213 — Москва, 2 — Санкт-Петербург и так далее по справочнику Yandex. Devices принимает DEVICE_ALL, DEVICE_DESKTOP, DEVICE_PHONE или DEVICE_TABLET. Если регион не указан — метод считает запросы по всей аудитории Yandex, что обычно и нужно для контентной статьи без гео-привязки.

Операторы вроде !слово, +слово и [слово], знакомые по веб-версии Wordstat, метод не поддерживает. Передать их в phrase можно, но точная фразовая частотность не гарантируется — для такой точечной работы остается веб-интерфейс.

Как написать Python-скрипт для сбора топ-запросов?

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

Ниже рабочий код, который можно скопировать без изменений. Понадобится только API-ключ в переменной YANDEX_API_KEY и folder ID в YANDEX_FOLDER_ID.

import os
import csv
import time
import requests

API_URL = "https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests"
API_KEY = os.environ["YANDEX_API_KEY"]
FOLDER_ID = os.environ["YANDEX_FOLDER_ID"]


def get_top_requests(phrase: str, region: int = 213, limit: int = 100) -> dict:
    """Возвращает словарь {"results": [...], "associations": [...]} по одной фразе."""
    body = {
        "phrase": phrase,
        "numPhrases": limit,
        "regions": [str(region)],
        "devices": ["DEVICE_ALL"],
        "folderId": FOLDER_ID,
    }
    headers = {
        "Authorization": f"Api-Key {API_KEY}",
        "Content-Type": "application/json",
    }

    for attempt in range(3):
        response = requests.post(API_URL, json=body, headers=headers, timeout=30)

        if response.status_code == 200:
            data = response.json()
            return {
                "phrase": phrase,
                "total_count": int(data.get("totalCount", 0)),
                "results": [
                    {"phrase": r["phrase"], "count": int(r["count"])}
                    for r in data.get("results", [])
                ],
                "associations": [
                    {"phrase": a["phrase"], "count": int(a["count"])}
                    for a in data.get("associations", [])
                ],
            }

        if response.status_code == 429:
            wait = 2 ** attempt
            time.sleep(wait)
            continue

        if response.status_code >= 500:
            time.sleep(1.5)
            continue

        response.raise_for_status()

    raise RuntimeError(f"Не удалось получить данные по фразе: {phrase}")


def batch_get_top(phrases_list: list, delay: float = 0.1) -> list:
    """Прогоняет список фраз с задержкой между вызовами, чтобы не словить 429."""
    results = []
    for phrase in phrases_list:
        try:
            results.append(get_top_requests(phrase))
        except RuntimeError as error:
            results.append({"phrase": phrase, "error": str(error)})
        time.sleep(delay)
    return results


def save_to_csv(data: list, filename: str) -> None:
    """Сохраняет результаты batch_get_top в плоский CSV: фраза, тип, значение, частота."""
    with open(filename, "w", newline="", encoding="utf-8") as file:
        writer = csv.writer(file)
        writer.writerow(["seed_phrase", "type", "phrase", "count"])

        for item in data:
            if "error" in item:
                writer.writerow([item["phrase"], "error", item["error"], ""])
                continue

            for r in item["results"]:
                writer.writerow([item["phrase"], "result", r["phrase"], r["count"]])
            for a in item["associations"]:
                writer.writerow([item["phrase"], "association", a["phrase"], a["count"]])


if __name__ == "__main__":
    seeds = ["вайбкодинг", "нейросеть для кода", "ai ide"]
    collected = batch_get_top(seeds, delay=0.2)
    save_to_csv(collected, "wordstat_report.csv")

Три вещи, на которых стоит написать себе напоминание в коде. Folder ID обязателен в каждом запросе, без него метод сразу отвечает ошибкой на уровне валидации. Задержку между вызовами лучше не убирать даже при небольшом списке фраз, лимит на разумной эксплуатации — около 5-10 запросов в секунду. И да, count в исходном JSON — строка, скрипт выше уже конвертирует ее в число внутри get_top_requests.

Как избежать блокировки 429 при массовом сборе ключей?

429 означает превышение лимита запросов в секунду. Решение — задержка между вызовами и экспоненциальный retry на уровне кода, а не бесконечный цикл без паузы.

На практике, если гнать список из 500+ фраз без паузы, сервис быстро начнет отвечать 429. Функция get_top_requests выше уже делает retry с растущей паузой: 1 секунда, потом 2, потом 4. Для батча из нескольких сотен фраз этого достаточно, чтобы пройти список без ручного вмешательства.

Второй практический момент — не запускать сбор семантики параллельно в несколько потоков без общего троттлинга. Последовательный проход с delay=0.2 работает медленнее, зато не требует синхронизации между потоками и не рискует упереться в общий лимит аккаунта.

Сколько стоит Wordstat GetTop API и какие лимиты действуют в 2026 году?

Сами вызовы Wordstat в составе Search API v2 бесплатны — платить придется только за токены LLM-моделей через Model Gallery. Rate limit на практике держится в районе 5-10 запросов в секунду.

Это отличает Search API v2 от старого пути через Direct, где доступ был бесплатным, но с квотами и ограничениями по количеству запросов в сутки на аккаунт. У нового метода жесткого суточного потолка в документации не заявлено, ограничение работает через скорость запросов в секунду, а не через дневной лимит. Цифры стоит сверять на странице тарифов AI Studio перед продакшен-использованием — Yandex меняет условия по мере выхода сервисов из беты.

Лиза: «Для одной ниши собрала 90 листов Excel, полтора миллиона ключей. Он реально собирает реальную частотность, находит запросы, до которых я бы вручную никогда не додумалась. На 30 минут можно отойти — собирает сам.»

Wordstat API или связка Make плюс GPT: что выбрать?

Прямой вызов Python-скриптом дает контроль над форматом и логикой обработки. Связка Make плюс GPT быстрее в настройке для тех, кто не хочет писать код, но менее гибкая при массовых батчах.

В комьюнити вайбкодеров популярен и другой путь: подключить Wordstat к сценарию в Make через HTTP-модуль, а разбор результата отдать модулю GPT — без единой строчки собственного кода. Для разового сбора 500 ключей под одну статью это рабочий вариант, особенно если не хочется разбираться с Python и переменными окружения.

Разница проявляется на масштабе. Скрипт из предыдущего раздела легко встраивается в CI, cron или в агент вроде тех, что собраны в каталоге ИИ-агентов под задачи маркетолога. Сценарий в Make быстрее собрать один раз, но сложнее поддерживать, когда список фраз растет до тысяч и нужна собственная логика ретраев и дедупликации. Если задача — встроить сбор семантики в контентный конвейер портала, код через API дает больше контроля. Если нужно один раз собрать ключи под конкретную статью — no-code сценарий отрабатывает быстрее.

Здесь же стоит смотреть в сторону агента под задачу «SEO-специалист» или «маркетолог» на странице агентов VibeCoderz — там собраны готовые промпт-сетапы под похожие сценарии сбора и разбора семантики.

Частозадаваемые вопросы про Wordstat GetTop API

Нужен ли рекламный аккаунт Яндекс.Директ для Wordstat GetTop API?
Нет. Search API v2 работает через обычный аккаунт Yandex Cloud и API-ключ AI Studio, привязка к рекламному кабинету не нужна.

Что делать, если API отвечает INVALID_ARGUMENT?
В 90% случаев причина — отсутствующий или неверный folderId в теле запроса. Проверьте, что каталог указан именно от сервисного аккаунта, которому выдан ключ.

Почему count в ответе приходит строкой, а не числом?
Это особенность сериализации 64-битных чисел из protobuf в JSON, где такие значения передаются как строки, чтобы не терять точность. Перед вычислениями оборачивайте значение в int().

Можно ли получить историю запросов по датам через GetTop?
Нет, для динамики по времени нужен отдельный метод GetDynamics с параметром period и датами в формате RFC3339.

Сколько фраз можно собрать за один вызов GetTop?
От 1 до 2000, значение задается параметром numPhrases. По умолчанию метод возвращает 50 фраз.

Работают ли операторы Wordstat вроде плюс-слово или квадратные скобки в API?
Нет, операторы точного соответствия из веб-версии Wordstat метод не поддерживает. Для такой точечной работы остается wordstat-2.yandex.ru в браузере.

Платный ли доступ к Wordstat GetTop API в 2026 году?
На момент обновления статьи сами вызовы Wordstat в Search API v2 бесплатны, платить нужно только за токены LLM-моделей в Model Gallery. Актуальные условия стоит проверять на странице тарифов AI Studio перед продакшен-использованием.

Если собираете семантику для статей на постоянной основе, разумно сразу завести пайплайн, а не разбирать JSON руками каждый раз. В каталоге AI-инструментов VibeCoderz собраны IDE и агенты, которые ускоряют такую сборку кода. А если нужна помощь с архитектурой контентного конвейера под конкретный проект, запишитесь на консультацию к Максиму.

Обновлено: октябрь 2026