google-search-console

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Search Console

Architecture

架构

gsc

is a Python CLI wrapping two Google APIs:

Search Console API (webmasters v3 + searchconsole v1) -- search analytics, site management, sitemaps, URL inspection
PageSpeed Insights API (v5) -- Lighthouse lab tests for performance, accessibility, SEO, best practices

All commands output JSON to stdout. Errors go to stderr. Designed for Claude to invoke and parse programmatically.

gsc

是一个封装了两个Google API的Python命令行工具：

Search Console API（webmasters v3 + searchconsole v1）——搜索分析、站点管理、站点地图、URL检查
PageSpeed Insights API（v5）——用于性能、可访问性、SEO、最佳实践的Lighthouse实验室测试

所有命令将JSON输出到stdout，错误信息输出到stderr。设计用于Claude以编程方式调用和解析。

Before First Use

首次使用前

uv: Run

which uv

. If missing:

curl -LsSf https://astral.sh/uv/install.sh | sh

Project sync:
```
uv sync --project <skill-dir>
```
Auth: See below.
PageSpeed API key: See below.

uv：运行

which uv

。如果未安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

项目同步：
```
uv sync --project <skill-dir>
```
身份验证：见下文。
PageSpeed API密钥：见下文。

Search Console Auth (OAuth)

Search Console 身份验证（OAuth）

Save your OAuth client_secret.json (downloaded from GCP) to a known path, then authenticate:

bash

gsc auth login --client-secret /path/to/client_secret.json

A browser opens for OAuth consent. On a headless machine, open an SSH tunnel first:

ssh -L 8085:localhost:8085 <this-host>

, then open the printed URL on a machine with a browser. Credentials are stored at

~/.config/skills/gsc/credentials.json

and auto-refresh.

If you need to create a new OAuth client, see

references/setup.md

for the full GCP click-path.

将从GCP下载的OAuth client_secret.json保存到已知路径，然后进行身份验证：

bash

gsc auth login --client-secret /path/to/client_secret.json

浏览器会打开进行OAuth授权。在无图形界面的机器上，先建立SSH隧道：

ssh -L 8085:localhost:8085 <this-host>

，然后在有浏览器的机器上打开打印出的URL。凭据将存储在

~/.config/skills/gsc/credentials.json

并自动刷新。

如果需要创建新的OAuth客户端，请查看

references/setup.md

获取完整的GCP操作步骤。

PageSpeed Insights API Key

PageSpeed Insights API密钥

Set the key once and gsc remembers it:

bash

gsc config set pagespeed-api-key <your-key>

If you don't have a key, create one in your GCP project's Credentials page, restrict it to the "PageSpeed Insights API", and pass it to

gsc config set

above.

设置一次密钥后，gsc会记住它：

bash

gsc config set pagespeed-api-key <your-key>

如果没有密钥，请在GCP项目的凭据页面创建一个，将其限制为仅用于"PageSpeed Insights API"，然后通过上述

gsc config set

命令设置。

Invocation

调用方式

bash

uv run --project /path/to/skills/google-search-console gsc <command> [args]

For brevity, examples below use

gsc

directly.

bash

uv run --project /path/to/skills/google-search-console gsc <command> [args]

为简洁起见，以下示例直接使用

gsc

。

Commands

命令

auth -- Manage authentication

auth -- 管理身份验证

bash

undefined

bash

undefined

Authenticate with OAuth

通过OAuth进行身份验证

gsc auth login --client-secret ./client_secret.json --port 8085

Check auth status

检查身份验证状态

gsc auth status

Remove stored credentials

删除存储的凭据

gsc auth logout

undefined

gsc auth logout

undefined

config -- Manage settings

config -- 管理设置

bash

undefined

bash

undefined

Set PageSpeed API key

设置PageSpeed API密钥

gsc config set pagespeed-api-key AIza...

Get a config value

获取配置值

gsc config get pagespeed-api-key

Show all config (secrets masked)

显示所有配置（敏感信息已掩码）

gsc config show

undefined

gsc config show

undefined

query -- Search Analytics

query -- 搜索分析

bash

undefined

bash

undefined

Basic query: clicks, impressions, CTR, position for last 7 days

基础查询：过去7天的点击量、展示量、点击率、排名

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07

Group by query keyword

按查询关键词分组

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d query

Group by page and query

按页面和查询分组

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d page -d query

Daily breakdown

按日期细分

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d date

Filter by query containing "pricing"

过滤包含"pricing"的查询

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d query --query-filter pricing

Exact match filter

精确匹配过滤

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --query-filter "=best coffee shop"

Mobile only

仅移动端

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --device-filter "=MOBILE"

Image search

图片搜索

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --search-type image

Paginate results

结果分页

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --row-limit 5000 --start-row 0


Filter prefix operators: `=` exact match, `!` not-contains, no prefix or `~` for contains.

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --row-limit 5000 --start-row 0


过滤前缀运算符：`=` 精确匹配，`!` 不包含，无前缀或 `~` 表示包含。

inspect -- URL Inspection

inspect -- URL检查

bash

gsc inspect sc-domain:example.com https://example.com/page
gsc inspect https://example.com/ https://example.com/page --language en-US

Returns: indexing verdict, crawl info, canonical URL, mobile usability, rich results status.

bash

gsc inspect sc-domain:example.com https://example.com/page
gsc inspect https://example.com/ https://example.com/page --language en-US

返回内容：索引判定、抓取信息、规范URL、移动端可用性、富结果状态。

sites -- Manage properties

sites -- 管理站点属性

bash

gsc sites list
gsc sites get sc-domain:example.com
gsc sites add https://example.com/

bash

gsc sites list
gsc sites get sc-domain:example.com
gsc sites add https://example.com/

sitemaps -- Manage sitemaps

sitemaps -- 管理站点地图

bash

gsc sitemaps list sc-domain:example.com
gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps submit sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps delete sc-domain:example.com https://example.com/sitemap.xml

bash

gsc sitemaps list sc-domain:example.com
gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps submit sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps delete sc-domain:example.com https://example.com/sitemap.xml

pagespeed -- PageSpeed Insights

bash

undefined

bash

undefined

Mobile performance (default)

移动端性能（默认）

gsc pagespeed https://example.com

Desktop, all categories

桌面端，所有类别

gsc pagespeed https://example.com --strategy desktop
--category performance --category accessibility --category seo --category best-practices

Specific locale

指定区域设置

gsc pagespeed https://example.com --locale fr


Requires API key: `gsc config set pagespeed-api-key <key>`. Lab tests take 30-60s.

gsc pagespeed https://example.com --locale fr


需要API密钥：`gsc config set pagespeed-api-key <key>`。实验室测试需要30-60秒。

Site URL Formats

站点URL格式

Google Search Console supports two property types:

Type	Format	Example	Scope
Domain property	`sc-domain:example.com`	`sc-domain:example.com`	All subdomains, protocols, paths
URL-prefix property	`https://example.com/`	`https://example.com/`	Exact prefix match only

Use domain properties when possible -- they cover all variations.

Google Search Console支持两种属性类型：

类型	格式	示例	覆盖范围
域名属性	`sc-domain:example.com`	`sc-domain:example.com`	所有子域名、协议、路径
URL前缀属性	`https://example.com/`	`https://example.com/`	仅精确前缀匹配

尽可能使用域名属性——它们覆盖所有变体。

Common Workflows

常见工作流

Weekly Performance Check

每周性能检查

bash

undefined

bash

undefined

This week vs last week, grouped by date

本周与上周对比，按日期分组

gsc query sc-domain:example.com -s 2026-03-05 -e 2026-03-11 -d date gsc query sc-domain:example.com -s 2026-02-26 -e 2026-03-04 -d date

Top queries by clicks

按点击量排序的热门查询

gsc query sc-domain:example.com -s 2026-03-05 -e 2026-03-11 -d query --row-limit 25

undefined

gsc query sc-domain:example.com -s 2026-03-05 -e 2026-03-11 -d query --row-limit 25

undefined

Indexing Health Check

索引健康检查

bash

undefined

bash

undefined

Check if key pages are indexed

检查关键页面是否已被索引

gsc inspect sc-domain:example.com https://example.com/important-page gsc inspect sc-domain:example.com https://example.com/new-blog-post

Verify sitemap coverage

验证站点地图覆盖率

gsc sitemaps list sc-domain:example.com gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml

undefined

gsc sitemaps list sc-domain:example.com gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml

undefined

CTR Optimization

点击率优化

bash

undefined

bash

undefined

Find high-impression, low-CTR queries (position 3-10)

找到高展示量、低点击率的查询（排名3-10）

gsc query sc-domain:example.com -s 2026-02-10 -e 2026-03-11 -d query -d page --row-limit 5000

Filter results to find optimization opportunities:

过滤结果以找到优化机会：

Look for rows where impressions > 100 and position between 3-10 but CTR < 3%

寻找展示量>100、排名在3-10之间但点击率<3%的行

undefined

undefined

Device Comparison

设备对比

bash

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d device

bash

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d device

Core Web Vitals Check

Core Web Vitals 检查

bash

gsc pagespeed https://example.com --strategy mobile
gsc pagespeed https://example.com --strategy desktop

bash

gsc pagespeed https://example.com --strategy mobile
gsc pagespeed https://example.com --strategy desktop

Interpreting Output

输出解读

See

references/seo-playbook.md

for detailed interpretation guides including:

CTR benchmarks by SERP position
Core Web Vitals thresholds
URL inspection verdicts
Title/description optimization
Monthly monitoring methodology

查看

references/seo-playbook.md

获取详细的解读指南，包括：

按SERP排名划分的点击率基准
Core Web Vitals阈值
URL检查判定
标题/描述优化
月度监控方法

Configuration Files

配置文件

OAuth credentials:
```
~/.config/skills/gsc/credentials.json
```
Config (API keys):
```
~/.config/skills/gsc/config.json
```
Override the config dir with
```
GSC_CONFIG_DIR=/path/to/dir
```

OAuth凭据：
```
~/.config/skills/gsc/credentials.json
```
配置（API密钥）：
```
~/.config/skills/gsc/config.json
```
可通过
```
GSC_CONFIG_DIR=/path/to/dir
```
覆盖配置目录

Migrating from earlier versions

从旧版本迁移

If upgrading from a build that stored config at

~/.config/gsc/

, run

gsc config migrate --apply

to move the credentials and config to the new location.

gsc auth status

emits a

deprecation_warning

until the migration runs.

如果从将配置存储在

~/.config/gsc/

的版本升级，请运行

gsc config migrate --apply

将凭据和配置移动到新位置。在完成迁移前，

gsc auth status

会发出

deprecation_warning

。

Troubleshooting

故障排除

"Not authenticated" -- Run

gsc auth login --client-secret /path/to/client_secret.json

. Credentials may have expired or be missing on a new machine.

"Permission denied" -- The authenticated account must be a verified owner or user of the Search Console property. Check property access at https://search.google.com/search-console.

"Rate limit exceeded" -- Search Console API has per-minute and per-day quotas. Wait 60 seconds and retry. See

references/setup.md

for quota details.

URL Inspection returns no data -- The URL may not be in Google's index. Check the

verdict

field. Only URLs within verified properties can be inspected.

PageSpeed timeout -- Lighthouse lab tests can take 30-60 seconds. The command uses a 120-second timeout. Retry if it fails.

"Unknown key" on config set -- Only

pagespeed-api-key

is a valid config key.

"未通过身份验证" —— 运行

gsc auth login --client-secret /path/to/client_secret.json

。凭据可能已过期或在新机器上缺失。

"权限被拒绝" —— 已验证的账户必须是Search Console属性的已验证所有者或用户。请在 https://search.google.com/search-console 检查属性访问权限。

"超出速率限制" —— Search Console API有每分钟和每日配额。等待60秒后重试。查看

references/setup.md

获取配额详情。

URL检查无数据返回 —— 该URL可能未在Google索引中。检查

verdict

字段。只有已验证属性内的URL才能被检查。

PageSpeed超时 —— Lighthouse实验室测试可能需要30-60秒。命令使用120秒超时。如果失败请重试。

配置设置时提示"Unknown key" —— 只有

pagespeed-api-key

是有效的配置键。