---
metadata:
  - name: generator
    content: Diplodoc Platform v5.44.0
alternate:
  - https://yandex.com/dev/webmaster/doc/en/reference/host-search-queries-popular.md
  - https://yandex.com/dev/webmaster/doc/ru/reference/host-search-queries-popular.md
keywords:
  - s
  - i
  - t
  - e
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/webmaster/doc/en/llms.txt


# 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](*user-id)}/hosts/{[host-id](*host-id)}/search-queries/popular
  ? [order_by](*order_by)=<string>
  & [[query_indicator](*query_indicator)=<string>]
  & [[device_type_indicator](*device_type_indicator)=<string>]
  & [[date_from](*date_from)=<datetime>]
  & [[date_to](*date_to)=<datetime>]
  & [[offset](*offset)=<int32>]
  & [[limit](*limit)=<int32>]
```

#|
||
`user-id`
|
<!-- source: en/_includes/popups.md -->
Type: `int64`. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the [GET /v4/user](https://yandex.com/dev/webmaster/doc/en/reference/user.md) method.
<!-- endsource: en/_includes/popups.md -->
||
||
`host-id`
|
<!-- source: en/_includes/popups.md -->
Type: `host id (string)`. The site ID. To get it, use the [GET /v4/user/{user-id}/hosts](https://yandex.com/dev/webmaster/doc/en/reference/hosts.md) method.
<!-- endsource: en/_includes/popups.md -->
||
||
`order_by`[*](*requiredParam)
|
Indicator for sorting requests ([ApiQueryOrderField](*ApiQueryOrderField)).
||
||
`query_indicator`
|
Indicators for displaying requests ([ApiQueryIndicator](*ApiQueryIndicator)).
||
||
`device_type_indicator`
|
Device type ([ApiDeviceTypeIndicator](*ApiDeviceTypeIndicator)). Default value: `ALL`.
||
||
`date_from`
|
<!-- source: en/_includes/popups.md -->
The start date of the range. If omitted, data is returned for the last week.
<!-- endsource: en/_includes/popups.md -->
||
||
`date_to`
|
<!-- source: en/_includes/popups.md -->
The end date of the range. If omitted, data is returned for the last week.
<!-- endsource: en/_includes/popups.md -->
||
||
`offset`
|
The list offset. The minimum value is 0. Default value: 0.
||
||
`limit`
|
Page size (1-500). Default value: 500.
||
|#

\* Required

<!-- source: en/_includes/reference/query-order-field.md -->
### Query sorting order (ApiQueryOrderField) {#query-order-field}

#|
|| **Indicator** | **Description** ||
|| `TOTAL_SHOWS` | The number of displays. ||
|| `TOTAL_CLICKS` | The number of clicks. ||
|#
<!-- endsource: en/_includes/reference/query-order-field.md -->

<!-- source: en/_includes/reference/api-query-indicator.md -->
### Query indicators (ApiQueryIndicator) {#api-query-indicator}

#|
|| **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. ||
|#
<!-- endsource: en/_includes/reference/api-query-indicator.md -->

<!-- source: en/_includes/reference/device-type-indicators.md -->
### Device type indicators (ApiDeviceTypeIndicator) {#device-type-indicators}

#|
|| **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`.
<!-- endsource: en/_includes/reference/device-type-indicators.md -->


## Response format

### Examples

> 
> {% list tabs %}
> 
> - JSON
> 
>   
>   ```javascript
>   {
>     "queries": [
>       {
>         "query_id": "a08b",
>         "query_text": "some text",
>         "indicators": {
>           "[TOTAL_SHOWS](*ApiQueryIndicator)": 1.1, ...
>         }
>       }, ...
>     ],
>     "date_from": "2016-01-01",
>     "date_to": "2016-01-07",
>     "count": "300"
>   }
>   ```
>   
> 
> - XML
> 
>   
>   ```xml
>   <Data>
>       <query>
>           <[query_id](*query_id_desc)>a08b</query_id>
>           <[query_text](*query_text_desc)>some text</query_text>
>           <indicators>
>               <[TOTAL_SHOWS](*ApiQueryIndicator)>1.1</TOTAL_SHOWS>
>               ...
>           </indicators>
>       </query>
>       ...
>       <[date_from](*date_from)>2016-01-01</date_from>
>       <[date_to](*date_to)>2016-01-07</date_to>
>       <[count](*count_desc)>300</count>
>   </Data>
>   ```
> 
> {% endlist %}

#|
|| **Name** | **Required** | **Type** | **Description** ||
|| `query_id` | Yes | `string` | Search query ID. | — ||
|| `query_text` | Yes | `string` | The text of the search query. | — ||
|| [TOTAL_SHOWS](*ApiQueryIndicator) | Yes | [ApiQueryIndicator](*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. | — ||
|#

<!-- source: en/_includes/reference/api-query-indicator.md -->
### Query indicators (ApiQueryIndicator) {#api-query-indicator}

#|
|| **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. ||
|#
<!-- endsource: en/_includes/reference/api-query-indicator.md -->

## Response codes

To view the response structure in detail, click the reason.

#|
||
**Code** | **Reason** | **Description**
||
||
200 | OK | 
||
||
403
|
[INVALID_USER_ID](https://yandex.com/dev/webmaster/doc/en/reference/errors.md#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.

{% list tabs %}

- JSON

  ```json 
  {   
      "error_code": "INVALID_USER_ID",   
      "available_user_id": 1,   
      "error_message": "Invalid user id. {user_id} should be used." 
  }
  ```

- XML

  ```xml 
  <Data>     
      <[error_code](*error_code)>INVALID_USER_ID</error_code>     
      <[available_user_id](*available_user_id)>1</available_user_id>     
      <[error_message](*error_message)>Invalid user id. {user_id} should be used.</error_message> 
  </Data>
  ```

{% endlist %}
||
||
404
|
[HOST_NOT_VERIFIED](https://yandex.com/dev/webmaster/doc/en/reference/errors.md#host-not-verif)
|
Site management rights are not verified.

{% list tabs %}

- JSON

  ```json 
  {   
      "error_code": "HOST_NOT_VERIFIED",   
      "host_id": "http:ya.ru:80",   
      "error_message": "some string" 
  }
  ```

- XML

  ```xml 
  <Data>   
      <[error_code](*error_code)>HOST_NOT_VERIFIED</error_code>     
      <[host_id](*host_id)>http:ya.ru:80</host_id>   
      <[error_message](*error_message)>some string</error_message> 
  </Data>
  ```

{% endlist %}
||
||
404
|
[HOST_NOT_INDEXED](https://yandex.com/dev/webmaster/doc/en/reference/errors.md#host-not-ind)
|
The Sitemap file is missing.

{% list tabs %}

- JSON

  ```json 
  {   
    "error_code": "HOST_NOT_INDEXED", //errorCode.    
    "host_id": "http:ya.ru:80", //id хоста. host id.    
    "error_message": "some string" //Error message.  
  }
  ```

- XML

  ```xml 
  <Data>   
      <[error_code](*error_code)>HOST_NOT_INDEXED</error_code>     
      <[host_id](*host_id)>http:ya.ru:80</host_id>     
      <[error_message](*error_message)>some string</error_message> 
  </Data>
  ```

{% endlist %}
||
||
404
|
[HOST_NOT_LOADED](https://yandex.com/dev/webmaster/doc/en/reference/errors.md#host-not-loaded)
|
The site data isn't uploaded to Yandex.Webmaster yet.

{% list tabs %}

- JSON

  ```json 
  {   
      "error_code": "HOST_NOT_LOADED",   
      "host_id": "http:ya.ru:80",   
      "error_message": "some string"
  }
  ```

- XML

  ```xml 
  <Data>   
      <[error_code](*error_code)>HOST_NOT_LOADED</error_code>     
      <[host_id](*host_id)>http:ya.ru:80</host_id>   
      <[error_message](*error_message)>some string</error_message> 
  </Data>
  ```

{% endlist %}
||
|#

### Related information

- [Error codes and statuses](https://yandex.com/dev/webmaster/doc/en/reference/errors.md)




[*limit]: Page size (1-500). Default value: 500.

[*query]: The list offset. The minimum value is 0. Default value: 0.

[*offset]: The list offset. The minimum value is 0. Default value: 0.

[*order_by]: Indicator for sorting requests ([ApiQueryOrderField](#query-order-field)).

[*requiredParam]: ^*^Required

[*user-id]: Type: `int64`. User ID. Required when calling all Yandex.Webmaster API resources. To get it, use the [GET /v4/user](https://yandex.com/dev/webmaster/doc/en/reference/user.md) method.

[*host-id]: Type: `host id (string)`. The site ID. To get it, use the [GET /v4/user/{user-id}/hosts](https://yandex.com/dev/webmaster/doc/en/reference/hosts.md) method.

[*ApiQueryIndicator]: ### Query indicators (ApiQueryIndicator) {#api-query-indicator}

#|
|| **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. ||
|#

[*ApiDeviceTypeIndicator]: ### Device type indicators (ApiDeviceTypeIndicator) {#device-type-indicators}

#|
|| **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`.

[*ApiQueryOrderField]: ### Query sorting order (ApiQueryOrderField) {#query-order-field}

#|
|| **Indicator** | **Description** ||
|| `TOTAL_SHOWS` | The number of displays. ||
|| `TOTAL_CLICKS` | The number of clicks. ||
|#

[*query_indicator]: Indicators for displaying requests ([ApiQueryIndicator](#api-query-indicator))

[*device_type_indicator]: Device type ([ApiDeviceTypeIndicator](#device-type-indicators)). 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_id_desc]: **Required**

Yes

**Type**

`string`

**Description**

Search query ID.

**Note**

—

[*query_text_desc]: **Required**

Yes

**Type**

`string`

**Description**

The text of the search query.

**Note**

—

[*count_desc]: **Required**

Yes

**Type**

`int32`

**Description**

The total number of search queries available.

**Note**

—

[*error_code]: **Description**

Error code.

[*available_user_id]: **Description**

ID of the user who allowed access.

[*host_id]: **Description**

ID of the requested site.

[*error_message]: **Description**

Error message.