gsc — Google Search Console, PageSpeed Insights и CrUX
Данные Search Console (ресурсы, поисковая
аналитика, инспекция URL, карты сайта), PageSpeed Insights
(Lighthouse, CrUX, все аудиты) и Chrome UX Report API
(реальные посетители Chrome, история по неделям). Работает как CLI (gsc analytics …) и как Python-библиотека
(import gsc). Пакет, импорт и команда — gsc. Поддерживаются macOS и Linux.
Установка
Из реестра Gitea (пакет выпускается туда):
</code></pre>
<p>Или из git-тега, на любой другой машине:</p>
<pre><code class="language-bash">uv tool install "rb-google-search-console @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/google-search-console.git@vX.Y.Z"
vX.Y.Z — последний тег релиза (ставить из тега, не из ветки). Обновление — uv tool upgrade rb-google-search-console.
Дистрибутив называется rb-google-search-console (gsc на PyPI — чужой пакет), команда и импорт — gsc.
Стоит старая установка под именем gsc — сначала uv tool uninstall gsc, иначе два
инструмента делят одну команду.
Как зависимость другого проекта (библиотека): "rb-google-search-console>=0.5,<0.6" в dependencies и
rb-google-search-console = { index = "gitea" } в [tool.uv.sources] (с индексом gitea из [[tool.uv.index]]).
Доступы
Секреты живут только в связке ключей ОС (Keychain) и переменных окружения; .env не читается.
Search Console — сервисный аккаунт Google.
- Google Cloud Console → создать сервисный аккаунт → Keys → Add key → JSON; включить Google Search Console API.
gsc auth login --file ~/Downloads/key.json— JSON ключа кладётся в Keychain, в общий слот всех Google-инструментов (google-oauth:service_account, пакет google-oauth); файл после этого можно удалить.- Email аккаунта (выводится командой) добавить в Search Console → Настройки → Пользователи
и разрешения каждого нужного ресурса. Для
submit-sitemap— с полными правами.
Порядок поиска ключа: GSC_GOOGLE_SERVICE_ACCOUNT_JSON → GOOGLE_SERVICE_ACCOUNT_JSON →
GOOGLE_OAUTH_SERVICE_ACCOUNT_JSON → GOOGLE_SERVICE_ACCOUNT_FILE / GOOGLE_OAUTH_SERVICE_ACCOUNT_FILE
(путь к файлу) → Keychain. Вход общий: ключ, положенный другим Google-инструментом, gsc тоже видит,
а gsc auth logout удаляет его для всех.
PageSpeed Insights — API-ключ (без ключа квота Google нулевая).
- Cloud Console → APIs & Services → Library → включить PageSpeed Insights API.
- Credentials → Create credentials → API key; желательно ограничить ключ этим API.
gsc auth login --provider pagespeed(спросит скрытым вводом; Keychaingoogle-oauth:api_key) или envGSC_PAGESPEED_API_KEY(а такжеGOOGLE_PAGESPEED_API_KEY,GOOGLE_OAUTH_PAGESPEED_API_KEY).- Для
gsc cruxтот же ключ: включить Chrome UX Report API и добавить его в ограничения ключа (в списке ограничений видны только уже включённые API). Изменения доходят за 1–5 минут.
gsc auth status # что найдено; --check — ещё и спросить у Google, принят ли ключ
gsc doctor # общая диагностика
CLI
gsc # версия + список команд
gsc analytics --help # опции и формат --json
gsc --ai # памятка для AI-агентов
gsc sites # ресурсы аккаунта
gsc sites --for https://blog.example.com/post # какой ресурс покрывает URL
gsc analytics -s sc-domain:example.com -d page,query --limit 100
gsc analytics -s sc-domain:example.com -d page,query --by-day --limit 0 --json > full.json # без предела 50 000
gsc analytics -s sc-domain:example.com -d query -f page:contains:/blog/ --aggregation byPage
gsc inspect -s sc-domain:example.com https://example.com/a https://example.com/b
gsc sitemaps -s sc-domain:example.com
gsc submit-sitemap -s sc-domain:example.com https://example.com/sitemap.xml --dry-run
gsc pagespeed https://example.com --strategy desktop --audits # все 4 категории
gsc crux --origin https://example.com --form-factor phone # реальные посетители, 28 дней
gsc crux --origin https://example.com --history --periods 40 # тренд по неделям
--json у каждой команды; коды выхода: 0 успех, 2 неверные аргументы / нет доступа к
ресурсу, 3 нужны доступы, 5 сбой API Google (в т. ч. квота), 6 CLI устарел.
В папке проекта ресурс можно закрепить: gsc init --site sc-domain:example.com — тогда
-s не нужен (.gsc/config.toml, секретов там нет).
Библиотека
Публичный API — всё из gsc.__all__; меняется только по SemVer. Импорт не лезет в сеть,
keychain и CLI; ключ читается при первом запросе. Всё синхронное.
import gsc
sc = gsc.SearchConsole()
site = sc.property_for("https://example.com/") # доменный ресурс важнее URL-prefix
start, end = gsc.default_range() # 28 дней с задержкой данных 3 дня
rows = sc.iter_search_analytics(
site,
start,
end,
dimensions=["page", "query"],
filters=[{"dimension": "page", "operator": "contains", "expression": "/blog/"}],
aggregation_type="byPage", # byPage / byProperty считают клики и показы по-разному
by_day=True, # по запросу на день: обходит предел ~50 000 строк на запрос
)
for row in rows: # постранично по 25 000
row.keys["page"], row.keys["date"], row.clicks, row.impressions, row.ctr, row.position
rows.first_incomplete_date # при data_state="all": с какой даты данные неполные
for item in sc.inspect_many(urls, site, limit=500): # темп 600/мин, стоп на дневной квоте
if isinstance(item, gsc.InspectionError):
...
else:
item.coverage_state, item.google_canonical, item.rich_results
ps = gsc.PageSpeed()
r = ps.analyze("https://example.com/", "mobile") # все 4 категории за одну единицу квоты
r.scores, r.lab.lcp_ms, r.crux_origin.lcp.good, r.crux_origin_fallback
a = r.audit("render-blocking-insight")
a.description, a.categories, a.details, a.metric_savings # категория, вес, группа; советы
r.stack_packs, r.entities, r.run_warnings, r.runtime_error # платформа, сторонние сервисы, сбои замера
for res in ps.analyze_many(urls, "mobile", concurrency=4):
...
crux = gsc.CrUX() # тот же ключ; нет данных у Google → None
crux.record(origin="https://example.com", form_factor="PHONE").metrics["largest_contentful_paint"]
crux.history("https://example.com/", periods=40).metrics["largest_contentful_paint"].p75 # по неделям
gsc.auth_status() # AuthStatus(google="ok"|"missing"|"expired", pagespeed_key=bool, account=…)
| Ошибка | Когда | Что делать |
|---|---|---|
gsc.NotAuthorized |
нет ключа / Google его отверг | .action — команда gsc auth login … |
gsc.PropertyNotFound |
ресурса нет или нет доступа | добавить email аккаунта в Search Console |
gsc.QuotaExceeded |
квота API; .daily, .retry_after (с) |
ждать retry_after |
gsc.ApiError |
сеть, 5xx, прочие 4xx после повторов; .status |
повторить позже |
Все они — подклассы gsc.CliError (.code, .message, .action). Ошибки по отдельным URL в
inspect_many / analyze_many не прерывают обход — приходят как InspectionError /
PageSpeedError.
Тесты без сети: gsc.testing.FakeSearchConsole / FakePageSpeed / FakeCrUX — те же методы, данные
задаются моделями (gsc.Row, gsc.Inspection, gsc.PageSpeedResult), исключение в словаре —
ошибка по этому URL. Разобрать записанный ответ API: gsc.parse_inspection, gsc.parse_pagespeed,
gsc.parse_crux_record, gsc.parse_crux_history.
Чего нет ни в одном API (только интерфейс Search Console): сводный отчёт об индексировании, отчёт Core Web Vitals, ссылки, ручные меры, безопасность, статистика сканирования. Полные данные поиска без предела строк — только выгрузка в BigQuery (настраивается в интерфейсе GSC).
Квота URL Inspection учитывается локально (файл в папке состояния пользователя, общий для
процессов на машине): sc.quota_remaining(site). Запросы с других машин он не видит — это оценка;
точный стоп даёт ответ Google 429.
Разработка
uv sync
uv run gsc --help
uv run pytest --snapshot-update # после изменения справки команды — снапшоты tests/snapshots/help/
Гейт — шаг gate check в .gitea/workflows/ci.yml: его команду запускают перед каждым коммитом.
Версия — git-тег (vX.Y.Z); работа и релизы идут через Antagor. Архитектура — шаблон
cli-generator; правила для
агентов-разработчиков — AGENTS.md.
Выбор решений
- HTTP к Google —
httpxчерез общийHttpProvider, токен сервисного аккаунта —google-auth.google-api-python-clientубран: тяжёлый (discovery, httplib2), свои повторы и исключения, хуже тестируется; нужные эндпоинты (webmasters/v3, urlInspection v1, PSI v5) — пять REST-вызовов. - Сервисный аккаунт, а не OAuth пользователя — работает неинтерактивно везде (CI, spider); цена — добавлять email аккаунта в каждый ресурс.
- MCP-сервер удалён — агенты вызывают CLI с
--jsonпо памяткеgsc --ai.
Metadata
Release files for rb-google-search-console 0.5.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rb_google_search_console-0.5.5.tar.gz | 172.9 kB | Without provenance | Details for rb_google_search_console-0.5.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rb_google_search_console-0.5.5-py3-none-any.whl | Python 3 | none | any | Details for rb_google_search_console-0.5.5-py3-none-any.whl |
Total release size: 262.6 kB
Release files / rb_google_search_console-0.5.5.tar.gz
| Download URL | rb_google_search_console-0.5.5.tar.gz |
|---|---|
| Size | 172.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ba492093a2ec6c428a3186bee34f02306a70a866f4ed0b475dd1b7f3dfc428f5
|
|
BLAKE2b-256 checksum How to use checksums |
19b4fe14b0c51307645345295ed464abdfb3d381a3c3ea738be1abf21b6e0cb2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / rb_google_search_console-0.5.5-py3-none-any.whl
| Download URL | rb_google_search_console-0.5.5-py3-none-any.whl |
|---|---|
| Size | 89.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aed5cef2bc8b096dfa7cdcd67bc42165ec8f6118d6f7575164624a5ceec70230
|
|
BLAKE2b-256 checksum How to use checksums |
53c656a598e216278bf1ddc37a9d755e504f1b6dde58c4e6dbd25d55008a874a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for rb-google-search-console 0.5.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.