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 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 для читання й змін. Для вивантаження ефективності достатньо доступу лише для читання.
- Створіть проєкт у 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 не пояснює причину зростання чи падіння.
Автоматизація також не виправляє нечіткої моделі даних. Якщо поєднати різні типи пошуку, періоди та властивості без явних полів, великий файл виглядатиме переконливо, але втратить зміст. Автоматичний звіт корисний лише тоді, коли запит можна повторити й пояснити.
Що робити після першого вивантаження?
Збережіть картку запиту та необроблену відповідь до побудови похідних показників. Тримайте денні агрегати окремо від деталізованих рядків. Потім перевірте одне завдання: наприклад, які сторінки отримують покази без кліків або які запити змінилися між зіставними періодами. Матеріал про перші покази та кліки допомагає не сприймати короткий сплеск за сталу динаміку.