Google Search Console API нужен, когда данных в интерфейсе недостаточно для повторяемого анализа: он позволяет забирать показатели поиска программно, сохранять одинаковые настройки запросов и обновлять отчёты без ручного экспорта. Для полной выгрузки нельзя ограничиваться первым ответом. У метода Search Analytics значение rowLimit по умолчанию равно 1 000, максимум — 25 000, а следующие строки запрашиваются через startRow. Даже после пагинации Google возвращает самые значимые строки в пределах внутренних ограничений, поэтому результат нельзя называть полным журналом всех запросов.
Ниже — практическая схема для человека, которому нужны страницы, запросы, клики, показы, CTR и позиция. Она отделяет Search Analytics от URL Inspection и управления sitemap, использует доступ только для чтения и показывает, как проверить выгрузку числами. У готового файла должна сохраняться карточка запроса: свойство, даты, тип поиска, измерения, фильтры, режим данных и время получения.
Какие задачи решает Google Search Console API?
Search Console API — это несколько ресурсов с разными назначениями. Через них можно читать данные эффективности, просматривать доступные свойства, работать с sitemap и проверять сведения об индексированной версии отдельного URL. Официальный обзор API подчёркивает, что для обращения к свойству нужны соответствующие права в Search Console.
| Задача | Метод | Что получится | Главное ограничение |
|---|---|---|---|
| Выгрузить клики и показы | searchAnalytics.query | Строки по датам, страницам, запросам, странам, устройствам и другим измерениям | Возвращаются верхние строки; API не обещает все возможные сочетания |
| Проверить сведения об URL | urlInspection.index.inspect | Статус индексирования, канонический адрес, сведения об обходе и обнаруженные проблемы | Проверяется версия в индексе, а не опубликованная страница в реальном времени |
| Получить список sitemap | sitemaps.list | Отправленные карты сайта и их состояние | Это не список всех URL сайта |
| Узнать доступные свойства | sites.list | Свойства, к которым есть доступ у авторизованного пользователя | Набор зависит от прав учётной записи |
Такое разделение предотвращает типичную ошибку: Search Analytics нельзя использовать как проверку индексирования, а URL Inspection API — как массовый тест опубликованной версии. В описании URL Inspection прямо указано, что метод сообщает о версии, известной индексу Google.
Если сначала нужно разобраться, какой вопрос решает каждый отчёт интерфейса, используйте обзор возможностей Search Console. API имеет смысл подключать после определения нужного отчёта и уровня агрегации.
Почему стандартная выгрузка заканчивается на 1 000 строках?
В теле запроса Search Analytics параметр rowLimit необязателен. Если его не передать, сервис использует 1 000 строк. Допустимый диапазон — от 1 до 25 000. Параметр startRow задаёт нулевой индекс первой строки следующей порции. Эти значения приведены в справочнике метода query.
Увеличение rowLimit до 25 000 решает только размер одного ответа. Для продолжения нужно повторить тот же запрос, изменив startRow с 0 на 25 000, затем на 50 000. Даты, измерения, фильтры, тип поиска и режим данных при этом должны оставаться одинаковыми. Если менять параметры между страницами, строки уже нельзя считать частями одной выгрузки.
{
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"type": "web",
"dimensions": ["page", "query"],
"rowLimit": 25000,
"startRow": 0,
"dataState": "final"
}Свойство указывается в адресе запроса. Для URL-prefix оно содержит протокол и завершающий слеш, например https://example.com/; для доменного свойства используется форма sc-domain:example.com. Это технические примеры синтаксиса, а не адрес исследуемого проекта.
Как выгрузить больше 1 000 строк без пропусков между пакетами?
Алгоритм останавливается, когда ответ пуст или содержит меньше запрошенных 25 000 строк. Google отдельно описывает постраничную выгрузку Search Analytics: если объём равен точной границе пакета, следующий запрос вернёт пустой ответ. Поэтому пустая третья страница после двух заполненных страниц — нормальное подтверждение конца, а не ошибка.
start_row = 0
batch_size = 25000
while True:
body["startRow"] = start_row
body["rowLimit"] = batch_size
rows = request_search_analytics(body)
save(rows)
if len(rows) < batch_size:
break
start_row += batch_sizeНаш расчёт. Если один день и один тип поиска дают ровно 50 000 доступных строк, потребуются три обращения: два ответа по 25 000 и один пустой ответ, который фиксирует границу. Для 31 дня при ежедневной выгрузке одного типа это до 93 обращений: 31 × 3. Это расчёт количества запросов для данного сценария, а не обещание, что каждое свойство вернёт 50 000 строк.
После каждого пакета сохраните номер страницы и число строк. После объединения проверьте уникальность набора измерений, например date + page + query + country + device. Дубликат такого ключа указывает на повторное сохранение пакета или несовпадающие параметры, но не доказывает ошибку Google.
Почему даже пагинация не гарантирует абсолютно все запросы?
Search Analytics сортирует результаты по кликам и предупреждает, что из-за внутренних ограничений возвращает верхние строки, а не гарантированно все строки данных. Отдельная инструкция о получении данных эффективности указывает максимум 50 000 строк в день для одного типа поиска. Поэтому формулировка «полная выгрузка» означает максимально доступную выборку при заданных параметрах, а не список каждой анонимизированной или редкой комбинации.
Чтобы сохранить больше доступных строк, Google рекомендует запрашивать данные отдельно по дням и типам поиска. Широкий диапазон удобнее, но он не увеличивает дневной предел. Разбиение на устройства или страны создаёт дополнительные запросы и может менять агрегацию; это следует делать для конкретного анализа, а не ради искусственного увеличения файла.
Как настроить доступ без передачи лишних прав?
Для данных пользователя нужен OAuth 2.0. Обычный API key не заменяет авторизацию Search Console. В инструкции Google по авторизации перечислены два основных scope: webmasters.readonly для чтения и webmasters для чтения и изменения. Для выгрузки эффективности выбирайте scope только для чтения.
- Создайте проект в Google Cloud Console и включите Search Console API.
- Настройте экран согласия OAuth и создайте клиент для используемого типа приложения.
- Запросите
https://www.googleapis.com/auth/webmasters.readonly. - Авторизуйте пользователя, у которого есть доступ к нужному свойству.
- Храните refresh token как секрет и не записывайте его в отчёты или репозиторий.
Google перечисляет эти предварительные условия в руководстве по подготовке приложения. Права внутри Search Console продолжают действовать: токен не открывает свойства, которых нет у пользователя.
Какие квоты учитывать до запуска массовой выгрузки?
Квоты зависят от ресурса. Согласно актуальной странице ограничений, Search Analytics допускает 1 200 запросов в минуту на сайт и на пользователя; для проекта указаны отдельные минутные и дневные пределы. Кроме количества запросов действует нагрузочная квота: запросы с группировкой или фильтрацией одновременно по странице и запросу дороже, а длинные диапазоны создают больше нагрузки.
URL Inspection ограничен 2 000 проверок в день и 600 в минуту для одного свойства. Это отдельный бюджет: им нельзя измерять эффективность, и его не следует тратить на повторную проверку неизменившихся URL. Для ошибок квоты используйте задержку с увеличением интервала и повтор, а не плотный бесконечный цикл.
| Сигнал | Проверка | Действие |
|---|---|---|
| Ответ содержит 25 000 строк | Есть ли следующая страница | Увеличить startRow на 25 000 |
| Ответ короче 25 000 строк | Параметры не менялись | Завершить этот срез |
| Ответ пуст на точной границе | Предыдущий пакет был полным | Зафиксировать конец, не считать ошибкой |
| Quota exceeded | Какой ресурс и какое окно квоты | Разнести запросы и повторить позже |
| Сумма деталей ниже агрегата | Уровень группировки и внутренние пределы | Хранить агрегат отдельно, описать ограничение |
Как проверить качество готового CSV или таблицы?
Сначала сравните не строки, а настройки. У двух файлов должны совпадать часовой смысл дат, тип поиска, режим final или all, измерения, фильтры и свойство. Затем посчитайте строки по пакетам, минимальную и максимальную дату, число уникальных ключей и сумму кликов с показами. CTR лучше пересчитать как сумма кликов / сумма показов, а среднюю позицию не следует усреднять повторно без понимания весов.
Для разового анализа можно использовать инструмент полной выгрузки GSC. Он избавляет от настройки OAuth-клиента и ручной пагинации, но не отменяет ограничения исходного API. Рядом с файлом всё равно сохраните параметры и дату получения.
Чего Search Console API не делает?
API не добавляет сайт в индекс, не отправляет произвольные страницы на ускоренное индексирование и не раскрывает скрытые запросы. Он не является сервисом проверки позиции в фиксированной выдаче: поле position — агрегированный показатель Search Console. URL Inspection API не выполняет live test, а Search Analytics не объясняет причину роста или падения.
Также API не исправляет качество исходной модели данных. Если объединить разные типы поиска, периоды и свойства без явных полей, большой файл будет выглядеть убедительно, но потеряет смысл. Автоматизация полезна только тогда, когда один и тот же запрос можно повторить и объяснить.
Что делать после первой выгрузки?
Сохраните конфигурацию и необработанный ответ до построения производных метрик. Сделайте отдельные таблицы для дневного агрегата и детальных строк. Затем проверьте одну задачу: например, какие страницы получают показы без кликов или какие запросы изменились между сопоставимыми периодами. Для разбора первых сигналов используйте материал о первых показах и кликах; он помогает не принимать короткий всплеск за устойчивую динамику.