Performing search queries 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

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

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

   • 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 values range from 1 to 100. The default value is 20.

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

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": "<query_ID>"}' \
  operation.api.cloud.yandex.net:443 yandex.cloud.operation.OperationService/Get

Where:

• <IAM_token>: Previously obtained IAM token.
• <query_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>"
  }
}