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 в порівнянні.