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
Что отдаёт API Вебмастера
API Вебмастера — те же данные, что в кабинете Яндекс Вебмастера, только по запросу из программы:
| Что | Что внутри |
|---|---|
| Сайты | список сайтов аккаунта, подтверждены ли права, главное зеркало |
| Сводка | ИКС, число страниц в поиске и исключённых, проблемы сайта по уровням |
| Популярные запросы | показы, клики, средняя позиция показа и клика, фильтр по устройствам |
| Индексация | история обхода по кодам ответа, страницы в поиске, исключённые страницы |
| Ссылки | внешние ссылки на сайт |
| Действия | переобход страниц, добавление файлов Sitemap |
Чего в API нет: позиций конкурентов, частотности запросов и снимка выдачи. Позиция — средняя за период, как в отчёте «Запросы». Данные есть только по сайтам с подтверждёнными правами.
Шаг 1. Создайте приложение на oauth.yandex.ru
- Откройте oauth.yandex.ru/client/new под тем аккаунтом Яндекса, где подтверждены ваши сайты.
- Название — любое, например
seo-api. - Платформа — «Веб-сервисы», Redirect URI —
https://oauth.yandex.ru/verification_code. - В «Доступ к данным» найдите Яндекс Вебмастер и отметьте права:
webmaster:hostinfo— чтение данных о сайтах: запросы, индексация, ИКС, проблемы. Для выгрузок хватает его;webmaster:verify— добавление сайтов и подтверждение прав. Нужен, только если программа будет добавлять сайты.
- Если тем же токеном будете читать Метрику, отметьте и Яндекс Метрика →
metrika:read. - Нажмите «Создать приложение» и скопируйте ClientID.
Условия API требуют, чтобы у каждого пользователя было своё приложение. Поэтому программы, которые работают с Вебмастером, просят создать приложение, а не дают общее.
Шаг 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 или в настройках программы.
Шаг 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).
Выгрузите популярные запросы
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 <токен>, те же адреса.
Ограничения, о которых стоит знать
- История короткая. Вебмастер отдаёт запросы за ограниченный период. Старые дни API позже не вернёт — если нужна история за год, выгружайте данные регулярно и копите у себя.
- Только подтверждённые сайты и главные зеркала. По остальным хостам данных не будет.
- Данные отстают. Свежие дни появляются с задержкой, иногда заметной.
- Даты — по Москве. При сравнении с Search Console ряды могут сдвигаться на несколько часов.
Частые ошибки
| Что видите | Что делать |
|---|---|
401 Unauthorized | токен истёк или скопирован не полностью — получите новый |
403 при запросе к сайту | у приложения нет права webmaster:hostinfo или сайт не подтверждён в этом аккаунте |
404 по host_id | неверный формат: нужен https:example.ru:443, а не адрес сайта |
| Пустой список запросов | неглавное зеркало, нет данных за период или слишком свежие даты |
| Пустой список сайтов | токен получен в другом аккаунте Яндекса |
Готовые инструменты вместо своего кода
Тот же токен подходит для готовых инструментов:
- MCP-сервер Яндекс Вебмастера — подключает Вебмастер к Claude, Cursor и другим ИИ-агентам: вы спрашиваете обычными словами, агент сам выгружает запросы, ИКС и проблемы сайта.
- Тот же токен с правом
metrika:readработает и с MCP-сервером Яндекс Метрики. - Для Google порядок другой — см. Google Search Console API.
Как получить OAuth-токен для API Яндекс Вебмастера
- 1
Создайте приложение
Откройте oauth.yandex.ru/client/new, выберите платформу «Веб-сервисы» и Redirect URI https://oauth.yandex.ru/verification_code.
- 2
Выберите права
В «Доступ к данным» отметьте Яндекс Вебмастер — webmaster:hostinfo (чтение) и при необходимости webmaster:verify.
- 3
Скопируйте ClientID
После создания приложения скопируйте его ClientID.
- 4
Получите токен
Откройте https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID, нажмите «Разрешить» и скопируйте токен.
- 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.
Обсудим ваш проект?
Напишите, что за сайт и какая задача — отвечу сам, обычно в течение дня.
Источники и обновления
Источники
История обновлений
- 8 ноября 2026Первая версия, сверено с документацией API Вебмастера 08.11.2026