Позиции сайта через API: как выгрузить данные из Яндекс Вебмастера

Если позиции нужны не глазами, а в таблице, дашборде или в скрипте — их отдаёт API Яндекс Вебмастера. Бесплатно, по всем запросам сайта, без ограничения «до 100 ключей в тарифе». Ниже — какие эндпоинты за это отвечают, чем они отличаются друг от друга, где у них лимиты и на чём чаще всего спотыкается интеграция.

Про то, как читать эти же цифры руками в интерфейсе и когда всё-таки нужен внешний съёмщик, есть отдельная статья — мониторинг позиций в Яндексе. Здесь — техническая сторона.

Что именно отдаёт API

Сразу важное ограничение, чтобы не строить неверных ожиданий. Вебмастер не отдаёт «позицию сайта по запросу в Москве на мобильных в 14:30». Он отдаёт среднюю позицию показа — усреднение по всем реальным показам вашего сайта живым пользователям за период. Это другая метрика, чем у сервисов съёма, и в ряде задач она честнее: она взвешена по фактическому спросу, а не по одному замеру из одной точки.

Вместе с позицией доступны показы, клики и CTR — то есть полная связка, по которой видно не только «где стоим», но и «приносит ли это трафик».

Авторизация и host_id

Работа с API начинается с двух вещей, которые почти всегда съедают первый час.

Токен. Авторизация — OAuth Яндекса, заголовком Authorization: OAuth <token>. Приложение регистрируется в Яндекс OAuth, нужное право — доступ к Вебмастеру.

Идентификаторы. В URL каждого запроса участвуют user_id и host_id, и оба нужно получить отдельными вызовами:

GET https://api.webmaster.yandex.net/v4/user
GET https://api.webmaster.yandex.net/v4/user/{user-id}/hosts

Здесь первая ловушка: host_id — это не домен. Он выглядит как https:example.com:443 — схема, домен и порт через двоеточия, без слешей. В путь URL его нужно вставлять в URL-кодированном виде. Подставить туда просто example.com — самая частая ошибка на старте.

Эндпоинт 1: сводка по запросам

GET /v4/user/{user-id}/hosts/{host-id}/search-queries/popular

Возвращает список запросов, по которым сайт показывался, отсортированный по показам или кликам. Ключевые параметры:

• order_by — TOTAL_SHOWS или TOTAL_CLICKS, обязательный;
• query_indicator — какие метрики приложить к каждому запросу: TOTAL_SHOWS, TOTAL_CLICKS, AVG_SHOW_POSITION, AVG_CLICK_POSITION;
• date_from, date_to — период;
• device_type_indicator — ALL, DESKTOP, MOBILE, TABLET, MOBILE_AND_TABLET;
• offset, limit — пагинация, до 500 записей за вызов.

Главная ловушка этого метода. Параметр query_indicator необязательный, и если его не передать, сервер спокойно вернёт 200 и список запросов — но с пустым indicators: {} у каждого. Ни позиций, ни показов. Выглядит как «API не отдаёт метрики», на деле — не запросили.

Второй нюанс: индикаторы передаются повторяющимся параметром, а не строкой через запятую:

?order_by=TOTAL_SHOWS
&query_indicator=TOTAL_SHOWS
&query_indicator=TOTAL_CLICKS
&query_indicator=AVG_SHOW_POSITION

Если ваш HTTP-клиент склеивает массив в query_indicator=A,B,C, метрики снова не придут. Мы сами наступили на эту граблю в коде Seely: схема инструмента объявляла параметр строкой, а клиент ждал массив — в итоге индикаторы молча не доходили до API, и запросы возвращались без цифр. Ошибка починена, но она хорошо показывает, насколько тихо этот метод деградирует.

Эндпоинт 2: разбивка по дням

POST /v4/user/{user-id}/hosts/{host-id}/query-analytics/list

Метод другого назначения: он отдаёт статистику по дням за последние две недели, и не только по запросам, но и по URL. Тело запроса задаёт:

• text_indicator — QUERY (группировать по запросам) или URL (по страницам);
• limit — до 20 записей за вызов, это самый жёсткий потолок из всех методов;
• region_ids — фильтр по регионам;
• filters — текстовые и статистические фильтры (например, только запросы с позицией лучше 10);
• sort_by_date — сортировка.

В ответе на каждую запись приходит массив statistics — по одной точке на день и поле: IMPRESSIONS, CLICKS, CTR, POSITION, DEMAND. Плюс поле popular_complementary_indicator: для запроса это самый частый URL, для URL — самый частый запрос. Именно оно позволяет одним вызовом понять, какая страница отвечает за какой запрос — то есть увидеть каннибализацию, не сводя данные вручную.

DEMAND — отдельная ценность: это оценка общего спроса по запросу, а не только ваших показов. По нему видно, вы просели или просел сам спрос.

Эндпоинт 3: история

GET /v4/user/{user-id}/hosts/{host-id}/search-queries/all/history
GET /v4/user/{user-id}/hosts/{host-id}/search-queries/{query-id}/history

Первый — динамика суммарных показателей по всем запросам, второй — по конкретному запросу (query_id берётся из ответа сводки). Оба принимают query_indicator теми же значениями и с тем же правилом повторяющегося параметра.

Это основной инструмент, когда нужно отделить апдейт алгоритма от собственной ошибки: если по всем запросам провал в один день — это апдейт, если по одному — правки на странице.

Как собрать выгрузку целиком

Порядок, который работает:

1. Получить user_id и host_id — один раз, дальше кэшировать.
2. Забрать сводку через search-queries/popular с нужными индикаторами, страницами по 500 записей через offset, пока ответ не станет короче лимита.
3. Для запросов, которые интересны, дозапросить дневную динамику через query-analytics/list пачками по 20.
4. Сохранить срез с датой снятия: API отдаёт скользящее окно, «как было три месяца назад» задним числом уже не восстановить.

Последний пункт важнее, чем кажется. Вебмастер хранит ограниченное окно истории, поэтому собственный архив снимков — единственный способ через год ответить на вопрос «а что было прошлой весной».

Есть и общий лимит частоты обращений на приложение, поэтому в цикле по страницам нужна пауза и обработка 429, а не «выгрузить всё в 50 параллельных потоков».

Тот же результат без кода

Всё описанное выше — обвязка вокруг довольно простых HTTP-запросов: авторизация, идентификаторы, пагинация, повторяющиеся параметры. Эту обвязку можно не писать.

MCP-сервер делает ровно её: держит токен, знает про составной host_id, сам разбивает выгрузку на страницы и отдаёт нейросети готовые данные. На вашей стороне остаётся формулировка задачи:

Выгрузи из Вебмастера запросы за последние 28 дней с показами, кликами и средней позицией. Найди те, где позиция в топ-10, но CTR ниже 3%. Для каждого покажи, какая страница отвечает за запрос.

Внутри это несколько вызовов тех же самых методов — get_webm_popular_queries за сводкой, get_webm_query_analytics_list за связкой «запрос — URL». Разница в том, что пагинацию, индикаторы и формат ответа разбирает сервер, а не вы.

Когда своя интеграция всё-таки нужна: если данные ложатся в собственную БД, если нужен ежедневный снапшот по расписанию или если поверх строится клиентский дашборд. Для разовой аналитики и еженедельных разборов писать код смысла мало.

Итого

• Позиции, показы и клики по запросам Яндекс отдаёт бесплатно через API Вебмастера v4.
• search-queries/popular — сводка до 500 записей, query-analytics/list — дневная разбивка до 20, history — динамика.
• Три вещи ломают интеграцию чаще всего: домен вместо составного host_id, отсутствующий query_indicator и склейка индикаторов в один параметр.
• Позиция здесь — усреднение по реальным показам, а не съём из конкретного города.
• Историю нужно архивировать самому: API отдаёт скользящее окно.

Что делать с полученными цифрами дальше — в статье про вывод запросов из топ-20 в топ-10, а про регулярную отчётность на этих данных — в материале об автоматизации SEO-отчётов.