Contact UsGet started

How to get started with the Yandex Search API using API v2

Written by
Updated at May 7, 2025

API v2 is the latest and most recommended interface for Yandex Search API. API v2 is fully integrated into the Yandex Cloud ecosystem and supports both API key authentication as well as the more secure authentication based on short-lived IAM tokens.

Getting started

Sign up in Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or register a new account.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

To use the examples, install the cURL and jq utilities, plus gRPCurl if you are going to use gRPC API.

Get your cloud ready

  1. For authenticating with the API v2 as a service account, create a service account.

  2. Assign the search-api.webSearch.user role to the user or service account you will use to run queries.

  3. Get an IAM token, which is required for authentication.

    The following examples use IAM token authentication. To use a service account's API key for authentication, edit the Authorization header in the query examples. For more information, see Authentication with the API v2.

Create a search query

This request example returns the fifth page of search results for the Yandex query. Search type: Russian. Search region: Novosibirsk Oblast. Notification language: Russian. The family filter will be applied to the search results. The number of passages is three. The results are grouped by domain and sorted by relevance. Each group contains three documents, and the number of groups returned per page is five.

For more information about the request body parameters, see Query body format.

  1. Create a file with the request body, e.g., body.json, specify the ID of the folder you are going to use to work with Yandex Search API in the folderId field:

    body.json

    {
    "query": {
      "searchType": "SEARCH_TYPE_RU",
      "queryText": "Yandex”,
      "familyMode": "FAMILY_MODE_STRICT",
      "page": "4"
    },
    "sortSpec": {
      "sortMode": "SORT_MODE_BY_RELEVANCE",
      "sortOrder": "SORT_ORDER_DESC"
    },
    "groupSpec": {
      "groupMode": "GROUP_MODE_DEEP",
      "groupsOnPage": "5",
      "docsInGroup": "3"
    },
    "maxPassages": "3",
    "region": "65",
    "l10N": "LOCALIZATION_RU",
    "folderId": "<folder_ID>"
}

  2. Run an http request by specifying the IAM token you got earlier:

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

    Result:

    {
 "done": false,
 "id": "sppger465oq1********",
 "description": "WEB search async",
 "createdAt": "2024-10-02T19:51:02Z",
 "createdBy": "bfbud0oddqp4********",
 "modifiedAt": "2024-10-02T19:51:03Z"
}

  1. Create a file with the request body, e.g., body.json, specify the ID of the folder you are going to use to work with Yandex Search API in the folderId field:

    body.json

    {
    "query": {
      "search_type": "SEARCH_TYPE_RU",
      "query_text": "Yandex”,
      "family_mode": "FAMILY_MODE_STRICT",
      "page": "4"
    },
    "sort_spec": {
      "sort_mode": "SORT_MODE_BY_RELEVANCE",
      "sort_order": "SORT_ORDER_DESC"
    },
    "group_spec": {
      "group_mode": "GROUP_MODE_DEEP",
      "groups_on_page": "5",
      "docs_in_group": "3"
    },
    "max_passages": "3",
    "region": "65",
    "l10n": "LOCALIZATION_RU",
    "folder_id": "<folder_ID>"
}

  2. Run an gRPC call by specifying the IAM token you got earlier:

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

    Result:

    {
  "id": "spp3gp3vhna6********",
  "description": "WEB search async",
  "createdAt": "2024-10-02T19:14:41Z",
  "createdBy": "bfbud0oddqp4********",
  "modifiedAt": "2024-10-02T19:14:42Z"
}

Save the obtained Operation object ID (id value) for later use.

Make sure the request was executed successfully

Wait until Yandex Search API executes the request and generates a response. This may take from five minutes to a few hours.

Make sure the request was executed successfully:

Run an http request:

curl \
  --request GET \
  --header "Authorization: Bearer <IAM_token>" \
  https://operation.api.cloud.yandex.net/operations/<request_ID>

Where:

  • <IAM_token>: Previously obtained IAM token.
  • <request_ID>: The Operation object ID you saved at the previous step.

Result:

{
 "done": true,
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.searchapi.v2.WebSearchResponse",
  "rawData": "<Base64_encoded_XML_response_body>"
 },
 "id": "spp82pc07ebl********",
 "description": "WEB search async",
 "createdAt": "2024-10-03T08:07:07Z",
 "createdBy": "bfbud0oddqp4********",
 "modifiedAt": "2024-10-03T08:12:09Z"
}

Run this gRPC call:

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{"operation_id": "<request_ID>"}' \
  operation.api.cloud.yandex.net:443 yandex.cloud.operation.OperationService/Get

Where:

  • <IAM_token>: Previously obtained IAM token.
  • <request_ID>: The Operation object ID you saved at the previous step.

Result:

{
  "id": "spp82pc07ebl********",
  "description": "WEB search async",
  "createdAt": "2024-10-03T08:07:07Z",
  "createdBy": "bfbud0oddqp4********",
  "modifiedAt": "2024-10-03T08:12:09Z",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.searchapi.v2.WebSearchResponse",
    "rawData": "<Base64_encoded_XML_response_body>"
  }
}

If the done field is set to true and the response object is present in the output, the request has been completed successfully, so you can move on to the next step. Otherwise, repeat the check later.

Get a response

After Yandex Search API has successfully processed the request:

  1. Get the result:

    curl \
  --request GET \
  --header "Authorization: Bearer <IAM_token>" \
  https://operation.api.cloud.yandex.net/operations/<request_ID> \
  > result.json

    grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{"operation_id": "<request_ID>"}' \
  operation.api.cloud.yandex.net:443 yandex.cloud.operation.OperationService/Get \
  > result.json

    Eventually the search request result will be saved to a file named result.json containing a Base64-encoded XML response in the response.rawData field.

  2. Decode the result from Base64:

    echo "$(< result.json)" | \
  jq -r .response.rawData | \
  base64 --decode > result.xml

    The XML response to the request will be saved to a file named result.xml.

See also

Previous
Getting started with API v1
Next
All guides