Получить распределение количества запросов с ключевой фразой по регионам

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

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

Wordstat позволяет получить распределение числа запросов, содержащих заданную фразу, по регионам мира за последние 30 дней с помощью REST-метода или gRPC-вызова GetRegionsDistribution.

Эта функциональность находится на стадии Preview.

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

REST API

gRPC API

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

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

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

curl \
  --request POST \
  --header "Authorization: Bearer <IAM-токен>" \
  --data "@body.json" \
  "https://searchapi.api.yandexcloud.kz/v2/wordstat/regions" \
  > result.json

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

curl \
  --request POST \
  --header "Authorization: Api-key <API-ключ>" \
  --data "@body.json" \
  "https://searchapi.api.yandexcloud.kz/v2/wordstat/regions" \
  > result.json

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

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

{
 "results": [
  {
   "region": "2",
   "count": "117527",
   "share": 0.033340221022570879,
   "affinityIndex": 48.87239354882464
  },
  {
   "region": "213",
   "count": "286666",
   "share": 0.03751625685705634,
   "affinityIndex": 54.99391465808182
  }
 ]
}

Создайте файл с телом запроса (например, body.json):
```
 {
   "phrase": "<ключевая_фраза>",
   "region": "REGION_CITIES",
   "devices": ["DEVICE_PHONE"],
   "folder_id": "<идентификатор_каталога>"
}
```
Где:
- phrase — ключевая фраза запроса, поддерживает поисковые операторы.
- region — уровень детализации распределения. Возможные значения:
  - REGION_CITIES: детализация только по городам.
  - REGION_REGIONS: детализация только по регионам.
  - REGION_ALL: везде, значение по умолчанию.
- devices — список типов устройств, с которых был задан запрос. Возможные значения:
  - DEVICE_ALL: все устройства.
  - DEVICE_DESKTOP: компьютеры.
  - DEVICE_PHONE: телефоны.
  - DEVICE_TABLET: планшеты.
- folder_id — идентификатор каталога вашего сервисного аккаунта.
Выполните gRPC-вызов, указав полученный ранее API-ключ или IAM-токен и путь к файлу с телом запроса:
- Аутентификация с IAM-токеном:
```
grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d @ < body.json \
  searchapi.api.yandexcloud.kz:443 yandex.cloud.searchapi.v2.WordstatService/GetRegionsDistribution \
  > result.json
```
- Аутентификация с API-ключом:
```
grpcurl \
  -rpc-header "Authorization: Api-Key <API-ключ>" \
  -d @ < body.json \
  searchapi.api.yandexcloud.kz:443 yandex.cloud.searchapi.v2.WordstatService/GetRegionsDistribution \
  > result.json
```
Результат будет сохранен в файл result.json.

Ответ содержит массив объектов со следующими параметрами:
- region — идентификатор региона.
- count — количество запросов с указанной фразой в регионе.
- share — доля запросов с фразой от общего числа запросов в регионе
- affinityIndex — индекс соответствия — отношение доли запросов в регионе к их доле по стране.
Фрагмент ответа
```
{
 "results": [
  {
   "region": "2",
   "count": "117527",
   "share": 0.033340221022570879,
   "affinityIndex": 48.87239354882464
  },
  {
   "region": "213",
   "count": "286666",
   "share": 0.03751625685705634,
   "affinityIndex": 54.99391465808182
  }
 ]
}
```

Получить распределение количества запросов с ключевой фразой по регионам

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