Получить топ результатов по ключевой фразе

Статья создана

Обновлена 19 января 2026 г.

Wordstat позволяет получить самые популярные результаты поиска по ключевой фразе с помощью вызова GetTop.

Чтобы воспользоваться примером, создайте сервисный аккаунт с ролью search-api.webSearch.user и получите для него API-ключ с областью действия yc.search-api.execute. Также вы можете использовать IAM-токен как более безопасный способ. Подробнее об аутентификации в Yandex Search API.

gRPC API

Создайте файл с телом запроса (например, body.json):
```
 {
  "phrase": "<ключевая_фраза>",
  "numPhrases": 100,
  "regions": ["213"],
  "devices": ["DEVICE_ALL"],
  "folderId": "<идентификатор_каталога>"
}
```
Где:
- phrase — ключевая фраза запроса, поддерживает поисковые операторы.
- numPhrases — количество фраз в ответе. Значение по умолчанию — 50, максимальное значение — 2000.
- regions — список идентификаторов регионов, откуда был задан запрос, например, 213 — Москва. По умолчанию учитываются запросы из любого региона.
- devices — список типов устройств, с которых был задан запрос. Возможные значения:
  - DEVICE_ALL: все устройства.
  - DEVICE_DESKTOP: компьютеры.
  - DEVICE_PHONE: телефоны.
  - DEVICE_TABLET: планшеты.
- folderId — идентификатор каталога вашего сервисного аккаунта.

Выполните gRPC-вызов, указав полученный ранее API-ключ или IAM-токен и путь к файлу с телом запроса:

Аутентификация с API-ключом:

grpcurl \
  -rpc-header "Authorization: Api-Key <API-ключ>" \
  -d @ < body.json \
  searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.WordstatService/GetTop \
  > result.json

Аутентификация с IAM-токеном:

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d @ < body.json \
  searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.WordstatService/GetTop \
  > result.json

Результат будет сохранен в файл result.json.

Фрагмент ответа

{
  "totalCount": "123456",
  "results": [
    { "phrase": "купить собаку", "count": "1000" }
  ],
  "associations": [
    { "phrase": "цены на собак", "count": "900" }
  ]
}

Получить топ результатов по ключевой фразе

Была ли статья полезна?