Image search response format
In response to an image search query, Yandex Search API returns a UTF-8 encoded XML file with the search results.
XML files consist of the request (aggregate information on search query parameters) and response (search query handling results) grouping tags.
Currently, image search is only available for queries received via API v1.
Below is the general structure of the resulting XML document with examples of values.
Response structure
<?xml version="1.0" encoding="utf-8"?>
<yandexsearch version="1.0">
<request>
<query>cats</query>
<page>2</page>
<sortby order="descending" priority="no">rlv</sortby>
<maxpassages>1</maxpassages>
<groupings>
<groupby attr="ii" mode="deep" groups-on-page="1" docs-in-group="1" curcateg="-1"/>
</groupings>
</request>
<response date="20240414T091102">
<reqid>1713085862371215-3284531111984749627-balancer-l7leveler-kubr-yp-vla-25-BAL</reqid>
<found priority="phrase">11132</found>
<found priority="strict">11132</found>
<found priority="all">11132</found>
<found-human>11 thousand results found</found-human>
<results>
<grouping attr="ii" mode="deep" groups-on-page="1" docs-in-group="1" curcateg="-1">
<page first="1" last="1">2</page>
<group>
<categ attr="ii" id="3166497932182189502"/>
<doccount>1</doccount>
<relevance priority="all"/>
<doc id="Z37E83657D25C5DED">
<relevance priority="all"/>
<url>https://***.*****.**/big3/989/426616-Kycb.jpg</url>
<domain>***.*****.**</domain>
<modtime>20170920T100608</modtime>
<size>0</size>
<charset>utf-8</charset>
<image-properties>
<id>63966cd66b86c8e11bf80c4c7dc5e431c5cd1b5d-8971534-images-thumbs</id>
<shard>0</shard>
<thumbnail-link>http://avatars.mds.yandex.net/i?id=63966cd66b86c8e11bf80c4c7dc5e431c5cd1b5d-8971534-images-thumbs</thumbnail-link>
<thumbnail-width>480</thumbnail-width>
<thumbnail-height>272</thumbnail-height>
<original-width>480</original-width>
<original-height>272</original-height>
<html-link>https://****.*********.ru/download/kot-kotyara-usy-lapy-hvost-2399/480x272/</html-link>
<image-link>https://****.*********.ru/original/480x272/8/d3/kot-kotyara-usy-lapy-hvost-2399.jpg</image-link>
<file-size>57435</file-size>
<mime-type>jpg</mime-type>
</image-properties>
<mime-type>text/html</mime-type>
<properties/>
</doc>
</group>
<found priority="phrase">8432</found>
<found priority="strict">8432</found>
<found priority="all">8432</found>
<found-docs priority="phrase">8432</found-docs>
<found-docs priority="strict">8432</found-docs>
<found-docs priority="all">8432</found-docs>
<found-docs-human>8 thousand results found</found-docs-human>
</grouping>
</results>
</response>
</yandexsearch>
Response parameters
The request group provides aggregate information about request parameters. It may be missing if there are errors in the response.
request
|
Request group tags |
Description |
Attributes |
|
query |
Search query text |
None |
|
page |
Number of the returned page with search results. Page numbering starts from zero ( |
None |
|
sortby |
Result sorting parameters. Service tag, takes the |
|
|
maxpassages |
Maximum number of text snippets generated for image. Service tag, takes the |
None |
|
groupings |
Grouping tag. It contains grouping parameters in the |
None |
|
groupby |
Parameters for grouping the search results. |
|
response
Results of processing the search query, information about which is provided in the request tag.
It contains the date attribute with the query date and time (UTC) in <year><month><day>Т<hour><minute><second> format.
This group consists of the following sections:
General information about search results
The table below lists the tags used in the appropriate section.
|
Tags for general information about search results |
Description |
Attributes |
|
error |
Error description Used only if a search query is handled incorrectly (e.g., if the query is empty or parameters are incorrect). In some cases, it is mutually exclusive with other tags of the |
|
|
reqid |
Unique query ID |
None |
|
found |
Estimate of the number of images found in response to the query. |
|
|
found-human |
String in the language matching the selected search type. Contains information about the number of found images and related information. |
None |
resultssection
This is an optional tag and only used if any results are found for a query.
The table below lists the tags for this section.
|
|
Description |
Attributes |
|
results |
Grouping tag. Child tags contain information about search parameters and found images. |
None |
|
grouping |
Grouping tag. Child tags contain information about search parameters and found images. |
Attributes reflect the grouping rules for images.
|
|
page |
Number of the returned page with search results. Page numbering starts from zero ( |
|
|
group |
Grouping tag. Each |
None |
|
categ |
Description of the found image |
|
|
doccount |
Service tag |
None |
|
relevance |
Service tag |
|
|
doc |
Grouping tag. Each |
|
|
relevance |
Service tag |
|
|
url |
Image address |
None |
|
domain |
Domain that hosts the document containing the image |
None |
|
modtime |
Image modification date and time (UTC) in |
None |
|
size |
Image size in bytes |
None |
|
charset |
Encoding of the document containing the image |
None |
|
image-properties |
Grouping tag. Contains information about the image properties to include in search results. |
None |
|
id |
Image thumbnail ID |
None |
|
shard |
Number of the shard containing the image information |
None |
|
thumbnail-link |
Image thumbnail address |
None |
|
thumbnail-width |
Width of the image thumbnail in pixels |
None |
|
thumbnail-height |
Height of the image thumbnail in pixels |
None |
|
original-width |
Width of the source (original) image |
None |
|
original-height |
Height of the source (original) image |
None |
|
html-link |
Image page address |
None |
|
image-link |
Image address |
None |
|
file-size |
Image size in bytes |
None |
|
mime-type |
Image format (JPG, GIF, or PNG) |
None |
|
mime-type |
Format of the document containing the image |
None |
|
found |
Estimate of the number of generated groups |
|
|
found-docs |
Estimate of the number of images found in response to the query. It is a more accurate estimate as compared to the value provided in the |
|
|
found-docs-human |
A string in the language matching the selected search type. Contains information about the number of found images and related information. The value being provided must be used when generating search results. |
None |