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.

Request format

GET https://api.webmaster.yandex.net/v4/user/{user-id}/hosts/{host-id}/search-queries/popular
  ? order_by=<string>
  & [query_indicator=<string>]
  & [device_type_indicator=<string>]
  & [date_from=<datetime>]
  & [date_to=<datetime>]
  & [offset=<int32>]
  & [limit=<int32>]

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.

order_by*

Indicator for sorting requests (ApiQueryOrderField).

query_indicator

Indicators for displaying requests (ApiQueryIndicator).

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.

offset

The list offset. The minimum value is 0. Default value: 0.

limit

Page size (1-500). Default value: 500.

* Required

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

<Data>
    <query>
        <query_id>a08b</query_id>
        <query_text>some text</query_text>
        <indicators>
            <TOTAL_SHOWS>1.1</TOTAL_SHOWS>
            ...
        </indicators>
    </query>
    ...
    <date_from>2016-01-01</date_from>
    <date_to>2016-01-07</date_to>
    <count>300</count>
</Data>

Name

Required

Type

Description

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

<Data>     
    <error_code>INVALID_USER_ID</error_code>     
    <available_user_id>1</available_user_id>     
    <error_message>Invalid user id. {user_id} should be used.</error_message> 
</Data>

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

<Data>   
    <error_code>HOST_NOT_VERIFIED</error_code>     
    <host_id>http:ya.ru:80</host_id>   
    <error_message>some string</error_message> 
</Data>

404

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

<Data>   
    <error_code>HOST_NOT_INDEXED</error_code>     
    <host_id>http:ya.ru:80</host_id>     
    <error_message>some string</error_message> 
</Data>

404

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

<Data>   
    <error_code>HOST_NOT_LOADED</error_code>     
    <host_id>http:ya.ru:80</host_id>   
    <error_message>some string</error_message> 
</Data>

Page size (1-500). Default value: 500.

The list offset. The minimum value is 0. Default value: 0.

The list offset. The minimum value is 0. Default value: 0.

Indicator for sorting requests (ApiQueryOrderField).

*Required

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.

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.

Query sorting order (ApiQueryOrderField)

Indicator

Description

TOTAL_SHOWS

The number of displays.

TOTAL_CLICKS

The number of clicks.

Indicators for displaying requests (ApiQueryIndicator)

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.

Required

Yes

Type

string

Description

Search query ID.

Note

—

Required

Yes

Type

string

Description

The text of the search query.

Note

—

Required

Yes

Type

int32

Description

The total number of search queries available.

Note

—

Description

Error code.

Description

ID of the user who allowed access.

Description

ID of the requested site.

Description

Error message.

Previous
Getting the history of SQI changes
Next
Getting statistics for all queries