Мониторинг поисковых запросов

Позволяет получить список поисковых запросов и URL-адресов страниц, по которым ваш сайт отображается в результатах поиска Яндекса. Данные доступны за последние две недели. Подробно о мониторинге поисковых запросов см. в Справке.

Примечание

Если вы отправите более 10 тысяч запросов в час, вы не сможете воспользоваться мониторингом в течение некоторого времени. Сообщение о превышении появится в коде ответа 429.

Формат запроса

POST https://api.webmaster.yandex.net/v4/user/{user-id}/hosts/{host-id}/query-analytics/list

user-id

Тип: int64. ID пользователя. Необходим для вызова любых ресурсов API Яндекс Вебмастера. Чтобы получить его, используйте метод GET /v4/user.

host-id

Тип: host id (string). ID сайта. Чтобы получить его, используйте метод GET /v4/user/{user‑id}/hosts.

Заголовок запроса

При отправке запроса используйте заголовок Content-Type: application/json; charset=UTF-8.

Формат тела запроса

{
  "offset": 1,
  "limit": 1,
  "device_type_indicator": "ALL",
  "text_indicator": "URL",
  "region_ids": [
    1
  ],
  "filters": {
    "text_filters": [
      {
        "text_indicator": "URL",
        "operation": "TEXT_CONTAINS",
        "value": "some string"
      }
    ],
    "statistic_filters": [
      {
        "statistic_field": "IMPRESSIONS",
        "operation": "LESS_THAN",
        "value": "some string",
        "from": "some string",
        "to": "some string"
      }
    ]
  },
  "sort_by_date": {
    "date": "some string",
    "statistic_field": "IMPRESSIONS",
    "by": "ASC"
  }
}
<Data>
  <offset>1</offset>
  <limit>1</limit>
  <device_type_indicator>ALL</device_type_indicator>
  <text_indicator>URL</text_indicator>
  <region_id>1</region_id>

  <filters>
    <text_filter>
      <text_indicator>URL</text_indicator>
      <operation>TEXT_CONTAINS</operation>
      <value>some string</value>
    </text_filter>

    <statistic_filter>
      <statistic_field>IMPRESSIONS</statistic_field>
      <operation>LESS_THAN</operation>
      <value>some string</value>
      <from>some string</from>
      <to>some string</to>
    </statistic_filter>
  </filters>

  <sort_by_date>
    <date>some string</date>
    <statistic_field>IMPRESSIONS</statistic_field>
    <by>ASC</by>
  </sort_by_date>
</Data>

Имя

Обязательно

Тип

Описание

offset

Нет

int32

Смещение списка. Минимальное значение — 0. Значение по умолчанию: 0.

limit

Нет

int32

Количество записей (1—500). Значение по умолчанию: 20.

device_type_indicator

Нет

ApiDeviceTypeIndicator

Тип устройства. Значение по умолчанию: ALL.

text_indicator

Нет

Indicator

Тип данных, по которому отображается статистика. По умолчанию принимает значение QUERY. Возможные значения:

  • QUERY — поисковый запрос;

  • URL — адрес страницы сайта.

region_ids

array

Идентификаторы регионов, для которых производится мониторинг. Можно указать несколько идентификатор через запятую (например, 1, 2). Если значение не задано, статистика считается по всем регионам, в которых присутствует сайт в результатах поиска.

filters

Нет

Filters

Фильтры.

sort_by_date

Нет

SortByDate

Сортировка данных по дате.

Поля внутри Filters

text_filters

Нет

array (TextFilter)

Фильтры над текстом.

statistic_filters

Нет

array (StatisticFilter)

Фильтры над статистическими данными.

Поля внутри TextFilters

text_indicator

Да, если передается TextFilters

Indicator

Тип данных, по которому отображается статистика. Возможные значения:

  • QUERY — поисковый запрос;

  • URL — адрес страницы сайта.

operation

ApiTextualOperation

Операции с URL или текстом запроса.

value

string

Строка, к которой применяется операция. Используется для фильтрации поискового запроса или URL. Например, фрагмент «brand».

Поля внутри StatisticFilters

statistic_field

Да, если передается StatisticFilters

ApiStatisticField

Статистические данные, над которыми производится фильтрация.

operation

ApiNumericOperation

Целое число, которое применяется к операции.

value

string

Число, с которым нужно сравнить статистическое значение.

from

Начало (включительно) интервала дат в формате yyyy-MM-dd.

to

Конец (включительно) интервала дат в формате yyyy-MM-dd.

Поля внутри SortByDate

date

Да, если передается SortByDate

Дата в формате yyyy-MM-dd.

statistic_field

ApiStatisticField

Статистические данные, над которыми производится фильтрация.

by

OrderDirection

Тип для описания направления сортировки.

Индикатор

Описание

ALL

Все типы устройств.

DESKTOP

Компьютеры.

MOBILE_AND_TABLET

Мобильные телефоны и планшеты.

MOBILE

Мобильные телефоны.

TABLET

Планшеты.

Если в запросе не задан индикатор типа устройства, по умолчанию используется значение ALL.

Индикатор

Описание

TEXT_CONTAINS

Укажите часть текста.

TEXT_MATCH

Укажите полностью поисковый запрос.

TEXT_DOES_NOT_CONTAIN

Укажите часть текста, который не должен входить в поисковый запрос.

Индикатор

Описание

IMPRESSIONS

Появление ссылки на сайт в результатах поиска Яндекса по некоторому запросу. Показом не является потенциальное появление ссылки на второй и последующих страницах результатов поиска, если пользователь эти страницы не открывал.

POSITION

Место, на котором появляется ссылка на сайт в поисковой выдаче Яндекса в ответ на поисковый запрос пользователя.

Информация о позиции сайта может отсутствовать, если в заданный период:

  • сайт не отображался в результатах поиска по указанному поисковому запросу;
  • пользователи не вводили указанный поисковый запрос;
  • пользователи не долистали до позиции сайта в результатах поиска.

В этом случае обратите внимание на «Спрос» (DEMAND). Например, если он равен 0, значит пользователи не задавали поисковый запрос. Если значение больше 0, но позиция не определена, вероятно, пользователи не долистали до позиции сайта или сайта нет в результатах поиска по поисковому запросу.

CLICKS

Переход посетителя на сайт со страницы результатов поиска Яндекса.

CTR

Отношение числа кликов на сниппет к числу его показов, измеряется в процентах. Можно сказать, что этот показатель говорит о привлекательности сниппета страницы сайта.

DEMAND

Спрос показывает, насколько часто пользователи Яндекса задают поисковый запрос. Если сайт отображается на первой странице больше одного раза, сумма показов сайта может оказаться больше спроса. Например, для навигационных запросов, где пользователь ищет конкретный сайт, и поисковая система показывает несколько результатов с одного сайта.

Индикатор

Описание

LESS_THAN

Меньше чем.

GREATER_THAN

Больше чем.

LESS_EQUAL

Меньше или равно.

GREATER_EQUAL

Больше или равно.

EQUAL

Равно.

Индикатор

Описание

ASC

По возрастанию.

DESC

По убыванию.

Идентификаторы часто используемых регионов

Идентификатор

Регион

225

Россия

11235

Алтайский край

11375

Амурская область

10842

Архангельская область

10946

Астраханская область

10645

Белгородская область

10650

Брянская область

10658

Владимирская область

10950

Волгоградская область

10853

Вологодская область

10672

Воронежская область

10687

Ивановская область

11266

Иркутская область

11013

Кабардино-Балкарская Республика

10857

Калининградская область

11020

Карачаево-Черкесская Республика

11282

Кемеровская область (Кузбасс)

10699

Костромская область

10995

Краснодарский край

11309

Красноярский край

11158

Курганская область

10705

Курская область

10712

Липецкая область

1

Москва и Московская область

10897

Мурманская область

11079

Нижегородская область

10904

Новгородская область

11316

Новосибирская область

11318

Омская область

11084

Оренбургская область

10772

Орловская область

11095

Пензенская область

11108

Пермский край

11409

Приморский край

10926

Псковская область

11111

Республика Башкортостан

11010

Республика Дагестан

11012

Республика Ингушетия

11077

Республика Марий Эл

11117

Республика Мордовия

11021

Республика Северная Осетия — Алания

11119

Республика Татарстан

11029

Ростовская область

10776

Рязанская область

11131

Самарская область

10174

Санкт-Петербург и Ленинградская область

11162

Свердловская область

10795

Смоленская область

11069

Ставропольский край

10802

Тамбовская область

10819

Тверская область

11353

Томская область

10832

Тульская область

11153

Ульяновская область

11457

Хабаровский край

11193

Ханты-Мансийский автономный округ - Югра

11225

Челябинская область

11024

Чеченская Республика

11156

Чувашская Республика

10841

Ярославская область

Формат ответа

Примеры

{
    "count": 5175,
    "text_indicator_to_statistics": [
        {
            "text_indicator": {
                "type": "URL",
                "value": "some text"
            },
            "statistics": [
                {
                    "date": "2023-04-15",
                    "field": "CLICKS",
                    "value": 7.0
                },
                {
                    "date": "2023-04-15",
                    "field": "POSITION",
                    "value": 4.0
                },
                {
                    "date": "2023-04-15",
                    "field": "IMPRESSIONS",
                    "value": 8595.0
                },
                {
                    "date": "2023-04-15",
                    "field": "CTR",
                    "value": 0.0
                },
            ...                
<Data>
    <count>5175</count>
    <text_indicator_to_statistic>
        <text_indicator>
            <type>URL</type>
            <value>some text</value>
        </text_indicator>
        <statistic>
            <date>2023-04-15</date>
            <field>CLICKS</field>
            <value>7.0</value>
        </statistic>
        <statistic>
            <date>2023-04-15</date>
            <field>POSITION</field>
            <value>4.0</value>
        </statistic>
        <statistic>
            <date>2023-04-15</date>
            <field>IMPRESSIONS</field>
            <value>8595.0</value>
        </statistic>
        ...    

Имя

Обязательный

Тип

Описание

count

Да

int32

Общее количество доступных данных.

text_indicator_to_statistics

Да

array
(TextIndicatorToStatistics)

Поля внутри TextIndicatorToStatistics

text_indicator

Да

TextIndicator

statistics

Да

array (Statistics)

Поля внутри TextIndicator

type

Да

string

Возможные значения:

  • QUERY — поисковый запрос;

  • URL — адрес страницы сайта.

value

Да

string

Поисковый запрос или URL страницы сайта.

Поля внутри Statistics

date

Да

Дата в формате yyyy-MM-dd, за которую отображается статистика.

field

Да

ApiStatisticField

Тип показателя.

value

Да

double

Значение показателя.

Коды ответа

Чтобы посмотреть структуру ответа подробнее, нажмите на причину.

Код

Причина

Описание

200

OK

400

ENTITY_VALIDATION_ERROR

Тело запроса не прошло валидацию.

{
  "error_code": "ENTITY_VALIDATION_ERROR",
  "error_message": "some string"
}
<Data>
  <error_code>ENTITY_VALIDATION_ERROR</error_code>  
  <error_message>some string</error_message>
</Data>

400

FIELD_VALIDATION_ERROR

Передан неверный параметр.

{
  "error_code": "FIELD_VALIDATION_ERROR",
  "error_message": "explicit error message",
  "field_name": "some string",
  "field_value": "some string",
  "error_message": "explicit error message"
}
<Data>
    <error_code>FIELD_VALIDATION_ERROR</error_code>
    <field_name>some string</field_name>
    <field_value>some string</field_value>
    <error_message>explicit error message</error_message>
</Data>

400

INVALID_URL

Передан неправильный URL.

{
  "error_code": "INVALID_URL",
  "error_message": "some string"
}
<Data>
  <error_code>INVALID_URL</error_code>  
  <error_message>some string</error_message>
</Data>

403

INVALID_USER_ID

ID пользователя, выдавшего токен, отличается от указанного в запросе. В примерах ниже {user_id} указан правильный uid владельца OAuth-токена.

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

Не подтверждены права на управление сайтом.

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

Сайт не проиндексирован.

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

Данные о сайте еще не загружены в Яндекс Вебмастер.

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

429

TOO_MANY_REQUESTS_ERROR

Отправлено более 10 тысяч запросов на домен в час. Поэтому вы не сможете использовать метод /user/{user-id}/hosts/{host-id}/query-analytics/list/ в течение некоторого времени.

{
  "error_code": "TOO_MANY_REQUESTS_ERROR",
  "error_message": "some string"
}
<Data>
  <error_code>TOO_MANY_REQUESTS_ERROR</error_code>
  <error_message>some string</error_message>
</Data>

Узнайте больше