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.

  1. Request format
  2. Response format
  3. Response codes

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-idType: int64. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the GET /v4/user method.
host-idType: host id (string). The site ID. To get it, use the GET /v4/user/{user-id}/hosts method.
user-idType: int64. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the GET /v4/user method.
host-idType: 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"
}
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

INVALID_USER_ID

The ID of the user who issued the token differs from the one specified in the request. In the examples below, {user_id} shows the correct uid of the OAuth token owner.

{
  "error_code": "INVALID_USER_ID",
  "available_user_id": 1,
  "error_message": "Invalid user id. {user_id} should be used."
}
404 HOST_NOT_VERIFIED
Site management rights are not verified.
{
  "error_code": "HOST_NOT_VERIFIED",
  "host_id": "http:ya.ru:80",
  "error_message": "some string"
}
HOST_NOT_INDEXED
The Sitemap file is missing.
{
  "error_code": "HOST_NOT_INDEXED", //errorCode. 
  "host_id": "http:ya.ru:80", //id хоста. host id. 
  "error_message": "some string" //Error message. 
}
HOST_NOT_LOADED

The site data isn't uploaded to Yandex.Webmaster yet.

{
  "error_code": "HOST_NOT_LOADED",
  "host_id": "http:ya.ru:80",
  "error_message": "some string"
}
Code Reason Description
200 OK
403

INVALID_USER_ID

The ID of the user who issued the token differs from the one specified in the request. In the examples below, {user_id} shows the correct uid of the OAuth token owner.

{
  "error_code": "INVALID_USER_ID",
  "available_user_id": 1,
  "error_message": "Invalid user id. {user_id} should be used."
}
404 HOST_NOT_VERIFIED
Site management rights are not verified.
{
  "error_code": "HOST_NOT_VERIFIED",
  "host_id": "http:ya.ru:80",
  "error_message": "some string"
}
HOST_NOT_INDEXED
The Sitemap file is missing.
{
  "error_code": "HOST_NOT_INDEXED", //errorCode. 
  "host_id": "http:ya.ru:80", //id хоста. host id. 
  "error_message": "some string" //Error message. 
}
HOST_NOT_LOADED

The site data isn't uploaded to Yandex.Webmaster yet.

{
  "error_code": "HOST_NOT_LOADED",
  "host_id": "http:ya.ru:80",
  "error_message": "some string"
}