Google Search Console API: доступ, области, лимиты и первый запрос

API Search Console возвращает те же данные об эффективности, что и отчёт, но с гораздо меньшими ограничениями по строкам, и бесплатен в рамках квоты использования. Чтобы им пользоваться, зарегистрируйте приложение в Google API Console, активируйте API Search Console, запросите у пользователя область доступа, авторизуйтесь через OAuth 2.0 и вызовите searchanalytics.query. Данные об эффективности ограничены 50 тыс. строк в день на тип поиска на ресурс, действуют квоты. Сторону доступа Google описывает в материале Authorize Requests.

Доступ, области и OAuth

Зарегистрируйте приложение в Google API Console, чтобы получить идентификатор клиента и секрет клиента, и активируйте API Search Console для проекта. Затем выберите область доступа. webmasters.readonly даёт доступ только на чтение, а webmasters — на чтение и запись; запрашивайте наименьшую нужную и не просите область чтения и записи для скрипта отчётности, если только не нужно добавлять сайты или отправлять sitemap.

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

Первый запрос

Вызовите searchanalytics.query с датой начала, датой окончания и нужными измерениями. Даты указываются по тихоокеанскому времени. Результаты отсортированы по кликам, а по умолчанию возвращаются только окончательные данные; dataState «all» включает свежие данные. Лимит строк — от 1 до 25 000, по умолчанию 1 000, а startRow переходит к следующей странице (searchanalytics.query). API поддерживает фильтрацию, сортировку и агрегацию, как отчёты, но не произвольный SQL; для него используйте массовую выгрузку в BigQuery.

Строк он возвращает больше, чем интерфейс: экспорт отчёта обрезается до 1 000 строк, а API возвращает до 50 тыс. строк в день на тип поиска на ресурс (экспорт данных через API). Дни без данных при группировке по дате пропускаются, поэтому не считайте отсутствующий день нулевым.

Квоты и что значит «превышена квота»

Search Analytics допускает 1 200 запросов в минуту на сайт и на пользователя и 40 000 в минуту и 30 000 000 в день на проект; проверка URL допускает 2 000 в день и 600 в минуту на сайт (лимиты использования). Лимиты складываются. Пример Google: пользователь A может делать до 1 200 запросов в минуту суммарно по трём своим сайтам, а пользователи A и B — до 1 200 в минуту суммарно по одному общему сайту. Лимиты уровня проекта действуют на всех, кто использует один ключ проекта Cloud.

Ошибка «превышена квота» выглядит одинаково для любой квоты. Если помогает ожидание в 15 минут, вы упёрлись в краткосрочную квоту нагрузки, измеряемую 10-минутными отрезками, поэтому распределяйте запросы в течение дня. Если уже один запрос внутри 10-минутного окна завершается ошибкой, вы упёрлись в суточную квоту нагрузки. Некоторые запросы просто дороги: группировка или фильтрация по странице или запросу затратна, а по странице и запросу вместе — самая затратная, причём стоимость растёт с диапазоном дат. Уберите группировку, сократите диапазон и не просите те же данные повторно.

Разобранный пример постраничной загрузки

Чтобы получить данные по запросам и страницам за 28 дней, запрашивайте по одному дню. В дне не более 50 000 строк, то есть 2 запроса по 25 000 (startRow 0 и 25 000), поэтому 28 дней — 56 запросов. Частота вызовов намного ниже 1 200 в минуту; ограничивает квота нагрузки, поэтому помогают короткий диапазон и по одному дню. Кэшируйте результат: повтор большого запроса зря расходует квоту нагрузки.

Стоимость и SEOKit

Сам API бесплатен в рамках квоты использования. Инструмент экспорта SEOKit и MCP-сервер используют этот же API и подчиняются тем же лимитам; что это значит на практике, показывает наша статья о строках и столбцах экспорта.

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

Как пользоваться отчётом «Эффективность»: Лимиты и варианты экспорта в интерфейсе. Документация: фильтры по умолчанию и экспорт: Инструмент экспорта в рабочем пространстве. Руководство: пять способов подключить ChatGPT: API, экспорт и BigQuery в сравнении.