Getting information about popular search queries
Gets a list of the TOP-3000 search queries the site was shown for in the search results over the past week. You can choose 500 queries with the most displays or with the most clicks.
Request format
GET https://api.webmaster.yandex.net/v4/user/{user-id}/hosts/{host-id}/search-queries/popular
? order_by=<string>
& [query_indicator=<string>]
& [device_type_indicator=<string>]
& [date_from=<datetime>]
& [date_to=<datetime>]
& [offset=<int32>]
& [limit=<int32>]
user-id | Type: int64. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the GET /v4/user method. |
host-id | Type: host id (string). The site ID. To get it, use the GET /v4/user/{user-id}/hosts method. |
user-id | Type: int64. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the GET /v4/user method. |
host-id | Type: host id (string). The site ID. To get it, use the GET /v4/user/{user-id}/hosts method. |
order_by * | Indicator for sorting requests (ApiQueryOrderField). |
query_indicator | Indicators for displaying requests (ApiQueryIndicator). |
device_type_indicator | Device type (ApiDeviceTypeIndicator). Default value: ALL. |
date_from | The start date of the range. If omitted, data is returned for the last week. |
date_to | The end date of the range. If omitted, data is returned for the last week. |
offset | The list offset. The minimum value is 0. Default value: 0. |
limit | Page size (1-500). Default value: 500. |
order_by * | Indicator for sorting requests (ApiQueryOrderField). |
query_indicator | Indicators for displaying requests (ApiQueryIndicator). |
device_type_indicator | Device type (ApiDeviceTypeIndicator). Default value: ALL. |
date_from | The start date of the range. If omitted, data is returned for the last week. |
date_to | The end date of the range. If omitted, data is returned for the last week. |
offset | The list offset. The minimum value is 0. Default value: 0. |
limit | Page size (1-500). Default value: 500. |
* Required
Query sorting order (ApiQueryOrderField)
Indicator | Description |
---|---|
TOTAL_SHOWS | The number of displays. |
TOTAL_CLICKS | The number of clicks. |
Indicator | Description |
---|---|
TOTAL_SHOWS | The number of displays. |
TOTAL_CLICKS | The number of clicks. |
Query indicators (ApiQueryIndicator)
Indicator | Description |
---|---|
TOTAL_SHOWS | The number of displays. |
TOTAL_CLICKS | The number of clicks. |
AVG_SHOW_POSITION | The average position of the display. |
AVG_CLICK_POSITION | Average click position. |
Indicator | Description |
---|---|
TOTAL_SHOWS | The number of displays. |
TOTAL_CLICKS | The number of clicks. |
AVG_SHOW_POSITION | The average position of the display. |
AVG_CLICK_POSITION | Average click position. |
Device type indicators (ApiDeviceTypeIndicator)
Indicator | Description |
---|---|
ALL | All device types. |
DESKTOP | Computers. |
MOBILE_AND_TABLET | Mobile phones and tablets. |
MOBILE | Mobile phones. |
TABLET | Tablets. |
Indicator | Description |
---|---|
ALL | All device types. |
DESKTOP | Computers. |
MOBILE_AND_TABLET | Mobile phones and tablets. |
MOBILE | Mobile phones. |
TABLET | Tablets. |
If the request does not specify a device type indicator, the default value is ALL.
Response format
Examples
{
"queries": [
{
"query_id": "a08b",
"query_text": "some text",
"indicators": {
"TOTAL_SHOWS": 1.1, ...
}
}, ...
],
"date_from": "2016-01-01",
"date_to": "2016-01-07",
"count": "300"
}
<Data>
<query>
<query_id>a08b</query_id>
<query_text>some text</query_text>
<indicators>
<TOTAL_SHOWS>1.1</TOTAL_SHOWS>
...
</indicators>
</query>
...
<date_from>2016-01-01</date_from>
<date_to>2016-01-07</date_to>
<count>300</count>
</Data>
Name | Required | Type | Description | Note |
---|---|---|---|---|
query_id | Yes | string | Search query ID. | — |
query_text | Yes | string | The text of the search query. | — |
TOTAL_SHOWS | Yes | ApiQueryIndicator | Search query indicator. | May be omitted if its value is not defined. |
date_from | Yes | datetime | The start date of the range. | May be later than the one you set in the request, if there is no earlier data for the site. |
date_to | Yes | datetime | The end date of the range. | May be earlier than the one you set in the request, if there is no earlier data for the site. |
count | Yes | int32 | The total number of search queries available. | — |
Name | Required | Type | Description | Note |
---|---|---|---|---|
query_id | Yes | string | Search query ID. | — |
query_text | Yes | string | The text of the search query. | — |
TOTAL_SHOWS | Yes | ApiQueryIndicator | Search query indicator. | May be omitted if its value is not defined. |
date_from | Yes | datetime | The start date of the range. | May be later than the one you set in the request, if there is no earlier data for the site. |
date_to | Yes | datetime | The end date of the range. | May be earlier than the one you set in the request, if there is no earlier data for the site. |
count | Yes | int32 | The total number of search queries available. | — |
Query indicators (ApiQueryIndicator)
Indicator | Description |
---|---|
TOTAL_SHOWS | The number of displays. |
TOTAL_CLICKS | The number of clicks. |
AVG_SHOW_POSITION | The average position of the display. |
AVG_CLICK_POSITION | Average click position. |
Indicator | Description |
---|---|
TOTAL_SHOWS | The number of displays. |
TOTAL_CLICKS | The number of clicks. |
AVG_SHOW_POSITION | The average position of the display. |
AVG_CLICK_POSITION | Average click position. |
Response codes
To view the response structure in detail, click the reason.
Code | Reason | Description |
---|---|---|
200 | OK | |
403 | The ID of the user who issued the token differs from the one specified in the request. In the examples below, | |
404 | HOST_NOT_VERIFIED | Site management rights are not verified. |
HOST_NOT_INDEXED | The Sitemap file is missing. | |
HOST_NOT_LOADED | The site data isn't uploaded to Yandex.Webmaster yet. |
Code | Reason | Description |
---|---|---|
200 | OK | |
403 | The ID of the user who issued the token differs from the one specified in the request. In the examples below, | |
404 | HOST_NOT_VERIFIED | Site management rights are not verified. |
HOST_NOT_INDEXED | The Sitemap file is missing. | |
HOST_NOT_LOADED | The site data isn't uploaded to Yandex.Webmaster yet. |