Image search

{
  "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.

{
  "site": "<website_domain_name>",
  "folder_id": "<folder_ID>",
  "url": "<source_image_URL>",
  "data": "<image_data>",
  "id": "<CBIR_ID>",
  "page": "<page_number>"
}

Description of fields:

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

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

• url: Source image URL.

• data: Source image data, Base64-encoded.

• id: Source image CBIR ID. Specify the ID you got in the response to get the next search result page faster.

  Note

  You can provide only one of these parameters in your query: url, id, or data.

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

{
  "images": [
    {
      "url": "https://cs10.pikabu.ru/post_img/2019/10/29/8/og_og_1572352646221687176.jpg",
      "format": "IMAGE_FORMAT_JPEG",
      "width": "570",
      "height": "960",
      "passage": "This Pin was discovered by Some Dude.",
      "host": "www.pinterest.com",
      "page_title": "How to enrich your cute cats' life? Cute cats, Indoor cat, Cats",
      "page_url": "https://www.pinterest.com/pin/how-to-enrich-your-cute-cats-life--703194929319013467/"
    },
    ...
  ],
  "page": "3",
  "id": "1716254/_KnCt2T9gLh4z8SSv8nVqQ7277"
}

Description of fields:

• images: Array of objects with information about found images:

  • url: Image URL.

  • format: Image format:

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

  • width: Image width in pixels.

  • height: Image height in pixels.

  • passage: Text snippet describing the image.

  • host: Domain hosting the document containing the image.

  • page_title: Image page title.

  • page_url: Image page URL.

• page: Current search results page number.

• id: Source image CBIR ID.