Performing search queries using API v2 in synchronous mode

With Yandex Search API's API v2, you can perform text search through the Yandex search database and get search results in XML or HTML format in synchronous mode. You can run queries using the gPRC API. The search results you get depend on the parameters specified in your query.

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 gRPCurl and jq.

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.

Send a search query

1. Send a query and get a Base64-encoded result:

   gRPC API

   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 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.WebSearchService/Search \
        > result.json
      

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

2. Depending on the requested response format, decode the result from Base64:

   XML

   HTML

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

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

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

   The HTML response to the query will be saved to a file named result.html.

See also

• Performing search queries in deferred mode using API v2
• Text search with API v2
• Authentication with the API v2
• XML format of response to a text search query
• HTML format of response to a text search query