Performing text search queries in deferred mode via API v2

1. Create a file with the request body, e.g., body.json:

   body.json

   {
       "query": {
         "search_type": "<search_type>",
         "query_text": "<search_query_text>",
         "family_mode": "<result_filter_setting_value>",
         "page": "<page_number>",
         "fix_typo_mode": "<typo_correction_mode_setting_value>"
       },
       "sort_spec": {
         "sort_mode": "<result_sorting_rule>",
         "sort_order": "<sort_order_of_results>"
       },
       "group_spec": {
         "group_mode": "<result_grouping_method>",
         "groups_on_page": "<number_of_groups_per_page>",
         "docs_in_group": "<number_of_documents_per_group>"
       },
       "max_passages": "<maximum_number_of_passages>",
       "region": "<region_ID>",
       "l10n": "<notification_language>",
       "folder_id": "<folder_ID>",
       "response_format": "<result_format>",
       "user_agent": "<User-Agent_header>"
   }
   

   Description of fields

   • search_type: Search type. The possible values are:

     • SEARCH_TYPE_RU: For the Russian search type.
     • SEARCH_TYPE_TR: For the Turkish search type.
     • SEARCH_TYPE_COM: For the International search type.
     • SEARCH_TYPE_KK: For the Kazakh search type.
     • SEARCH_TYPE_BE: For the Belarusian search type.
     • SEARCH_TYPE_UZ: For the Uzbek search type.

   • query_text: Search query text. The maximum length is 400 characters.

   • family_mode: Results filtering. This is an optional parameter. The possible values are:

     • FAMILY_MODE_MODERATE: Moderate filter (default). Adult category documents are excluded from search results unless the query explicitly targets resources of this category.
     • FAMILY_MODE_NONE: Filtering is off. Search results include any documents regardless of their contents.
     • FAMILY_MODE_STRICT: Family filter. Regardless of the search query, Adult category documents and documents containing profanity are excluded from search results.

   • page: Requested page number. This is an optional parameter. By default, the first page with search results is returned. Page numbering starts from zero (0 stands for page one).

   • fix_typo_mode: Search query typo correction setting. This is an optional parameter. The possible values are:

     • FIX_TYPO_MODE_ON: Typo correction enabled (default). Search query typos are corrected automatically.
     • FIX_TYPO_MODE_OFF: Typo correction disabled. Search query typos are not corrected. The search is performed strictly as per the query.

   • sort_mode: Search results sorting mode rule. This is an optional parameter. The possible values are:

     • SORT_MODE_BY_RELEVANCE: Sorting by relevance (default).
     • SORT_MODE_BY_TIME: Sorting by document update time.

   • sort_order: Search results sorting order. This is an optional parameter. The possible values are:

     • SORT_ORDER_DESC: Forward sorting order from most recent to oldest (default).
     • SORT_ORDER_ASC: Reverse sorting order from oldest to most recent.

   • group_mode: Result grouping method. This is an optional parameter. The possible values are:

     • GROUP_MODE_DEEP: Grouping by domain. Each group contains documents from one domain (default).
     • GROUP_MODE_FLAT: Flat grouping. Each group contains a single document.

   • groups_on_page: Maximum number of groups that can be returned per page. This is an optional parameter. The default value is 20.

     When getting the result in XML format, the possible values range from 1 to 100, while for HTML format, from 5 to 50.

   • docs_in_group: Maximum number of documents that can be returned per group. This is an optional parameter. The values range from 1 to 3. The default value is 1.

   • max_passages: Maximum number of passages that can be used when generating a document snippet. This is an optional parameter. The values range from 1 to 5. By default, a maximum of four passages with search query text is returned per document.

   • region: Search country or region ID that affects the document ranking rules. Only supported for the Russian and Turkish search types.

     For a list of frequently used country and region IDs, see Search regions.

   • l10n: Search response notifications language. Affects the text in the found-docs-human tag and error messages. This is an optional parameter. Possible values depend on the selected search type:

     • Russian:
       • LOCALIZATION_RU: Russian (default).
       • LOCALIZATION_BE: Belarusian.
       • LOCALIZATION_KK: Kazakh.
       • LOCALIZATION_UK: Ukrainian.
     • Turkish:
       • LOCALIZATION_TR: Turkish.
     • International:
       • LOCALIZATION_EN: English.

   • folder_id: Folder ID of the user or service account you will use for queries.

   • response_format: Search results format. This is an optional parameter. The possible values are:

     • FORMAT_XML: The results will be delivered in XML format (default).
     • FORMAT_HTML: The results will be delivered in HTML format.

   • user_agent: String containing the User-Agent header. Use this parameter to have your search results optimized for a specific device and browser, including mobile search results. This is an optional parameter. If not specified, you will get the default output.

   List of supported parameters:

   Note

   The list of supported request parameters depends on the required output format, XML or HTML.

   Parameter	Supported in XML response	Supported in HTML response
   search_type
   query_text
   family_mode
   page
   fix_typo_mode
   sort_mode
   sort_order
   group_mode
   groups_on_page
   docs_in_group
   max_passages
   region
   l10n
   folder_id
   response_format
   user_agent

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

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>"
  }
}