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

Name Required Type Default value Description
user-id Yes int64 The user ID.
host-id Yes host id Site ID.

Query arguments

Name Required Type Default value Description
order_by Yes ApiQueryOrderField How to sort queries.
query_indicator No ApiQueryIndicator collection Indicators for displaying queries.

Sort order for queries (ApiQueryOrderField)

Indicator Description
TOTAL_SHOWS The number of displays in search results.
TOTAL_CLICKS The 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"
}
Name Required Type Description
query_id Yes int64 Query ID.
query_text Yes string Query text.
TOTAL_SHOWS Yes ApiQueryIndicator Query indicator (may be omitted if the value is undefined).
date_from Yes yyyy-MM-ddTHH:mm:ss,sssZ The start date of the range.
date_to Yes yyyy-MM-ddTHH:mm:ss,sssZ The end date of the range.

Query indicators (ApiQueryIndicator)

Indicator Description
TOTAL_SHOWS The number of displays in search results.
TOTAL_CLICKS The number of clicks.
AVG_SHOW_POSITION The average position where the site was displayed.
AVG_CLICK_POSITION The 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."
}
Parameter Description
error_code Error code.
available_user_id ID of the user who allowed access.
error_message Error message.

404 Not Found

  • HOST_NOT_INDEXED error

    {
      "error_code": "HOST_NOT_INDEXED",
      "host_id": "http:ya.ru:80",
      "error_message": "explicit error message"
    }
    Parameter Description
    error_code The site hasn't been indexed yet.
    host_id Site ID.
    error_message Error message.
  • HOST_NOT_LOADED error

    {
      "error_code": "HOST_NOT_LOADED",
      "host_id": "http:ya.ru:80",
      "error_message": "explicit error message"
    }
    Parameter Description
    error_code The site data hasn't been loaded to Yandex.Webmaster yet.
    host_id Site ID.
    error_message Error message.
  • HOST_NOT_VERIFIED error

    {
      "error_code": "HOST_NOT_VERIFIED",
      "host_id": "http:ya.ru:80",
      "error_message": "explicit error message"
    }
    Parameter Description
    error_code The site hasn't been added to the list of sites, or the user hasn't verified site management rights.
    host_id Site ID.
    error_message Error message.