Getting top results by key phrase

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

Note

This feature is currently in Preview.

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.

  1. 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: Key phase of the query. Supports 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.

  2. 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"
             }
          ]
        }

  1. 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.

  2. 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"
             }
          ]
        }
Previous
Mobile search results
Next
Query change dynamics