Яндекс Wordstat. Руководство разработчика

Яндекс Wordstat — формат ответа

Яндекс Wordstat возвращает результаты только в формате JSON. Структура ответа зависит от значения параметра pagetype.

Поддерживаются четыре типа ответов:

• words — топ запросов по ключевой фразе;
• history — динамика частотности;
• regions — распределение запросов по регионам;
• regionsTree — дерево поддерживаемых регионов.

Топ запросов по ключевой фразе

Для запроса с параметром pagetype=words возвращаются популярные поисковые запросы за последние 30 дней, содержащие заданную фразу, а также похожие запросы пользователей.

Пример ответа

{
    "totalCount": "1539274",
    "results": [
        {
            "phrase": "пластиковые окна",
            "count": "251340"
        },
        {
            "phrase": "купить окна",
            "count": "98420"
        }
    ],
    "associations": [
        {
            "phrase": "остекление балкона",
            "count": "46750"
        },
        {
            "phrase": "оконные конструкции",
            "count": "21480"
        }
    ]
}

Описание полей

Поле	Тип	Описание
totalCount	string	Общее количество запросов, содержащих все слова из заданной фразы независимо от их порядка.
results	array	Список популярных запросов, содержащих заданное слово или словосочетание.
associations	array	Список запросов, похожих по смыслу на заданную фразу.
phrase	string	Поисковая фраза.
count	string	Количество запросов по данной фразе за последние 30 дней.

Количество элементов в массиве results зависит от параметра groupby. Максимально можно получить до 2000 фраз за один запрос.

Динамика частотности

Для запроса с параметром pagetype=history возвращается изменение частотности заданной фразы за выбранный период.

Данные группируются по дням, неделям или месяцам в зависимости от значения параметра period.

Пример ответа

{
    "results": [
        {
            "date": "2026-01-01T00:00:00Z",
            "count": "185420",
            "share": "0.000142"
        },
        {
            "date": "2026-02-01T00:00:00Z",
            "count": "192870",
            "share": "0.000148"
        },
        {
            "date": "2026-03-01T00:00:00Z",
            "count": "211530",
            "share": "0.000157"
        }
    ]
}

Описание полей

Поле	Тип	Описание
results	array	Список значений частотности за выбранный период.
date	string	Дата начала соответствующего периода в формате RFC 3339.
count	string	Количество запросов, содержащих заданное слово или словосочетание.
share	string	Доля таких запросов от общего количества запросов к поиску Яндекса за указанный период.

Значение поля date зависит от выбранной группировки. При группировке по месяцам указывается начало месяца, по неделям — начало недели, по дням — соответствующая дата.

Распределение запросов по регионам

Для запроса с параметром pagetype=regions возвращается распределение количества запросов по регионам за последние 30 дней.

Пример ответа

{
    "results": [
        {
            "region": "213",
            "count": "68420",
            "share": "0.084",
            "affinityIndex": "132.7"
        },
        {
            "region": "2",
            "count": "32180",
            "share": "0.039",
            "affinityIndex": "108.4"
        }
    ]
}

Описание полей

Поле	Тип	Описание
results	array	Список регионов и показателей частотности.
region	string	Идентификатор региона Яндекса.
count	string	Количество запросов с заданным словом или фразой в указанном регионе.
share	string	Доля выбранных запросов от общего количества поисковых запросов в данном регионе.
affinityIndex	string	Индекс региональной популярности запроса. Показывает отношение доли выбранных запросов в регионе к их доле по всей стране.

Индекс региональной популярности

Поле affinityIndex помогает определить, насколько запрос популярен в конкретном регионе по сравнению со средним значением по стране.

• значение около 100 — популярность примерно соответствует среднему уровню;
• значение выше 100 — запрос в регионе популярнее среднего;
• значение ниже 100 — запрос менее популярен, чем в среднем по стране.

Дерево поддерживаемых регионов

Для запроса с параметром pagetype=regionsTree возвращается иерархический список регионов, поддерживаемых Яндекс Wordstat.

Пример ответа

{
    "regions": [
        {
            "id": "225",
            "label": "Россия",
            "children": [
                {
                    "id": "1",
                    "label": "Москва и область",
                    "children": [
                        {
                            "id": "213",
                            "label": "Москва",
                            "children": []
                        }
                    ]
                }
            ]
        }
    ]
}

Описание полей

Поле	Тип	Описание
regions	array	Список регионов верхнего уровня.
id	string	Идентификатор региона.
label	string	Название региона.
children	array	Вложенный список дочерних регионов. Каждый элемент имеет такую же структуру: id, label и children.

Значения поля id можно использовать в параметре regions при запросах топа фраз и динамики частотности.

Типы данных в JSON

Числовые показатели в ответах Wordstat передаются в виде строк. Например:

{
    "count": "251340",
    "share": "0.000142",
    "affinityIndex": "132.7"
}

При выполнении математических операций значения необходимо предварительно преобразовать в числовой тип средствами используемого языка программирования.

Пустые результаты

Если по заданной фразе отсутствуют подходящие данные, соответствующий массив может быть пустым.

{
    "totalCount": "0",
    "results": [],
    "associations": []
}

Пустой массив не является ошибкой и означает, что Яндекс Wordstat не вернул данные по заданным условиям.

Дополнительная документация

Правила формирования запросов и примеры использования разных типов статистики описаны в разделе Формат запроса.

Полный список параметров и допустимых значений находится в разделе Таблица параметров.

Возможные ошибки и способы их исправления представлены в разделе Коды ошибок.