Getting information about popular queries

Description

Gets a list of the top 500 search queries that the site was shown for in search results over the past week. You can choose to get the 500 queries with the most displays in search results, or the 500 queries with the most click-throughs.

Request format

Send a GET request to the operation address for the search-queries/popular resource for the user's site.

GET https://api.webmaster.yandex.net/v3/user/{user-id}/hosts/{host-id}/search-queries/popular/?order_by={order_by}[&query_indicator={query_indicator}]

Path parameters

NameRequiredTypeDefault valueDescription
user-idYesint64The user ID.
host-idYeshost idSite ID.

Query arguments

NameRequiredTypeDefault valueDescription
order_byYesApiQueryOrderFieldHow to sort queries.
query_indicatorNoApiQueryIndicator collectionIndicators for displaying queries.

Sort order for queries (ApiQueryOrderField)

IndicatorDescription
TOTAL_SHOWSThe number of displays in search results.
TOTAL_CLICKSThe number of clicks.

Response format

If successful, the server returns 200 OK and a list of popular search queries:

Samples

{
  "queries": [
    {
      "query_id": "a08b",
      "query_text": "some text",
      "indicators": {
        "TOTAL_SHOWS": 1.1, ...
      }
    }, ...
  ],
  "date_from": "2016-01-01",
  "date_to": "2016-01-01"
}
NameRequiredTypeDescription
query_idYesint64Query ID.
query_textYesstringQuery text.
TOTAL_SHOWSYesApiQueryIndicatorQuery indicator (may be omitted if the value is undefined).
date_fromYesyyyy-MM-ddTHH:mm:ss,sssZThe start date of the range.
date_toYesyyyy-MM-ddTHH:mm:ss,sssZThe end date of the range.

Query indicators (ApiQueryIndicator)

IndicatorDescription
TOTAL_SHOWSThe number of displays in search results.
TOTAL_CLICKSThe number of clicks.
AVG_SHOW_POSITIONThe average position where the site was displayed.
AVG_CLICK_POSITIONThe average click position.

Errors

403 Forbidden

The user ID for the token doesn't match the one specified in the request. In the examples below, {user_id} is the correct uid for the owner of the OAuth token.

{
  "error_code": "INVALID_USER_ID",
  "available_user_id": 1,
  "error_message": "Invalid user id. {user_id} should be used."
}
ParameterDescription
error_codeError code.
available_user_idID of the user who allowed access.
error_messageError message.

404 Not Found

  • HOST_NOT_INDEXED error

    {
      "error_code": "HOST_NOT_INDEXED",
      "host_id": "http:ya.ru:80",
      "error_message": "explicit error message"
    }
    ParameterDescription
    error_codeThe site hasn't been indexed yet.
    host_idSite ID.
    error_messageError message.
  • HOST_NOT_LOADED error

    {
      "error_code": "HOST_NOT_LOADED",
      "host_id": "http:ya.ru:80",
      "error_message": "explicit error message"
    }
    ParameterDescription
    error_codeThe site data hasn't been loaded to Yandex.Webmaster yet.
    host_idSite ID.
    error_messageError message.
  • HOST_NOT_VERIFIED error

    {
      "error_code": "HOST_NOT_VERIFIED",
      "host_id": "http:ya.ru:80",
      "error_message": "explicit error message"
    }
    ParameterDescription
    error_codeThe site hasn't been added to the list of sites, or the user hasn't verified site management rights.
    host_idSite ID.
    error_messageError message.