Источники данных и квоты
Каждое число, которое печатает инструмент, приходит из API провайдера или из собственного обхода. У каждого источника есть жёсткие лимиты, и инструмент сообщает о них, а не делает вид, что данные полные. Путь по умолчанию использует только бесплатные тарифы; платный провайдер не требуется.
См. также: Отчёты и диффы, Обход и аудит, Автоматизация и доставка, MCP и навыки агентов.
Матрица возможностей
| Источник | Чтение | Запись (с подтверждением) | Аутентификация | Бесплатная квота | Задержка данных |
|---|---|---|---|---|---|
| Google Search Console | Аналитика поиска, сайты, карты сайта, URL Inspection | Отправка карты сайта; в 0.5.2 возвращает WRITE_DISABLED | Bearer-токен доступа (webmasters.readonly для чтения, webmasters для карт сайта) | 1 200 запросов/мин на сайт и на пользователя; 50 000 строк/день/сайт/тип; URL Inspection 2 000/день, 600/мин | 2–3 дня |
| Yandex Webmaster | Сводка, история SQI, индексирование, URL в поиске и события, запросы, диагностика, битые ссылки, карты сайта | Очередь переобхода; в 0.5.2 возвращает WRITE_DISABLED | OAuth-токен, scope webmaster:hostinfo | Бесплатно; глобальные RPD/RPS не опубликованы; аналитика запросов нестабильна примерно выше 10 тыс. запросов/час | Около 4 дней |
| Yandex Metrika | Визиты, источники трафика, поисковые фразы, страницы входа, цели | Нет | OAuth-токен, scope metrika:read | 5 000 запросов/день/пользователь; 30 rps/IP; 3 параллельно; /stat/v1/data 200 запросов за 5 минут; до 100 тыс. строк, 20 метрик и 10 измерений на запрос | Reporting API; сэмплирование сообщается |
| Bing Webmaster | Статистика запросов, позиции и трафик, ошибки обхода | Отправка IndexNow (работает); путь отправки карты сайта не подключён | Один API-ключ на пользователя | Бесплатно; около 10 тыс. отправок URL/день/домен, 500 за пакет | В API нет статистики по окнам |
| Chrome UX Report (CrUX) | Полевые p75 LCP, INP и CLS | Нет | API-ключ | 150 запросов/мин на проект, увеличить нельзя | Скользящее окно 28 дней |
| PageSpeed Insights (PSI) | Лабораторная диагностика Lighthouse, устаревший блок полевых данных | Нет | API-ключ необязателен; без ключа работает с меньшей квотой | Около 25 тыс. запросов/день | Живой лабораторный запуск |
| GA4 (опционально) | Органические страницы входа, сессии, ключевые события | Нет | Учётные данные Google Analytics Data API | Действует квота провайдера | Ориентировочно; порогование может скрывать строки |
| Собственный обход | Страницы, проблемы, граф ссылок, покрытие карты сайта | Нет | Нет | Локально | Текущий запуск |
| Логи | Триаж ботов по User-Agent для JSON access-логов nginx; не доказательство проверенного краулера | Нет | Локальный файл | Локально | Окно лога |
GA4 — необязательная точка интеграции, а не часть пути по умолчанию. Поставляемые провайдеры: GSC, Yandex Webmaster, Yandex Metrika, Bing, CrUX и PSI. Платные адаптеры для SERP и ссылок (DataForSEO, SerpApi и другие) запланированы или только описаны; в 0.5.2 ни один не поставляется.
Аутентификация
lv24-seo auth status --json
lv24-seo auth set --provider gsc --stdin
lv24-seo auth login --provider gsc
lv24-seo auth logout --provider gscauth set принимает gsc, yandex, metrika, bing, crux, psi, smtp и telegram. Секрет читается из stdin или скрытого запроса, сохраняется в системный keychain, а команда печатает только {provider, stored, source}. Значение никогда не выводится, не попадает в логи и не записывается в seo.toml. Если недоступны ни keychain, ни файловый fallback, команда завершается ошибкой WRITE_DISABLED.
| Провайдер | Переменная окружения |
|---|---|
| GSC | LV24_SEO_GSC_TOKEN |
| Yandex Webmaster | LV24_SEO_YANDEX_WEBMASTER_TOKEN |
| Yandex Metrika | LV24_SEO_YANDEX_METRIKA_TOKEN |
| Bing | LV24_SEO_BING_API_KEY |
| CrUX | LV24_SEO_CRUX_API_KEY |
| PSI | LV24_SEO_PSI_API_KEY |
| SMTP | LV24_SEO_SMTP_PASSWORD |
| Telegram | LV24_SEO_TELEGRAM_BOT_TOKEN |
Порядок разрешения: окружение, затем опциональный keychain, затем файловый fallback с явным включением. Значения из окружения всегда побеждают и доступны только для чтения: auth set и auth logout отказывают, пока соответствующая переменная установлена. Сначала снимите её в оболочке.
Поддержка keychain приходит из опционального extra:
pip install "lv24-seo[secrets]"Без keychain headless-fallback — это data/secrets.json с режимом 0600, включаемый только через LV24_SEO_ALLOW_FILE_SECRETS=1. Пока fallback активен, каждый запуск предупреждает; в Windows режим не обеспечивается файловой системой.
Учётные данные — это вручную поставляемые токены доступа и API-ключи. Инструмент не выполняет OAuth-handshake, не обновляет токены и не обменивает ключ сервисного аккаунта на токен доступа. auth status сообщает только наличие и источник хранения; API-вызов не выполняется, поэтому наличие не доказывает валидность или права.
Квоты, задержка и усечение
Квоты провайдеров ограничиваются консервативными клиентскими token bucket до отправки запроса. Ответ 429 или исчерпанная квота становятся типизированной ошибкой, а не частичным успехом. Основные лимиты, которые нужно учитывать:
- Аналитика GSC ограничена 50 000 строк на день, сайт и тип поиска. Последняя страница, точно заполнившая лимит, помечается
truncated: trueсrows_cap_50000; меньший лимит вызывающего даёт предупреждение с его значением. Полная страница не доказывает, что за лимитом нет строк. - Группировка GSC теряет строки. Никогда не сравнивайте сумму ответа с группировкой по
pageс суммой ответа поqueryи не запрашивайте оба измерения, чтобы сравнить с негруппированным итогом. - Yandex Webmaster отдаёт топ-3 000 запросов за период, до 500 на страницу, и не поддерживает соединение запроса со страницей. Отсутствующие строки неизвестны, а не нулевые.
- Yandex Metrika по умолчанию сэмплирует (
accuracy=medium). Сэмплированный ответ несёт ограничениеsampledи предупреждение; сохраняйте флаг точности вместе со значением. - CrUX возвращает 404, если у URL слишком мало трафика; это становится
low_traffic, а не нулевой оценкой. - PSI — лабораторные данные. Не усредняйте лабораторные запуски и не смешивайте их с полевыми данными CrUX.
- У статистики Bing нет окна дат в API, поэтому отчёт не показывает сравнение с предыдущим периодом для Bing.
Каждый ограниченный ответ несёт одни и те же поля честности: truncated, total, возраст данных в днях (data_age_days) и limitations[]. rows — число возвращённых строк, а не итог. total присутствует, только когда провайдер или хранилище могут его сообщить.
Стабильные коды ограничений:
| Код | Значение |
|---|---|
rows_cap_50000 | GSC достиг лимита 50 000 строк; полная последняя страница потенциально усечена |
no_query_page_join | Провайдер не может соединить запросы со страницами в одном наборе |
top_3000_queries | Данные запросов Yandex ограничены топ-3 000 |
sampled | Metrika вернула сэмплированные данные |
low_traffic | У CrUX слишком мало трафика для URL или origin |
degraded_host | Yandex сообщает, что хост загружен не полностью |
one_url_per_call | URL Inspection обрабатывает один URL за вызов, без пакета |
no_per_url_sitemap_errors | Yandex не раскрывает детали ошибок карты сайта по URL |
token_expiring | Срок действия учётных данных близок к концу |
paid_provider | Строка пришла из платного адаптера |
partial_response | Провайдер вернул неполный ответ |
Никакого скрейпинга SERP
Инструмент никогда не скрейпит страницы результатов Google или Yandex, не обходит CAPTCHA и не автоматизирует карточку Yandex Business или ответы на отзывы через браузерную сессию. Данные позиций и запросов приходят из API GSC и Yandex Webmaster. Если провайдер не раскрывает метрику, она остаётся неизвестной.
Опциональные платные адаптеры работают со своим ключом и выключены по умолчанию. Они обязаны использовать тот же конверт результата и помечать строки paid_provider; путь по умолчанию от них не зависит. Данные провайдеров не перепродаются и не публикуются повторно: отчёты генерируются локально для владельца сайта.
Окна с учётом часового пояса
report.timezone — это IANA-зона (по умолчанию Europe/Minsk), используемая для окон отчёта и stats, окон MCP по умолчанию и локальных границ дня. Данные провайдеров остаются привязанными к датам и не конвертируются. Неверная зона отклоняется при валидации конфигурации с CONFIG_INVALID; неподдерживаемое значение никогда не подменяется молча.
Генераторы расписаний применяют ту же зону там, где бэкенд это поддерживает. Cron зависит от CRON_TZ, systemd записывает зону в OnCalendar, а XML Task Scheduler несёт фиксированное смещение с предупреждением о DST. См. Автоматизация и доставка.
Source: _source/engine-data-sources.md, _source/engine-cli.md, _source/engine-config.md, _source/engine-releases-0.5.2.md.