Getting top results by key phrase

Written by

Updated at February 3, 2026

With Wordstat, you can get the most popular search results by key phrase using a REST method or the GetTop gRPC call.

To complete the steps from this example, create a service account with the search-api.webSearch.user role and get an API key with the yc.search-api.execute scope. You can also use an IAM token as a more secure method. Learn more about authentication in Yandex Search API.

REST API

gRPC API

Create a file with the request body, e.g., body.json:
```
 {
  "phrase": "<key_phrase>",
  "numPhrases": 100,
  "regions": ["213"],
  "devices": ["DEVICE_ALL"],
  "folderId": "<folder_ID>"
}
```
Where:
- phrase: Query key phrase supporting search operators.
- numPhrases: Number of phrases in the response. The default value is 50. The maximum value is 2,000.
- regions: List of region IDs showing where the query originated. For example, 213 stands for Moscow. By default, queries from all regions are taken into account.
- devices: List of device types used to send the query. The possible values are:
  - DEVICE_ALL: All devices.
  - DEVICE_DESKTOP: PCs.
  - DEVICE_PHONE: Mobile phones.
  - DEVICE_TABLET: Tablets.
- folderId: Your service account’s folder ID.

Send an HTTP request specifying the API key or IAM token you got earlier and a path to the request body file:

Authentication with an IAM token:

curl \
  --request POST \
  --header "Authorization: Bearer <IAM_token>" \
  --data "@body.json" \
  "https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests" \
  > result.json

Authentication with an API key:

curl \
  --request POST \
  --header "Authorization: Api-key <API_key>" \
  --data "@body.json" \
  "https://searchapi.api.cloud.yandex.net/v2/wordstat/topRequests" \
  > result.json

The result will be saved to the result.json file.

Response fragment

{
   "totalCount": "48885",
   "results": [
     {
       "phrase": "buy a dog",
       "count": "48885"
     },
  ],
   "associations": [
     {
       "phrase": "how much is a poodle",
       "count": "613"
     }
  ]
}

Create a file with the request body, e.g., body.json:
```
 {
  "phrase": "<key_phrase>",
  "num_phrases": 100,
  "regions": ["213"],
  "devices": ["DEVICE_ALL"],
  "folder_id": "<folder_ID>"
}
```
Where:
- phrase: Query key phrase supporting search operators.
- num_phrases: Number of phrases in the response. The default value is 50. The maximum value is 2,000.
- regions: List of region IDs showing where the query originated. For example, 213 stands for Moscow. By default, queries from all regions are taken into account.
- devices: List of device types used to send the query. The possible values are:
  - DEVICE_ALL: All devices.
  - DEVICE_DESKTOP: PCs.
  - DEVICE_PHONE: Mobile phones.
  - DEVICE_TABLET: Tablets.
- folder_id: Your service account’s folder ID.

Make a gRPC call specifying the API key or IAM token you got earlier and a path to the request body file:

Authentication with an API key:

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

Authentication with an IAM token:

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d @ < body.json \
  searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.WordstatService/GetTop \
  > result.json

The result will be saved to the result.json file.

Response fragment

{
   "totalCount": "48885",
   "results": [
     {
       "phrase": "buy a dog",
       "count": "48885"
     },
  ],
   "associations": [
     {
       "phrase": "how much is a poodle",
       "count": "613"
     }
  ]
}

Getting top results by key phrase

Was the article helpful?