Telegram Обсудить проект
Статья SEO 8 минут чтения

API Яндекс Вебмастера

Коротко

API Яндекс Вебмастера — бесплатный программный доступ к данным Вебмастера: популярные запросы с показами, кликами и позициями, ИКС, страницы в поиске, история обхода, проблемы сайта, внешние ссылки, переобход и файлы Sitemap.

Чтобы получить доступ, создайте приложение на oauth.yandex.ru с платформой «Веб-сервисы» и правами Вебмастера, откройте ссылку авторизации со своим ClientID и скопируйте токен. Токен живёт 6 месяцев. Дальше — запрос user_id, список сайтов и любые отчёты по host_id.

Роман Михальчук · · проверено

Для кого: sEO-специалистам и разработчикам, которым нужны данные Вебмастера в таблицах, скриптах, чекере позиций или ИИ-агенте.

Главное
  • API Вебмастера бесплатен; условия требуют, чтобы у каждого пользователя было своё приложение.
  • Для чтения данных хватает права webmaster:hostinfo; webmaster:verify нужен, чтобы добавлять и подтверждать сайты.
  • OAuth-токен Яндекса для Вебмастера живёт 6 месяцев, потом его получают заново той же ссылкой.
  • Популярные запросы отдаются по 500 строк, до 3000 запросов за период; по умолчанию — за последнюю неделю.
  • Данные есть только по подтверждённым сайтам; длинную историю запросов нужно копить у себя.
Ключевые факты
Стоимость
бесплатно
Адрес API
https://api.webmaster.yandex.net/v4/
Права для чтения
webmaster:hostinfo
Срок жизни токена
6 месяцев (документация API Вебмастера)
Популярные запросы
до 500 строк за запрос, до 3000 запросов, по умолчанию за последнюю неделю
Формат host_id
протокол:домен:порт, например https:example.ru:443
01

Что отдаёт API Вебмастера

API Вебмастера — те же данные, что в кабинете Яндекс Вебмастера, только по запросу из программы:

ЧтоЧто внутри
Сайтысписок сайтов аккаунта, подтверждены ли права, главное зеркало
СводкаИКС, число страниц в поиске и исключённых, проблемы сайта по уровням
Популярные запросыпоказы, клики, средняя позиция показа и клика, фильтр по устройствам
Индексацияистория обхода по кодам ответа, страницы в поиске, исключённые страницы
Ссылкивнешние ссылки на сайт
Действияпереобход страниц, добавление файлов Sitemap

Чего в API нет: позиций конкурентов, частотности запросов и снимка выдачи. Позиция — средняя за период, как в отчёте «Запросы». Данные есть только по сайтам с подтверждёнными правами.

02

Шаг 1. Создайте приложение на oauth.yandex.ru

  1. Откройте oauth.yandex.ru/client/new под тем аккаунтом Яндекса, где подтверждены ваши сайты.
  2. Название — любое, например seo-api.
  3. Платформа — «Веб-сервисы», Redirect URI — https://oauth.yandex.ru/verification_code.
  4. В «Доступ к данным» найдите Яндекс Вебмастер и отметьте права:
    • webmaster:hostinfo — чтение данных о сайтах: запросы, индексация, ИКС, проблемы. Для выгрузок хватает его;
    • webmaster:verify — добавление сайтов и подтверждение прав. Нужен, только если программа будет добавлять сайты.
  5. Если тем же токеном будете читать Метрику, отметьте и Яндекс Метрика → metrika:read.
  6. Нажмите «Создать приложение» и скопируйте ClientID.

Условия API требуют, чтобы у каждого пользователя было своё приложение. Поэтому программы, которые работают с Вебмастером, просят создать приложение, а не дают общее.

03

Шаг 2. Как получить OAuth-токен

Откройте в браузере ссылку, подставив свой ClientID:

https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID

Нажмите «Разрешить» — на странице появится токен вида y0_AgAAA…. Это и есть OAuth-токен: передавайте его в заголовке Authorization: OAuth <токен>.

Токен для API Вебмастера живёт 6 месяцев. Когда он истечёт, запросы вернут 401 Unauthorized — откройте ту же ссылку ещё раз и замените токен. Программам, которые работают постоянно, удобнее схема с кодом подтверждения и refresh-токеном: тогда токен обновляется сам.

Токен — доступ к вашему аккаунту Вебмастера. Не пересылайте его в чат и не храните в коде, который уходит в репозиторий: держите в файле .env или в настройках программы.

04

Шаг 3. Узнайте user_id и host_id

Все запросы к данным идут по адресу https://api.webmaster.yandex.net/v4/user/{user_id}/…. Сначала узнайте свой user_id:

curl -H "Authorization: OAuth y0_ВАШ_ТОКЕН" https://api.webmaster.yandex.net/v4/user
# {"user_id": 123456789}

Потом список сайтов:

curl -H "Authorization: OAuth y0_ВАШ_ТОКЕН" https://api.webmaster.yandex.net/v4/user/123456789/hosts

В ответе у каждого сайта есть host_id — протокол, домен и порт через двоеточие, например https:example.ru:443, — и поле verified. Данные отдаются только по сайтам с verified: true и по главному зеркалу (main_mirror).

05

Выгрузите популярные запросы

curl -H "Authorization: OAuth y0_ВАШ_ТОКЕН" \
  "https://api.webmaster.yandex.net/v4/user/123456789/hosts/https:example.ru:443/search-queries/popular?order_by=TOTAL_SHOWS&query_indicator=TOTAL_SHOWS&query_indicator=TOTAL_CLICKS&query_indicator=AVG_SHOW_POSITION&limit=500"
ПараметрЧто значит
order_byсортировка: TOTAL_SHOWS или TOTAL_CLICKS
query_indicatorпоказатели: показы, клики, средняя позиция показа и клика — можно несколько
device_type_indicatorустройства: ALL, DESKTOP, MOBILE_AND_TABLET, MOBILE, TABLET
date_from, date_toпериод; без них — последняя неделя
limit, offsetдо 500 строк за запрос; всего — до 3000 запросов за период

Если в ответе date_from позже запрошенной даты, более ранних данных по сайту у Вебмастера нет.

То же на Python — несколько строк с библиотекой httpx или requests: заголовок Authorization: OAuth <токен>, те же адреса.

06

Ограничения, о которых стоит знать

  • История короткая. Вебмастер отдаёт запросы за ограниченный период. Старые дни API позже не вернёт — если нужна история за год, выгружайте данные регулярно и копите у себя.
  • Только подтверждённые сайты и главные зеркала. По остальным хостам данных не будет.
  • Данные отстают. Свежие дни появляются с задержкой, иногда заметной.
  • Даты — по Москве. При сравнении с Search Console ряды могут сдвигаться на несколько часов.
07

Частые ошибки

Что видитеЧто делать
401 Unauthorizedтокен истёк или скопирован не полностью — получите новый
403 при запросе к сайтуу приложения нет права webmaster:hostinfo или сайт не подтверждён в этом аккаунте
404 по host_idневерный формат: нужен https:example.ru:443, а не адрес сайта
Пустой список запросовнеглавное зеркало, нет данных за период или слишком свежие даты
Пустой список сайтовтокен получен в другом аккаунте Яндекса
08

Готовые инструменты вместо своего кода

Тот же токен подходит для готовых инструментов:

Как получить OAuth-токен для API Яндекс Вебмастера

  1. 1

    Создайте приложение

    Откройте oauth.yandex.ru/client/new, выберите платформу «Веб-сервисы» и Redirect URI https://oauth.yandex.ru/verification_code.

  2. 2

    Выберите права

    В «Доступ к данным» отметьте Яндекс Вебмастер — webmaster:hostinfo (чтение) и при необходимости webmaster:verify.

  3. 3

    Скопируйте ClientID

    После создания приложения скопируйте его ClientID.

  4. 4

    Получите токен

    Откройте https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID, нажмите «Разрешить» и скопируйте токен.

  5. 5

    Узнайте user_id

    Запрос GET https://api.webmaster.yandex.net/v4/user с заголовком Authorization: OAuth токен вернёт ваш user_id.

Частые ошибки

  • Взять чужое приложение или чужой токен — условия API требуют своё приложение, а чужой токен даёт доступ к чужому аккаунту.
  • Ждать данных по сайту, права на который не подтверждены, или по неглавному зеркалу.
  • Выгружать популярные запросы раз в месяц и удивляться, что старой истории нет, — копите данные регулярно.
  • Хранить токен в коде, который уходит в репозиторий или чат.
  • Забыть про срок жизни токена — через 6 месяцев запросы начнут возвращать 401.
Вопросы

Вопросы об API Вебмастера

Как получить токен для API Яндекс Вебмастера?

Получить токен для API Яндекс Вебмастера можно за 2 минуты: создайте приложение на oauth.yandex.ru с платформой «Веб-сервисы» и правом webmaster:hostinfo, откройте ссылку https://oauth.yandex.ru/authorize?response_type=token&client_id= со своим ClientID и скопируйте токен со страницы.

Сколько живёт OAuth-токен Вебмастера?

OAuth-токен для API Вебмастера живёт 6 месяцев — так сказано в документации API. Когда он истечёт, запросы вернут 401: откройте ту же ссылку авторизации ещё раз и замените токен.

Бесплатен ли API Вебмастера?

API Яндекс Вебмастера бесплатный. Ограничение одно — правила использования: у каждого пользователя должно быть своё приложение, а действия приложения не должны противоречить условиям API.

Почему в API меньше данных, чем в интерфейсе?

В API меньше данных, чем в интерфейсе, когда сайт не подтверждён, запрос идёт к неглавному зеркалу или период выходит за пределы того, что хранит Вебмастер. Популярные запросы ограничены 3000 строк за период.

Как получить историю запросов дольше нескольких недель?

Историю запросов дольше нескольких недель получают одним способом — выгружают данные регулярно, например раз в день, и копят у себя: в таблице, базе или чекере позиций. Старые дни API позже не отдаст.

Подходит ли один токен для нескольких сайтов?

Один токен подходит для всех сайтов, подтверждённых в аккаунте Яндекса, которым вы вошли. Если сайты в разных аккаунтах, получите токен в каждом.

Можно ли одним токеном работать с Вебмастером и Метрикой?

Одним токеном можно работать и с Вебмастером, и с Метрикой, если при создании приложения отметить права обоих сервисов: webmaster:hostinfo и metrika:read.

Обсудим ваш проект?

Напишите, что за сайт и какая задача — отвечу сам, обычно в течение дня.

Источники и обновления

Источники

  1. Яндекс — API Вебмастера: начало работы
  2. Яндекс — API Вебмастера: как получить OAuth-токен
  3. Яндекс — API Вебмастера: популярные запросы
  4. Яндекс — API Вебмастера: список сайтов

История обновлений

  • 8 ноября 2026Первая версия, сверено с документацией API Вебмастера 08.11.2026

Читать дальше

Вопросы по теме