Back to Details

google-search-console

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Query Google Search Console via 
curl + jq
. The user's OAuth bearer token is in 
$GOOGLE_SEARCH_CONSOLE_TOKEN
(scope 
webmasters.readonly
); every call needs 
Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN
. Base: 
https://searchconsole.googleapis.com
.
Failures are 
{"error":{"code","message","status"}}
— show verbatim. 
401
= re-install. 
403
= the token's account doesn't own/verify that site.
bash
AUTH="Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN"
通过
curl + jq
查询Google Search Console。用户的OAuth bearer token存储在
$GOOGLE_SEARCH_CONSOLE_TOKEN
中（权限范围
webmasters.readonly
）；每次调用都需要
Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN
。基础地址：
https://searchconsole.googleapis.com
。
失败返回格式为
{"error":{"code","message","status"}}
——请原样展示。
401
表示需要重新安装授权。
403
表示该token对应的账号未拥有/验证该站点。
bash
AUTH="Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN"

Verified sites (siteUrl is the property — URL-encode it in later calls)

已验证站点（siteUrl为属性值——后续调用中需对其进行URL编码）

curl -sS -H "$AUTH" "https://searchconsole.googleapis.com/webmasters/v3/sites"
| jq '.siteEntry[] | {siteUrl, permissionLevel}'
undefined
curl -sS -H "$AUTH" "https://searchconsole.googleapis.com/webmasters/v3/sites"
| jq '.siteEntry[] | {siteUrl, permissionLevel}'
undefined

Search analytics

搜索分析

bash
undefined
bash
undefined

Top queries by clicks for the last 28 days. siteUrl must be URL-encoded

过去28天内按点击量排序的热门查询。siteUrl必须经过URL编码

(https%3A%2F%2Fexample.com%2F or sc-domain%3Aexample.com).

（格式如https%3A%2F%2Fexample.com%2F 或 sc-domain%3Aexample.com）。

SITE="https%3A%2F%2Fexample.com%2F" curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json" -d '{ "startDate":"2026-05-24","endDate":"2026-06-21", "dimensions":["query"],"rowLimit":10 }' "https://searchconsole.googleapis.com/webmasters/v3/sites/$SITE/searchAnalytics/query"
| jq '.rows[] | {query: .keys[0], clicks, impressions, ctr, position}'

Swap `dimensions` for `["page"]`, `["country"]`, `["date"]`, or combine
`["query","page"]`. Add `"dimensionFilterGroups"` to filter by page/country.
SITE="https%3A%2F%2Fexample.com%2F" curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json" -d '{ "startDate":"2026-05-24","endDate":"2026-06-21", "dimensions":["query"],"rowLimit":10 }' "https://searchconsole.googleapis.com/webmasters/v3/sites/$SITE/searchAnalytics/query"
| jq '.rows[] | {query: .keys[0], clicks, impressions, ctr, position}'

可将`dimensions`替换为`["page"]`、`["country"]`、`["date"]`，或组合使用`["query","page"]`。添加`"dimensionFilterGroups"`可按页面/国家进行筛选。

Sitemaps & URL inspection

站点地图与URL检查

bash
undefined
bash
undefined

Submitted sitemaps

已提交的站点地图

curl -sS -H "$AUTH" "https://searchconsole.googleapis.com/webmasters/v3/sites/$SITE/sitemaps"
| jq '.sitemap[] | {path, lastDownloaded, errors, warnings}'
curl -sS -H "$AUTH" "https://searchconsole.googleapis.com/webmasters/v3/sites/$SITE/sitemaps"
| jq '.sitemap[] | {path, lastDownloaded, errors, warnings}'

Is a URL indexed?

某URL是否已被索引？

curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json"
-d '{"inspectionUrl":"https://example.com/page","siteUrl":"https://example.com/"}'
"https://searchconsole.googleapis.com/v1/urlInspection/index:inspect"
| jq '.inspectionResult.indexStatusResult | {verdict, coverageState, lastCrawlTime}'
undefined
curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json"
-d '{"inspectionUrl":"https://example.com/page","siteUrl":"https://example.com/"}'
"https://searchconsole.googleapis.com/v1/urlInspection/index:inspect"
| jq '.inspectionResult.indexStatusResult | {verdict, coverageState, lastCrawlTime}'
undefined

Gotchas

常见陷阱

  • Two property shapes: URL-prefix (
    https://example.com/
    ) vs Domain (
    sc-domain:example.com
    ). Use exactly the 
    siteUrl
    from the sites list, URL-encoded.
  • Data lags ~2–3 days; the most recent dates may be partial/empty — set 
    endDate
    a couple days back for stable numbers.
  • ctr
    is 0–1, 
    position
    is average rank (lower = better).
  • 两种属性格式： URL前缀（
    https://example.com/
    ）和域名（
    sc-domain:example.com
    ）。请严格使用站点列表中的
    siteUrl
    ，并进行URL编码。
  • 数据存在约2–3天的延迟；最近的日期数据可能不完整或为空——为了获取稳定数据，请将
    endDate
    设置为几天前。
  • ctr
    的取值范围是0–1，
    position
    是平均排名（数值越小排名越靠前）。