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

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

  1. Формат запроса
  2. Формат ответа
  3. Коды ответа

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

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.
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"
  }
}
Имя Обязательно Тип Описание
offset Нет int32 Смещение списка. Минимальное значение — 0. Значение по умолчанию: 0.
limit Нет int32 Количество записей (1—100). Значение по умолчанию: 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».
Имя Обязательно Тип Описание
offset Нет int32 Смещение списка. Минимальное значение — 0. Значение по умолчанию: 0.
limit Нет int32 Количество записей (1—100). Значение по умолчанию: 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 Тип для описания направления сортировки.
Поля внутри 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 Тип для описания направления сортировки.

Индикаторы типов устройств (ApiDeviceTypeIndicator)

Индикатор Описание
ALL Все типы устройств.
DESKTOP Компьютеры.
MOBILE_AND_TABLET Мобильные телефоны и планшеты.
MOBILE Мобильные телефоны.
TABLET Планшеты.
Индикатор Описание
ALL Все типы устройств.
DESKTOP Компьютеры.
MOBILE_AND_TABLET Мобильные телефоны и планшеты.
MOBILE Мобильные телефоны.
TABLET Планшеты.

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

Операции с текстом запроса (ApiTextualOperation)

Индикатор Описание
TEXT_CONTAINS Укажите часть текста.
TEXT_MATCH Укажите полностью поисковый запрос.
TEXT_DOES_NOT_CONTAIN Укажите часть текста, который не должен входить в поисковый запрос.
Индикатор Описание
TEXT_CONTAINS Укажите часть текста.
TEXT_MATCH Укажите полностью поисковый запрос.
TEXT_DOES_NOT_CONTAIN Укажите часть текста, который не должен входить в поисковый запрос.

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

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

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

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

В этом случае обратите внимание на «Спрос» (DEMAND). Например, если он равен 0, значит пользователи не задавали поисковый запрос. Если значение больше 0, но позиция не определена, вероятно, пользователи не долистали до позиции сайта или сайта нет в результатах поиска по поисковому запросу.
CLICKS Переход посетителя на сайт со страницы результатов поиска Яндекса.
CTR Отношение числа кликов на сниппет к числу его показов, измеряется в процентах. Можно сказать, что этот показатель говорит о привлекательности сниппета страницы сайта.
DEMAND Спрос показывает, насколько часто пользователи Яндекса задают поисковый запрос. Если сайт отображается на первой странице больше одного раза, сумма показов сайта может оказаться больше спроса. Например, для навигационных запросов, где пользователь ищет конкретный сайт, и поисковая система показывает несколько результатов с одного сайта.
Индикатор Описание
IMPRESSIONS Появление ссылки на сайт в результатах поиска Яндекса по некоторому запросу. Показом не является потенциальное появление ссылки на второй и последующих страницах результатов поиска, если пользователь эти страницы не открывал.
POSITION

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

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

В этом случае обратите внимание на «Спрос» (DEMAND). Например, если он равен 0, значит пользователи не задавали поисковый запрос. Если значение больше 0, но позиция не определена, вероятно, пользователи не долистали до позиции сайта или сайта нет в результатах поиска по поисковому запросу.
CLICKS Переход посетителя на сайт со страницы результатов поиска Яндекса.
CTR Отношение числа кликов на сниппет к числу его показов, измеряется в процентах. Можно сказать, что этот показатель говорит о привлекательности сниппета страницы сайта.
DEMAND Спрос показывает, насколько часто пользователи Яндекса задают поисковый запрос. Если сайт отображается на первой странице больше одного раза, сумма показов сайта может оказаться больше спроса. Например, для навигационных запросов, где пользователь ищет конкретный сайт, и поисковая система показывает несколько результатов с одного сайта.

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

Индикатор Описание
LESS_THAN Меньше чем.
GREATER_THAN Больше чем.
LESS_EQUAL Меньше или равно.
GREATER_EQUAL Больше или равно.
EQUAL Равно.
Индикатор Описание
LESS_THAN Меньше чем.
GREATER_THAN Больше чем.
LESS_EQUAL Меньше или равно.
GREATER_EQUAL Больше или равно.
EQUAL Равно.

Тип для описания направления сортировки (OrderDirection)

Индикатор Описание
ASC По возрастанию.
DESC По убыванию.
Индикатор Описание
ASC По возрастанию.
DESC По убыванию.

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

Идентификатор Регион
225 Россия
11235 Алтайский край
11375 Амурская область
10842 Архангельская область
10946 Астраханская область
10645 Белгородская область
10650 Брянская область
10658 Владимирская область
10950 Волгоградская область
10853 Вологодская область
10672 Воронежская область
10687 Ивановская область
11266 Иркутская область
11013 Кабардино-Балкарская Республика
10857 Калининградская область
11020 Карачаево-Черкесская Республика
11282 Кемеровская область (Кузбасс)
10699 Костромская область
10995 Краснодарский край
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 Ярославская область
Идентификатор Регион
225 Россия
11235 Алтайский край
11375 Амурская область
10842 Архангельская область
10946 Астраханская область
10645 Белгородская область
10650 Брянская область
10658 Владимирская область
10950 Волгоградская область
10853 Вологодская область
10672 Воронежская область
10687 Ивановская область
11266 Иркутская область
11013 Кабардино-Балкарская Республика
10857 Калининградская область
11020 Карачаево-Черкесская Республика
11282 Кемеровская область (Кузбасс)
10699 Костромская область
10995 Краснодарский край
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
                },
            ...
Имя Обязательный Тип Описание
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 Значение показателя.
Имя Обязательный Тип Описание
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"
}
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"
}
INVALID_URL Передан неправильный URL.
{
  "error_code": "INVALID_URL",
  "error_message": "some string"
}
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."
}
404 HOST_NOT_VERIFIED
Не подтверждены права на управление сайтом.
{
  "error_code": "HOST_NOT_VERIFIED",
  "host_id": "http:ya.ru:80",
  "error_message": "some string"
}
HOST_NOT_INDEXED
Сайт не проиндексирован.
{
  "error_code": "HOST_NOT_INDEXED", //errorCode. 
  "host_id": "http:ya.ru:80", //id хоста. host id. 
  "error_message": "some string" //Error message. 
}
HOST_NOT_LOADED

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

{
  "error_code": "HOST_NOT_LOADED",
  "host_id": "http:ya.ru:80",
  "error_message": "some string"
}
Код Причина Описание
200 OK
400 ENTITY_VALIDATION_ERROR Тело запроса не прошло валидацию.
{
  "error_code": "ENTITY_VALIDATION_ERROR",
  "error_message": "some string"
}
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"
}
INVALID_URL Передан неправильный URL.
{
  "error_code": "INVALID_URL",
  "error_message": "some string"
}
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."
}
404 HOST_NOT_VERIFIED
Не подтверждены права на управление сайтом.
{
  "error_code": "HOST_NOT_VERIFIED",
  "host_id": "http:ya.ru:80",
  "error_message": "some string"
}
HOST_NOT_INDEXED
Сайт не проиндексирован.
{
  "error_code": "HOST_NOT_INDEXED", //errorCode. 
  "host_id": "http:ya.ru:80", //id хоста. host id. 
  "error_message": "some string" //Error message. 
}
HOST_NOT_LOADED

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

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