Getting general statistics for a search query

Allows you to get the history of changes in indicators for a search query for a period of time.

  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/{query-id}/history
 ? [query_indicator=<string>]
 & [device_type_indicator=<string>]
 & [date_from=<datetime>]
 & [date_to=<datetime>]
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.
query-idType: string. Search query ID. To get it, use the GET /v4/user/{user-id}/hosts/{host-id}/search-queries/popular 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.
query-idType: string. Search query ID. To get it, use the GET /v4/user/{user-id}/hosts/{host-id}/search-queries/popular method.
query_indicatorIndicators for displaying requests (ApiQueryIndicator). You can specify multiple indicators. For example, query_indicator=TOTAL_SHOWS&query_indicator=TOTAL_CLICKS.
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.

query_indicatorIndicators for displaying requests (ApiQueryIndicator). You can specify multiple indicators. For example, query_indicator=TOTAL_SHOWS&query_indicator=TOTAL_CLICKS.
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.

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": [
            {
                "date": "2019-07-18T00:00:00.000+03:00",
                "value": 2.0
            },
            ...
        ]
    }
}               
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.
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.

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
404 QUERY_ID_NOT_FOUND
The specified search query ID does not exist.
{
  "error_code": "QUERY_ID_NOT_FOUND",
  "error_message": "some string"
}
Code Reason Description
200 OK
404 QUERY_ID_NOT_FOUND
The specified search query ID does not exist.
{
  "error_code": "QUERY_ID_NOT_FOUND",
  "error_message": "some string"
}