Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Searching by text description via API v2

Written by
Improved by
Updated at August 14, 2025

With Yandex Search API's API v2, you can search through the Yandex Images index by text description and get search results in XML format. You can run queries using REST API and gRPC API. The search results you get depend on the parameters specified in your query.

Getting started

Sign up for Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or create 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.

Learn more about clouds and folders here.

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. Create a service account you will use to send requests. You can also use a Yandex account or a federated account, but a service account is a better choice for automation purposes.

  2. Assign the search-api.webSearch.user role to the account you will use to send requests.

  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:

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

      body.json

      {
  "query": {
    "searchType": "<search_type>",
    "queryText": "<search_query_text>",
    "familyMode": "<result_filter_setting_value>",
    "page": "<page_number>",
    "fixTypoMode": "<typo_correction_mode_setting_value>"
  },
  "imageSpec": {
    "format": "<image_format>",
    "size": "<image_size>",
    "orientation": "<image_orientation>",
    "color": "<image_color>"
  },
  "site": "<website_domain_name>",
  "docsOnPage": "<results_per_page>",
  "folderId": "<folder_ID>",
  "userAgent": "<User-Agent_header>"
}
      Description of fields

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

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

      • familyMode: 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).

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

      • format: Searching for images of specified format. This is an optional parameter. If not set, the search includes images of all formats. The possible values are:

        • IMAGE_FORMAT_JPEG: JPG
        • IMAGE_FORMAT_GIF: GIF
        • IMAGE_FORMAT_PNG: PNG

      • size: Searching for images of specified size. This is an optional parameter. If not set, the search includes images of all sizes. The possible values are:

        • IMAGE_SIZE_ENORMOUS: Very large images (over 1600 × 1200 in pixels).
        • IMAGE_SIZE_LARGE: Large images (from 800 × 600 to 1600 × 1200 in pixels).
        • IMAGE_SIZE_MEDIUM: Medium images (from 150 × 150 to 800 × 600 in pixels).
        • IMAGE_SIZE_SMALL: Small images (from 32 × 32 to 150 × 150 in pixels).
        • IMAGE_SIZE_TINY: Icons (up to 32 × 32 in pixels).
        • IMAGE_SIZE_WALLPAPER: Wallpaper images.

      • orientation: Searching for images of specified orientation. This is an optional parameter. If not set, the search includes images of any orientation. The possible values are:

        • IMAGE_ORIENTATION_VERTICAL: Vertical images.
        • IMAGE_ORIENTATION_HORIZONTAL: Horizontal images.
        • IMAGE_ORIENTATION_SQUARE: Square aspect ratio images.

      • color: Searching for images with specified color parameters. This is an optional parameter. If not set, the search includes images with any color parameters. The possible values are:

        • IMAGE_COLOR_COLOR: Colored images.
        • IMAGE_COLOR_GRAYSCALE: Grayscale images.
        • IMAGE_COLOR_RED: Images with red as the main color.
        • IMAGE_COLOR_ORANGE: Images with orange as the main color.
        • IMAGE_COLOR_YELLOW: Images with yellow as the main color.
        • IMAGE_COLOR_GREEN: Images with green as the main color.
        • IMAGE_COLOR_CYAN: Images with cyan as the main color.
        • IMAGE_COLOR_BLUE: Images with blue as the main color.
        • IMAGE_COLOR_VIOLET: Images with violet as the main color.
        • IMAGE_COLOR_WHITE: Images with white as the main color.
        • IMAGE_COLOR_BLACK: Images with black as the main color.

      • site: Searching for images only on specified website, e.g., yandex.cloud. This is an optional parameter. If not set, the search includes all websites in the search base.

      • docsOnPage: Number of result groups displayed per search result page. You can specify values between 1 and 60. This is an optional parameter. The default value is 20.

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

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

      Request body example

      body.json

      {
  "query": {
    "searchType": "SEARCH_TYPE_RU",
    "queryText": "cats"
  },
  "folderId": "b1gt6g8ht345********"
}

    2. Send an HTTP request specifying the IAM token you got earlier and a path to the request body file:

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

    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>"
  },
  "image_spec": {
    "format": "<image_format>",
    "size": "<image_size>",
    "orientation": "<image_orientation>",
    "color": "<image_color>"
  },
  "site": "<website_domain_name>",
  "docs_on_page": "<results_per_page>",
  "folder_id": "<folder_ID>",
  "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.

      • format: Searching for images of specified format. This is an optional parameter. If not set, the search includes images of all formats. The possible values are:

        • IMAGE_FORMAT_JPEG: JPG
        • IMAGE_FORMAT_GIF: GIF
        • IMAGE_FORMAT_PNG: PNG

      • size: Searching for images of specified size. This is an optional parameter. If not set, the search includes images of all sizes. The possible values are:

        • IMAGE_SIZE_ENORMOUS: Very large images (over 1600 × 1200 in pixels).
        • IMAGE_SIZE_LARGE: Large images (from 800 × 600 to 1600 × 1200 in pixels).
        • IMAGE_SIZE_MEDIUM: Medium images (from 150 × 150 to 800 × 600 in pixels).
        • IMAGE_SIZE_SMALL: Small images (from 32 × 32 to 150 × 150 in pixels).
        • IMAGE_SIZE_TINY: Icons (up to 32 × 32 in pixels).
        • IMAGE_SIZE_WALLPAPER: Wallpaper images.

      • orientation: Searching for images of specified orientation. This is an optional parameter. If not set, the search includes images of any orientation. The possible values are:

        • IMAGE_ORIENTATION_VERTICAL: Vertical images.
        • IMAGE_ORIENTATION_HORIZONTAL: Horizontal images.
        • IMAGE_ORIENTATION_SQUARE: Square aspect ratio images.

      • color: Searching for images with specified color parameters. This is an optional parameter. If not set, the search includes images with any color parameters. The possible values are:

        • IMAGE_COLOR_COLOR: Colored images.
        • IMAGE_COLOR_GRAYSCALE: Grayscale images.
        • IMAGE_COLOR_RED: Images with red as the main color.
        • IMAGE_COLOR_ORANGE: Images with orange as the main color.
        • IMAGE_COLOR_YELLOW: Images with yellow as the main color.
        • IMAGE_COLOR_GREEN: Images with green as the main color.
        • IMAGE_COLOR_CYAN: Images with cyan as the main color.
        • IMAGE_COLOR_BLUE: Images with blue as the main color.
        • IMAGE_COLOR_VIOLET: Images with violet as the main color.
        • IMAGE_COLOR_WHITE: Images with white as the main color.
        • IMAGE_COLOR_BLACK: Images with black as the main color.

      • site: Searching for images only on specified website, e.g., yandex.cloud. This is an optional parameter. If not set, the search includes all websites in the search base.

      • docs_on_page: Number of result groups displayed per search result page. You can specify values between 1 and 60. This is an optional parameter. The default value is 20.

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

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

      Request body example

      body.json

      {
  "query": {
    "search_type": "SEARCH_TYPE_RU",
    "query_text": "cats"
  },
  "folder_id": "b1gt6g8ht345********"
}

    2. Run a gRPC call specifying the IAM token you got earlier and a path to the request body file:

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

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

  2. Decode the result from Base64:

    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.

See also

Previous
Text search in deferred mode
Next
Searching by image