GET requests

Search API allows you to search for images using the Yandex Images index with set parameters and get search results in XML format. You can transmit search parameters to the service in an HTTP request using the GET method. Search API generates a response as an XML document.

To use the search, when signing up for the service, specify the list of IP addresses you will use to run queries to the service and select the appropriate search type. Based on the selected search type, specify the appropriate domain name in your query:

• yandex.ru: For the Russian search type
• yandex.com.tr: For the Turkish search type
• yandex.com: For the International search type

To run a query, you need a service account with the search-api.executor role and a relevant API key you created.

Request formatRequest format

https://yandex.<domain>/images-xml
  ? [folderid=<folder_ID>]
  & [apikey=<API_key>]
  & [text=<search_query_text>]
  & [groupby=<result_grouping_settings>]
  & [p=<page_number>]
  & [fyandex=<family_search_filter>]
  & [site=<website_domain_name>]
  & [itype=<image_format>]
  & [iorient=<image_orientation_type>]
  & [isize=<image_size>]
  & [icolor=<image_color>]

Request parametersRequest parameters

• folderid: Folder ID of the service account you will use to send requests. This is a required parameter.

• apikey: Service account API key. This is a required parameter.

• text: Search query text, e.g., funny+cats. This is a required parameter.

  Warning

  Special characters provided as parameter values should be replaced with the respective escaped sequences based on percent-encoding. For example, use %3D instead of the equals sign (=), and + instead of a space.

• groupby: Result grouping settings. The groups-on-page parameter sets the number of result groups displayed per search results page. This is an optional parameter. If the parameter is not specified, the default value is 20. One result group contains one document.
  For example, to display five result groups per page, specify groupby=attr=ii.groups-on-page=5.

• p: Number of the requested search results page. Page numbering starts from zero (the 0 value stands for page 1). This is an optional parameter. By default, the first page with search results is returned.

• fyandex: Using the Family search filter when generating a search response. This is an optional parameter. If the parameter is not set, the filter is not used. The possible values include:

  • 0: Family Search filter disabled.
  • 1: Family Search filter enabled.

• site: Searching for images only on the specified website. For example, to search only the somepics.ru website, specify site=somepics.ru. This is an optional parameter. If the parameter is not set, the search is performed on all websites in the search base.

• itype: Searching for images in a specified format. This is an optional parameter. If the parameter is not set, the search is performed for images in all formats. The possible values include:

  • jpg: Searching for images in JPG format.
  • gif: Searching for images in GIF format.
  • png: Searching for images in PNG format.

• iorient: Searching for images with a specified image orientation. This is an optional parameter. If the parameter is not set, the search is performed for images with any image orientation. The possible values include:

  • horizontal: Searching for images with the horizontal image orientation.
  • vertical: Searching for images with the vertical image orientation.
  • square: Searching for images with equal sides (square).

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

  • enormous: Searching for very large images (larger than 1600 × 1200 pixels).
  • large: Searching for large images (from 800 × 600 to 1600 × 1200 pixels).
  • medium: Searching for medium images (from 150 × 150 to 800 × 600 pixels).
  • small: Searching for small images (from 32 × 32 to 150 × 150 pixels).
  • tiny: Searching for icons (up to 32 × 32 pixels).
  • wallpaper: Searching for desktop wallpapers.

• icolor: Searching for images with a specified color. This is an optional parameter. If the parameter is not set, the search is performed for images with any colors. The possible values include:

  • gray: Black and white
  • color: Colored
  • red: Red
  • orange: Orange
  • yellow: Yellow
  • green: Green
  • cyan: Cyan
  • blue: Blue
  • violet: Violet
  • white: White
  • black: Black

Search query exampleSearch query example

The following query will return the third page of image search results for the funny cats query. The search type is Russian (yandex.ru). The service will return results for medium-sized color images found on somepics.ru in JPG format with the horizontal image orientation. The Family search filter will be applied to the search results. The page will contain three groups of search results.

https://yandex.ru/images-xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&text=funny+cats&groupby=attr=ii.groups-on-page=3&p=2&fyandex=1&site=somepics.ru&itype=jpg&iorient=horizontal&isize=medium&icolor=color

See alsoSee also

• Image search response format
• Performing search queries in Search API