Image search response format
In response to an image search query, Search API returns an XML file encoded in UTF-8 containing the search results.
XML files consist of the request (aggregate information on search query parameters) and response (search query handling results) grouping tags.
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,000 responses 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,000 responses 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
|
|
Description |
Attributes |
|
query |
Text of the sent search query |
N/A |
|
page |
Number of the returned page with search results. Page numbering starts from zero (the |
N/A |
|
sortby |
Result sorting parameters. Service tag, sets to |
|
|
maxpassages |
Maximum number of text snippets generated for each image. Service tag, sets to |
Missing |
|
groupings |
Grouping tag. Contains grouping parameters in the |
Missing |
|
groupby |
Parameters for grouping found 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>T<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, the tag is mutually exclusive with other tags of the |
|
|
reqid |
Unique ID of the query |
Missing |
|
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. |
Missing |
results
This section is optional 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. |
Missing |
|
grouping |
Grouping tag. Child tags contain information about search parameters and found images. |
Attributes show rules for grouping the found images.
|
|
page |
Number of the returned page with search results. Page numbering starts from zero (the |
|
|
group |
Grouping tag. Each |
Missing |
|
categ |
Description of the found image |
|
|
doccount |
Service tag |
Missing |
|
relevance |
Service tag |
|
|
doc |
Grouping tag. Each |
|
|
relevance |
Service tag |
|
|
url |
Image address |
Missing |
|
domain |
Domain that hosts the document containing the image |
Missing |
|
modtime |
Date and time the image was modified in |
Missing |
|
size |
Image size in bytes |
Missing |
|
charset |
Encoding of the document containing the image |
Missing |
|
image-properties |
Grouping tag. Contains information about the image properties to include in search results. |
Missing |
|
id |
Image thumbnail ID |
Missing |
|
shard |
Number of the shard containing the image information |
Missing |
|
thumbnail-link |
Image thumbnail address |
Missing |
|
thumbnail-width |
Width of the image thumbnail in pixels |
Missing |
|
thumbnail-height |
Height of the image thumbnail in pixels |
Missing |
|
original-width |
Width of the source (original) image |
Missing |
|
original-height |
Height of the source (original) image |
Missing |
|
html-link |
Image page address |
Missing |
|
image-link |
Image address |
Missing |
|
file-size |
Image size in bytes |
Missing |
|
mime-type |
Image format (JPG, GIF, or PNG) |
Missing |
|
mime-type |
Format of the document containing the image |
Missing |
|
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 |
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. |
Missing |