Структура API
API Вордстата включает в себя следующие методы:
/v1/getRegionsTree;/v1/topRequests;/v1/dynamics;/v1/regions.
Запросы расходуют общую квоту на запросы к сервису, а также персональную квоту на число запросов в секунду.
Запросы выполняются HTTP-методом POST. Параметры передаются в теле запроса в формате JSON. Для корректной обработки тела запроса нужно использовать заголовок Content-type: application/json. В параметре phrase можно использовать язык запросов.
Метод /v1/getRegionsTree
Метод /v1/getRegionsTree возвращает JSON-объект, описывающий множество регионов, которые поддерживает Вордстат. Другие методы API принимают список идентификаторов регионов из этого метода.
Без параметров.
Не расходует дневную квоту на запросы.
Метод /v1/topRequests
Метод /v1/topRequests возвращает данные за последние 30 дней о популярных запросах, которые содержат указанную фразу, и о запросах, которые похожи на заданный.
|
Параметр |
Описание |
Обязательный |
|
|
Фраза |
Да |
|
|
Количество фраз в ответе. Значение по умолчанию — |
Нет |
|
|
Список идентификаторов регионов, откуда был задан запрос. Допустимые значения можно получить из метода |
Нет |
|
|
Список типов устройств, с которых был задан запрос. Возможные значения:
Значение по умолчанию — |
Нет |
Пример запроса:
curl -XPOST -H 'Content-type: application/json;charset=utf-8' -H 'Authorization: Bearer <oauth-token>' -d '{"phrase":"яндекс","regions":[213,2],"devices":["phone"]}' https:// api.wordstat.yandex.net/v1/topRequests
Формат ответа: массив topRequests, состоящий из пар (phrase: фраза, count: количество заданных запросов). totalCount— общее число запросов, которые содержат все введенные слова в любом порядке.
Пример ответа
{
totalCount": 8275401
"topRequests": [
{
"phrase": "яндекс",
"count": 8275401
},
{
"phrase": "яндекс игры",
"count": 632440
},
{
"phrase": "яндекс карты",
"count": 579075
},
{
"phrase": "яндекс маркет",
"count": 539802
},
{
"phrase": "яндекс почта",
"count": 377566
}
]
}
Метод использует одну единицу дневной квоты на запросы.
Метод /v1/dynamics
Метод /v1/dynamics возвращает динамику числа запросов во времени по заданной фразе.
|
Параметр |
Описание |
Обязательный |
|
|
Фраза. В этом методе в параметре |
Да |
|
|
Период агрегации количества запросов. Возможные значения:
|
Да |
|
|
Начало периода, за который запрашиваются данные, в формате YYYY-MM-DD. При детализации по дням доступны данные за последние 60 дней. Для детализации по неделям и месяцам доступны данные с 01.01.2018 г. |
Да |
|
|
Конец периода, за который запрашиваются данные, в формате YYYY-MM-DD.
|
Нет |
|
|
Список идентификаторов регионов, откуда был задан запрос. Допустимые значения можно получить из метода |
Нет |
|
|
Список типов устройств, с которых был задан запрос. Возможные значения:
Значение по умолчанию — |
Нет |
Пример запроса:
{"phrase":"яндекс","period":"weekly","fromDate":"2025-02-03","toDate":"2025-04-06","regions":[213,2],"devices":["phone"]}
Формат ответа: массив dynamics, в котором дата (date), общее число запросов, содержащих заданную фразу (count), и доля числа таких запросов от общего числа запросов к Яндексу.
Пример ответа
{
"dynamics": [
{
"date": "2025-02-03",
"count": 1910301,
"share": 0.6030092668804485
},
{
"date": "2025-02-10",
"count": 1926557,
"share": 0.6092331204174273
},
{
"date": "2025-02-17",
"count": 1905623,
"share": 0.6088345666509491
},
{
"date": "2025-02-24",
"count": 1897645,
"share": 0.6019076028335435
},
{
"date": "2025-03-03",
"count": 1879813,
"share": 0.6006963056742451
},
{
"date": "2025-03-10",
"count": 1931583,
"share": 0.5929364330818319
},
{
"date": "2025-03-17",
"count": 1933021,
"share": 0.585401132607149
},
{
"date": "2025-03-24",
"count": 1953561,
"share": 0.593108598108686
},
{
"date": "2025-03-31",
"count": 1909107,
"share": 0.5748788349658039
}
]
}
Метод использует одну единицу дневной квоты на запросы.
Метод /v1/regions
Метод /v1/regions возвращает распределение числа запросов, содержащих заданную фразу, по регионам мира за последние 30 дней.
|
Параметр |
Описание |
Обязательный |
|
|
Фраза |
Да |
|
|
Показывать распределение запросов только по городам, только по областям, или везде. Возможные значения:
Значение по умолчанию — |
Нет |
|
|
Список типов устройств, с которых был задан запрос. Возможные значения:
Значение по умолчанию — |
Нет |
Пример запроса:
{"phrase":"яндекс","regionType":"cities","devices":["phone"]}
Формат ответа: массив regions, в котором идентификатор региона (regionId), число запросов, содержащих заданную фразу в этом регионе (count), доля от всех запросов к Яндексу в регионе (share) и индекс интереса (в процентах): отношение отобранных запросов в регионе к их доле по стране (affinityIndex).
Пример ответа
{
"regions": [
{
"regionId": 2,
"count": 2330855,
"share": 0.5818950367758946,
"affinityIndex": 123.75386731541778
},
{
"regionId": 4,
"count": 113869,
"share": 0.48076034011126784,
"affinityIndex": 102.24516034763612
},
{
"regionId": 11268,
"count": 3160,
"share": 0.24667996864978625,
"affinityIndex": 52.46238269843529
},
{
"regionId": 5,
"count": 126737,
"share": 0.5177023552746863,
"affinityIndex": 110.10176154538539
},
{
"regionId": 6,
"count": 141108,
"share": 0.5302251202210722,
"affinityIndex": 112.7650263846661
},
{
"regionId": 11270,
"count": 2763,
"share": 0.19726428773884294,
"affinityIndex": 41.95295877786469
},
{
"regionId": 21510,
"count": 12568,
"share": 0.5833962313197623,
"affinityIndex": 124.0731321632944
}
]
}
Метод использует две единицы дневной квоты на запросы.