Google Search Console API и отчёты: выгрузка данных и автоматизация

1. Архитектура и принцип работы

API работает через OAuth 2.0 или сервисный аккаунт. Вы отправляете POST-запрос к методу searchanalytics.query, указывая сайт (siteUrl), период (startDate, endDate), измерения (dimensions: query, page, country, device) и лимиты (rowLimit до 25 000). Ответ приходит в JSON с массивом rows, где каждая строка содержит ключи (clicks, impressions, ctr, position). Для больших магазинов с тысячами URL применяют пагинацию через startRow. Отчёты по индексации (urlInspection) и картам сайта (sitemaps) запрашиваются отдельными эндпоинтами. Автоматизация строится на cron-задачах: скрипт забирает данные за последние 7 дней, складывает в БД (BigQuery, PostgreSQL) и обновляет дашборд. Важно кэшировать ответы и соблюдать квоты (1200 запросов в минуту на проект).

2. Математическая механика и триггеры ранжирования

Ключевой метод — searchAnalytics.query. Параметры: dimensions (до 3 измерений), type (web, image, video, news), aggregationType (auto, byPage, byProperty), dataState (final или all). Для магазина обычно берут query+page+device. Формула расчёта среднего CTR: CTR = clicks / impressions * 100. Позиция — средняя по всем показам, не медиана. При выгрузке более 25 000 строк используют startRow и rowLimit (макс. 25 000). Для проверки индексации — urlInspection.index.inspect с параметром inspectionUrl. Квоты: 1200 запросов/мин на пользователя, 30 000 000 строк/день на проект. Ошибка 429 — превышение квоты. Для дедупликации запросов применяют фильтр dimensionFilterGroups с операторами equals, contains, includingRegex. Пример фильтра: {"filters":[{"dimension":"page","operator":"contains","expression":"/catalog/"}]}.

3. Специфика в Яндекс (YATI) vs Google

В Яндекс.Вебмастере API тоже есть, но структура отчётов другая: нет прямого аналога searchAnalytics.query с такими же измерениями. Яндекс даёт статистику по запросам через отчёт «Поисковые запросы» с ограничением 500 строк на страницу и другими квотами. Google Search Console API жёстче лимитирует по 25 000 строк, но поддерживает больше измерений (device, country, searchAppearance). В Яндексе данные обновляются с задержкой до 4 дней, в Google — до 3 дней. Для интернет-магазина важно: Google API позволяет выгружать данные по страницам с фильтром по каталогу, а Яндекс — по группам товаров. Оба API требуют OAuth, но Google использует сервисные аккаунты для автоматизации, Яндекс — только токен пользователя.

4. Нормативы SLA и диагностическая матрица

5. Пошаговый инженерный протокол внедрения

• Создайте сервисный аккаунт в Google Cloud Console, включите Search Console API, скачайте JSON-ключ и добавьте email сервисного аккаунта в пользователи GSC с правами «Полный».
• Напишите скрипт на Python (библиотека google-api-python-client), который запрашивает searchanalytics.query с dimensions=['query','page','device'], startDate='2025-01-01', endDate='2025-01-31', rowLimit=25000 и сохраняет результат в PostgreSQL.
• Настройте cron на ежедневный запуск в 6:00, добавьте обработку ошибок 429 (экспоненциальная задержка) и логирование в файл. Для больших магазинов используйте пагинацию через startRow, пока не получите пустой rows.
• Постройте дашборд в Looker Studio или Metabase, подключившись к таблице с данными. Выведите топ-10 страниц по кликам, среднюю позицию по категориям и динамику CTR за неделю.

Пример запроса к Search Console API (Python):

from googleapiclient.discovery import build
service = build('searchconsole', 'v1', credentials=creds)
response = service.searchanalytics().query(
    siteUrl='https://example.com/',
    body={
        'startDate': '2025-01-01',
        'endDate': '2025-01-31',
        'dimensions': ['query', 'page'],
        'rowLimit': 25000,
        'dimensionFilterGroups': [{
            'filters': [{'dimension': 'page', 'operator': 'contains', 'expression': '/catalog/'}]
        }]
    }
).execute()

Формула взвешенной позиции: sum(position * impressions) / sum(impressions).

6. Типичные ошибки при оптимизации

• Игнорирование квот: отправка более 1200 запросов в минуту приводит к блокировке на 24 часа. Решение — кэшировать ответы и использовать batch-запросы.
• Выгрузка без фильтра по страницам: для магазина с 50 000 URL запрос всех данных за месяц превышает лимит строк. Нужно фильтровать по каталогу через dimensionFilterGroups.
• Неправильная интерпретация position: средняя позиция считается по всем показам, включая нулевые клики. Для оценки видимости лучше использовать взвешенную позицию или медиану по топ-запросам.