Performing search queries in deferred mode using 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

   Note

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

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

   • 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). Documents of the Adult category are excluded from search results unless a query is explicitly made for searching resources of this category.
     • FAMILY_MODE_NONE: Filtering is disabled. Search results include any documents regardless of their contents.
     • FAMILY_MODE_STRICT: Family filter. Regardless of a search query, documents of the Adult category and those with 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 1).

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

     The fix_typo_mode parameter is not supported when getting the result in HTML format.

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

     The sort_mode parameter is not supported when getting the result in HTML format.

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

     The sort_order parameter is not supported when getting the result in HTML format.

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

     The group_mode parameter is not supported when getting the result in HTML format.

   • 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; for HTML, the range is 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.

     The docs_in_group parameter is not supported when getting the result in HTML format.

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

     The max_passages parameter is not supported when getting the result in HTML format.

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

     The l10n parameter is not supported when getting the result in HTML format.

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

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