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={order_by}[&query_indicator={query_indicator}&device_type_indicator={device_type_indicator}&date_from={date_from}&date_to={date_to}&offset={offset}&limit={limit}]

Path parameters

Name Required Type Default value Description
user-id Yes int64 User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the GET /user method.
host-id Yes host id The site ID. To get it, use the GET /user/{user-id}/hosts method.

Query parameters

Name Required Type Default value Description
order_by Yes ApiQueryOrderField Indicator for sorting queries.
query_indicator No ApiQueryIndicator Indicators for displaying queries.
device_type_indicator No ApiDeviceTypeIndicator ALL Device type.
date_from No datetime The start date of the range. If omitted, data is returned for the last week.
date_to No datetime The end date of the range. If omitted, data is returned for the last week.
offset No int32 0 The list offset. The minimum value is 0.
limit No int32 500 Page size (1-500).

Query sorting order (ApiQueryOrderField)

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.

Device type indicators (ApiDeviceTypeIndicator)

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.

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.

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"
}