Search Console API объединяет несколько ресурсов: Search Analytics, Sites, Sitemaps и URL Inspection. Для доступа к пользовательским данным требуется OAuth 2.0. Сервисный аккаунт тоже должен быть добавлен пользователем в Search Console с подходящими правами.
Что можно получить через API
Search Analytics возвращает клики, показы, CTR и позицию по измерениям query, page, country, device, date и другим доступным полям. Sites управляет списком ресурсов, Sitemaps — отправкой и чтением карт, URL Inspection — сведениями об индексированной версии URL.
API не полностью повторяет интерфейс. Некоторые отчёты и действия доступны только в Search Console, а запрос индексации обычных страниц через публичный Search Console API отсутствует. Google Indexing API предназначен только для поддерживаемых типов контента.
Что подготовить до начала
- Проект Google Cloud и включённый Google Search Console API.
- Настроенный OAuth consent screen и OAuth client либо сервисный аккаунт.
- Аккаунт или service account добавлен к ресурсу Search Console.
- Scopes и хранилище refresh token соответствуют минимальным правам.
Первое подключение к API
- Создайте проект Google Cloud и включите Search Console API.
- Настройте OAuth 2.0 client и redirect URI для вашего приложения.
- Получите согласие пользователя на webmasters.readonly или изменяющий scope.
- Вызовите sites.list и проверьте permissionLevel для нужного ресурса.
- Отправьте запрос searchanalytics.query или index.inspect и обработайте пагинацию и квоты.
Основные ресурсы
Подбирайте API по задаче, а не пытайтесь получить все данные одним запросом.
| Сигнал или статус | Что он означает | Что делать |
|---|---|---|
| Search Analytics | Эффективность поиска по измерениям | Фиксируйте период, фильтры и тип поиска |
| Sites | Список ресурсов и уровень доступа | Проверяйте точную строку siteUrl |
| Sitemaps | Список, отправка и удаление Sitemap | Не путайте отправку файла с индексированием URL |
| URL Inspection | Статус индексированной версии URL | Учитывайте квоту и дату последнего обхода |
Ошибки API
Чаще всего не совпадает строка ресурса или права OAuth.
| Проблема | Вероятная причина | Исправление |
|---|---|---|
| 403 insufficient permissions | Scope или роль пользователя недостаточны | Проверьте consent и доступ в Search Console |
| 404 site not found | Неверный формат Domain/URL-prefix | Копируйте siteUrl из sites.list |
| Invalid redirect URI | URL не зарегистрирован в OAuth client | Добавьте точное совпадение в Google Cloud |
| Quota exceeded | Слишком много запросов или строк | Добавьте кеш, backoff и пакетную обработку |
Контроль результата и приёмка работы
Перед контрольным прогоном подготовьте всё, от чего зависит результат: Проект Google Cloud и включённый Google Search Console API; Настроенный OAuth consent screen и OAuth client либо сервисный аккаунт; Аккаунт или service account добавлен к ресурсу Search Console; Scopes и хранилище refresh token соответствуют минимальным правам. Проверьте не только основной пример, но и второй URL или ресурс того же типа. В отчёте сохраните время, адрес проверяемого объекта, аккаунт и роль, фактический статус в интерфейсе, а для технической операции — HTTP-код и конечный URL.
Search Analytics означает: эффективность поиска по измерениям. Контрольное действие: фиксируйте период, фильтры и тип поиска. Sites означает: список ресурсов и уровень доступа. Контрольное действие: проверяйте точную строку siteurl. Sitemaps означает: список, отправка и удаление sitemap. Контрольное действие: не путайте отправку файла с индексированием url. URL Inspection означает: статус индексированной версии url. Контрольное действие: учитывайте квоту и дату последнего обхода.
Если воспроизводится «403 insufficient permissions», проверьте гипотезу «Scope или роль пользователя недостаточны» и выполните следующее: проверьте consent и доступ в search console. Если воспроизводится «404 site not found», проверьте гипотезу «Неверный формат Domain/URL-prefix» и выполните следующее: копируйте siteurl из sites.list. Если воспроизводится «Invalid redirect URI», проверьте гипотезу «URL не зарегистрирован в OAuth client» и выполните следующее: добавьте точное совпадение в google cloud. Если воспроизводится «Quota exceeded», проверьте гипотезу «Слишком много запросов или строк» и выполните следующее: добавьте кеш, backoff и пакетную обработку.
Порядок приёмки для «Google Search Console API: подключение и примеры использования»: Хранить refresh token зашифрованно и отдельно от аналитических данных; Версионировать схему выгрузки и набор dimensions; Делать инкрементальную загрузку по датам с повторной сверкой последних дней; Логировать коды и request context без client_secret и токенов. Отдельно укажите, что уже подтверждено live-проверкой, а что появится только после следующего обхода или обновления отчёта. Это не даст повторять отправку ради одного статуса в панели и сохранит воспроизводимую историю изменений.
Надёжная автоматизация
- Хранить refresh token зашифрованно и отдельно от аналитических данных.
- Версионировать схему выгрузки и набор dimensions.
- Делать инкрементальную загрузку по датам с повторной сверкой последних дней.
- Логировать коды и request context без client_secret и токенов.
Частые вопросы
Можно использовать service account?
Да, если добавить его email как пользователя ресурса Search Console. Само создание аккаунта не выдаёт доступ к сайтам.
Можно запросить индексацию через Search Console API?
Публичный API даёт URL Inspection, но не кнопку Request indexing для обычных страниц. Не подменяйте её Google Indexing API вне поддерживаемых сценариев.
Какой scope выбрать?
Для чтения — readonly scope, для управления ресурсами и Sitemap — изменяющий. Всегда выбирайте минимальные права.
Что читать дальше
Источники
Факты, названия разделов и ограничения сверены с документацией. Интерфейсы, тарифы и лимиты сервисов могут меняться.