Логотип seo-prodvizhenie-biznesa.ru
+7 (921) 333-77-45

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

Как выгрузить запросы и страницы из Яндекс Вебмастера через API и сверить цифры с интерфейсом
Анатолий Кузнецов

Анатолий Кузнецов
SEO-оптимизатор с 20-летним стажем. Автор блога seo-prodvizhenie-biznesa.ru о продвижении и доработке сайтов.

Как выгрузить запросы и страницы из Яндекс Вебмастера через API, если в кабинете много данных, а ручные таблицы неудобно сравнивать? Начинайте с выбора отчёта. Под общим названием API доступны разные методы: популярные запросы, мониторинг, общая история и расширенная выгрузка по URL. Они не обязаны возвращать одинаковый набор строк.

Ниже — рабочий порядок для владельца сайта и исполнителя: выбрать источник, получить данные, сохранить параметры и сверить результат с интерфейсом. Документация проверена 19 ноября 2026 года. Код приведён как пример чтения собственного подтверждённого сайта, без реальных токенов и закрытых данных.

Для SEO-продвижения сайта автоматизация полезна только тогда, когда понятно, что именно измерено. Красивый отчёт с неверным периодом или другой версией домена может привести к неправильным решениям быстрее, чем ручная работа. Поэтому сначала проверяем один небольшой срез, затем расширяем выгрузку.

1. Определите задачу до выбора метода API

Сформулируйте вопрос, на который должен отвечать файл. Например: какие страницы получают показы по интересующей группе запросов; как менялись клики у важной услуги; какие запросы появились у конкретного URL. Это разные аналитические задачи, и не каждой нужен полный экспорт всех доступных данных.

Официальный обзор ресурсов API помогает выбрать подходящий метод. Для мониторинга используется query-analytics/list, для популярных запросов — отдельный ресурс search-queries/popular, для общей истории — search-queries/all/history. Расширенная выгрузка по страницам имеет собственную процедуру создания и получения результата.

Не начинайте с требования «дайте все ключи сайта». Оно не определяет период, поверхность поиска, регион, устройство и нужную детализацию. В ответ можно получить технически корректный файл, который не отвечает на задачу руководителя. Лучше заранее записать, какая строка должна присутствовать в контрольном примере и почему.

Условный пример: владелец хочет понять изменение интереса к одной услуге. Сначала выбирают её страницу и одинаковые периоды сравнения. Затем проверяют доступные показатели и ограничения отчёта. Поиск всех запросов по домену с произвольной сортировкой не заменяет эту постановку.

Разделите регулярный мониторинг и разовый анализ истории. Для первого важны повторяемые параметры и надёжное сохранение результата. Для второго может понадобиться другой метод с более длинным доступным периодом. Один универсальный скрипт без описания источника легко скрывает это различие.

2. Не смешивайте популярные запросы и выгрузку по URL

Отчёт популярных запросов отвечает своей задаче и не равен перечню всех сочетаний «запрос — страница». Мониторинг позволяет работать с запросами и URL, но имеет собственную глубину данных и параметры. Расширенная выгрузка по URL предназначена для другой процедуры получения подробного результата.

Задача Где начать проверку Что сохранить для сверки
Популярные запросы Метод популярных поисковых запросов Порядок сортировки, показатели, период
Текущий мониторинг запросов и страниц query-analytics/list Тип строк, фильтры, устройства и регионы
Общая динамика показателей История по всем запросам Даты и выбранные индикаторы
Запросы конкретных URL за доступную историю Расширенная выгрузка по URL Список страниц, доступные даты, лимит и задача
Проверка расхождения с кабинетом Соответствующий раздел интерфейса Те же измерения и момент получения

В документации мониторинга указан доступ за последние две недели и размер страницы ответа до 500 записей. Это ограничение конкретного метода. Его нельзя переносить на всю историю Вебмастера или использовать как аргумент, что более старые данные вообще недоступны.

В расширенной выгрузке по URL описана доступная история до 550 дней и отдельный учёт лимита по сочетанию страницы и дня. Перед большой задачей проверьте текущие доступы и даты именно своего сайта. Не считайте один HTTP-вызов одной бесплатной единицей независимо от объёма.

Для владельца полезен простой вопрос исполнителю: какой метод выбран и какое измерение представляет одна строка файла? Если ответ звучит только как «данные из Яндекса», отчёт ещё недостаточно описан. Воспроизводимость начинается с названия источника, а не с оформления диаграммы.

3. Подготовьте доступ к нужному подтверждённому сайту

Используйте предусмотренную авторизацию API Вебмастера. Полученный доступ должен относиться к нужному пользователю и сайту. Наличие аккаунта Яндекса не означает автоматически право читать данные любого домена из знакомого списка.

Сначала получите идентификатор пользователя и список доступных сайтов. Затем выберите точную версию: протокол, доменное имя и нужный хост. Не составляйте host-id вручную по памяти, когда его можно получить штатным запросом. Ошибка с www или HTTP может дать данные другого объекта либо отказ доступа.

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

Не выдавайте доступ шире необходимого ради удобства одного экспорта. Для организационной приёмки зафиксируйте, кто владеет приложением и где описано восстановление интеграции. Когда сотрудник меняется, бизнес должен понимать, от какого доступа зависит регулярный отчёт и кому принадлежит его настройка.

Перед массовым сбором выполните небольшой запрос и проверьте его смысл. Технический ответ 200 подтверждает обработку обращения, но не правильность выбранного сайта. Сопоставьте домен в ответе и контрольный объект из кабинета. Так ошибку выбора можно обнаружить до накопления месячной истории.

4. Пример чтения мониторинга для своего сайта

Следующий пример показывает последовательность: получить пользователя, найти собственный хост, запросить одну страницу мониторинга и сохранить исходный JSON. Укажите свой домен вместо example.ru и передайте токен через окружение YWM_TOKEN. Это не готовый экспорт всей истории и не программа, которая меняет настройки сайта.

import json
import os
from pathlib import Path
import requests

api = "https://api.webmaster.yandex.net/v4"
headers = {"Authorization": "OAuth " + os.environ["YWM_TOKEN"]}

def read(path):
    response = requests.get(api + path, headers=headers, timeout=30)
    response.raise_for_status()
    return response.json()

uid = read("/user/")["user_id"]
hosts = read(f"/user/{uid}/hosts/")["hosts"]
host = next(h for h in hosts
            if h["ascii_host_url"].rstrip("/") == "https://example.ru")
hid = host["host_id"]
params = {
    "offset": 0,
    "limit": 100,
    "device_type_indicator": "ALL",
    "search_location": "WEB_LOCATION",
    "text_indicator": "QUERY"
}
response = requests.post(
    f"{api}/user/{uid}/hosts/{hid}/query-analytics/list",
    headers=headers, json=params, timeout=30
)
response.raise_for_status()
result = response.json()
Path("webmaster-monitoring.json").write_text(
    json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
)

Перед рабочим запуском сравните пример с актуальной схемой метода. Значения фильтров, доступность полей и структура ответа должны соответствовать документации, а не предположению разработчика. В частности, не добавляйте в тело произвольные date_from и date_to только потому, что они есть у другого метода.

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

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

5. Как организовать полную обработку страниц ответа

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

Уникальность строки выбирайте по реальным измерениям ответа. Одинаковый текст запроса может относиться к разным датам, регионам и страницам. Удаление дублей только по фразе способно потерять полезные сведения. Сначала опишите ключ записи и проверьте его на небольшой контрольной выборке.

Сохраняйте исходные значения без преждевременного округления. Для удобного отчёта можно создать отдельные вычисляемые колонки, но сырой ответ должен оставаться доступным. Тогда при расхождении не придётся угадывать, какая цифра была в API до преобразования таблицей.

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

Проверьте кодировку при открытии CSV и правила разделения колонок. Русские запросы, запятые и кавычки не должны разрушать структуру файла. Для контрольного просмотра выберите строки с такими символами. Открывающаяся без ошибки таблица ещё не доказывает, что значения попали в нужные столбцы.

6. Расширенная выгрузка по URL: создание задачи и результат

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

До запуска проверьте доступные даты и лимиты соответствующими методами. Выберите минимальный набор URL и дней, который отвечает на вопрос. Условный анализ десяти страниц за неделю и выгрузка всего каталога за полтора года требуют совершенно разного объёма. Не расширяйте задачу только потому, что интерфейс позволяет вписать больше адресов.

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

Состояние проверяйте по методу получения статуса выгрузки. Ссылку на готовый результат нужно обработать в предусмотренный срок. Не считайте файл сохранённым только потому, что в журнале появилась ссылка: проверьте скачивание, размер и чтение данных.

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

7. Как сверить API с интерфейсом Вебмастера

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

Сравнивайте одинаковые метрики. Показы, клики, средняя позиция показа и позиция клика — не взаимозаменяемые значения. Уточните название индикатора в выгрузке и соответствующую колонку интерфейса. Перевод заголовка в таблице не должен скрывать исходное определение.

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

Если не сходится итог, сначала сравните несколько отдельных строк и промежуточные суммы. Найдите уровень, где появляется разница: набор URL, фильтр запросов, даты или преобразование файла. Такой разбор быстрее, чем переписывание всего скрипта без установленной причины.

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

8. Ошибки доступа, лимиты и временные сбои

Разделите ошибки HTTP и содержательные состояния отчёта. Отказ доступа не означает отсутствие поисковых показов. Ответ сервера о временной недоступности не является нулевой статистикой. Скрипт должен сохранять причину сбоя и не подставлять нули в успешный отчёт вместо неполученных данных.

При ошибке пользователя проверьте соответствие токена и идентификатора. При проблеме хоста — фактические права и выбранную версию сайта. При ограничении частоты соблюдайте правила метода и контролируемые повторы. Ротация случайных аккаунтов ради обхода лимита не является правильным обслуживанием интеграции.

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

В журнале сохраняйте статус, время, безопасные параметры и идентификатор задачи. Токен и другие секреты исключайте из сообщений об ошибке. Удобный диагностический файл позволяет передать исполнителю причину без копирования всей среды сервера и личного аккаунта.

Если API временно недоступен, используйте подходящий штатный отчёт кабинета и явно отметьте смену источника. Не объединяйте незаметно ручную и автоматическую выгрузки в одну непрерывную историю. Разные методы сравнивают после согласования условий и структуры данных.

9. Как принять автоматизацию у разработчика

Попросите передать описание задачи, методов и структуры результата. Укажите расписание, место хранения исходных ответов, обработку ошибок и порядок восстановления после сбоя. Скрипт, который запускается только с ноутбука исполнителя без инструкции, ещё не является обслуживаемым процессом бизнеса.

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

Отдельно проверьте, что регулярный запуск не создаёт повторные задачи и не дописывает один день дважды. Результат должен обновляться по согласованному правилу. Для владельца важна возможность понять, откуда взялась цифра, а не только увидеть уведомление об успешном выполнении программы.

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

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

10. Частые вопросы о выгрузке Вебмастера

API отдаёт все запросы одним вызовом?

Это зависит от метода и объёма. Проверяйте пагинацию, доступные даты и ограничения выбранного источника. Отдельная страница успешного ответа не доказывает полноту выгрузки. Для асинхронного экспорта нужна проверка завершения задачи и сохранённого файла.

Почему данные не совпали с кабинетом?

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

Можно хранить токен в общей таблице с отчётом?

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

Если ответ пустой, показы равны нулю?

Не обязательно. Установите успешность запроса, применённые фильтры и смысл ответа по документации. Пустая выборка, отсутствующее значение и ошибка получения не должны превращаться в одно состояние.

Нужна ли выгрузка, если сайт небольшой?

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

Коротко

  • Сначала определите вопрос и нужное измерение данных.
  • Не смешивайте популярные запросы, мониторинг и расширенный экспорт по URL.
  • Проверяйте доступ, точный хост, даты и лимиты выбранного метода.
  • Сохраняйте исходные ответы, параметры и состояние задач без токенов.
  • Сверяйте API и кабинет в одинаковых условиях.
  • Принимайте автоматизацию по воспроизводимости, полноте и обработке сбоев.

Разобрать выгрузки, расхождения отчётов и приоритеты работ можно на консультации по аналитике Яндекс Вебмастера.

Увеличьте позиции и продажи вашего сайта

Профессиональное SEO-продвижение с гарантией результата. Выберите подходящую услугу:

Анатолий Кузнецов — SEO-оптимизатор

Остались вопросы по продвижению?

Меня зовут Анатолий Кузнецов, я SEO-оптимизатор с 20-летним стажем. Разберу ваш сайт, отвечу на вопросы и подскажу, что улучшить для роста позиций в Яндексе.

Связаться со мной →

Вопросы и обсуждение

Редакционные примеры вопросов для разбора. Это не опубликованные комментарии посетителей и не отзывы клиентов.

Евгений Крылов

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

Анатолий Кузнецов автор

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

Арина Самойлова

В нашей таблице потерялись кавычки и часть запросов разъехалась по столбцам. Сам файл открывался нормально, поэтому ошибку заметили не сразу.

Борис Тимофеев

Если один запрос встречается у нескольких страниц, удалять дубли по тексту фразы нельзя? Мы как раз так сокращали итоговый файл.

Анатолий Кузнецов автор

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

Валентина Савина

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

Дмитрий Корнеев

Для расширенного экспорта сохранили номер задачи, но файл не скачали. Можно считать, что данные уже получены, если есть ссылка?

Анатолий Кузнецов автор

Нет, отдельно проверьте фактическое скачивание результата. Сохраните файл и убедитесь, что его структура читается правильно. У ссылки на результат есть предусмотренный срок доступности. В журнале разделяйте готовность задачи и сохранение данных. Это позволит обнаружить незавершённый этап до потери результата.

Зинаида Белова

Сравнивали мобильные устройства с общим отчётом кабинета. Цифры были похожи, но не одинаковы, и мы долго искали ошибку в округлении.

Кирилл Прохоров

В конце дня данные кабинета обновились, а утренняя выгрузка осталась прежней. Как организовать приёмку, чтобы не спорить о разных состояниях?

Анатолий Кузнецов автор

Запишите время получения обеих версий. Для первичной сверки выберите завершённый период. Согласуйте одинаковые фильтры и показатели. Затем сравните несколько строк и промежуточные суммы. Если источник обновился, повторите тот же срез и сохраните обе квитанции.

Лариса Селиванова

Среднее CTR по строкам у нас оказалось заметно выше отношения всех кликов ко всем показам. Теперь понятно, почему способ агрегации надо описывать отдельно.

Марк Осипов

После обрыва соединения скрипт запускал экспорт заново и создавал несколько одинаковых задач. Что добавить в регламент?

Анатолий Кузнецов автор

Сохраняйте идентификатор созданной задачи сразу после получения. После потери ответа сначала проверяйте фактическое состояние. Отделите повтор чтения от повторного создания экспорта. Установите понятный критерий завершения и обработки ошибки. В журнале должно быть видно, какой результат относится к какой задаче.

Нина Чередниченко

Для маленького сайта пока хватает ручного отчёта. Хочу сначала определить регулярный вопрос, а потом уже платить за автоматизацию.

Олег Наумов

Выгрузку полезно принимать по контрольному примеру. Большая диаграмма выглядит убедительно даже тогда, когда выбран не тот хост.

Полина Киселёва

Добавлю в задание разработчику список исходников и инструкцию восстановления. Сейчас всё работает только с его ноутбука, и это неудобно для бизнеса.

Оставьте комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

 Отправляя форму, вы принимаете правила конфиденциальности 
Прокрутить вверх