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.

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-id

Type: int64. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the GET /v4/user method.

host-id

Type: host id (string). The site ID. To get it, use the GET /v4/user/{user-id}/hosts method.

query-id

Type: string. Search query ID. To get it, use the GET /v4/user/{user-id}/hosts/{host-id}/search-queries/popular method.

query_indicator

Indicators 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.

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

<Data>
    <query>
        <query_id>a08b</query_id>
        <query_text>some text</query_text>
        <indicators>
            <TOTAL_SHOWS>
                <date>2019-07-18T00:00:00.000+03:00</date>
                <value>2.0</value>
                ...
            </TOTAL_SHOWS>
            ...
        </indicators>
    </query>
</Data>

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.

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

<Data>   
    <error_code>QUERY_ID_NOT_FOUND</error_code>     
    <error_message>some string</error_message> 
</Data>

Type: int64. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the GET /v4/user method.

Type: host id (string). The site ID. To get it, use the GET /v4/user/{user-id}/hosts method.

Type: string. Search query ID. To get it, use the GET /v4/user/{user-id}/hosts/{host-id}/search-queries/popular method.

Indicators for displaying requests (ApiQueryIndicator). You can specify multiple indicators. For example, query_indicator=TOTAL_SHOWS&query_indicator=TOTAL_CLICKS.

Device type (ApiDeviceTypeIndicator). Default value: ALL.

The start date of the range. If omitted, data is returned for the last week.

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.

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.

Description

Error code.

Description

Error message.

Required

Yes

Type

string

Description

Search query ID.

Note

—

Required

Yes

Type

string

Description

The text of the search query.

Note

—

Previous
Getting statistics for all queries
Next
Getting the list of Sitemap files