Google Search Console API 是做什麼的?
Search Console API 可程式化存取大部分 Google Search Console 功能:成效報表(Search Analytics)、URL 檢測、Sitemap 及網站清單(Sites)。它是一個 REST/JSON API。每次呼叫都需要 OAuth 2.0 以及一個在該資源上具備 Search Console 權限的使用者(或服務帳戶)。
困難之處不在於發出呼叫,而是在不超出配額的情況下取得完整且正確的資料。本技能主要針對這點。
何時使用此技能
- 提取成效資料(點擊、曝光次數、點擊率、排名)以供分析、儀表板、資料倉儲或 SEO 調查使用。
- 大規模檢查 URL 的索引狀態、標準化選擇、robots/noindex 狀態或結構化資料有效性。
- 列出網站和權限,列出或提交 Sitemap。
- 設計排程同步工作,或修復觸發
quotaExceeded、遺漏資料列、或回傳與 UI 不符數據的工作。
此 API 不涵蓋: 頁面索引(涵蓋率)報表、連結、Core Web Vitals、檢索統計資料、人工行動、移除要求和「要求建立索引」按鈕。如需 Core Web Vitals 的現場資料,請使用 CrUX API;如需大量網站的大量原始成效資料,請使用 Search Console 的 BigQuery 大量資料匯出;獨立的 Indexing API 僅支援 JobPosting / BroadcastEvent 頁面。
四大服務
| 服務 | 方法 | HTTP | 範圍(最低) |
|---|---|---|---|
| Search Analytics | searchanalytics.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| URL Inspection | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| Sitemaps | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| Sitemaps | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| Sites | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| Sites | add / delete | PUT / DELETE /webmasters/v3/sites/{siteUrl} | webmasters |
根網址:https://searchconsole.googleapis.com/(目前探索文件,服務 searchconsole v1)。較舊的 https://www.googleapis.com/webmasters/v3/... 路徑仍會出現在 Google 文件中,且仍適用於 webmasters/v3 資源。
範圍: https://www.googleapis.com/auth/webmasters.readonly(唯讀)和 https://www.googleapis.com/auth/webmasters(讀寫)。除非任務確實需要提交/刪除 Sitemap 或新增/移除網站,否則請請求唯讀範圍。
資源識別碼(siteUrl)—— 403/404 錯誤的頭號來源
- 網域資源:
sc-domain:example.com - URL 前置字串資源:
https://www.example.com/——架構、主機和結尾斜線必須與 Search Console 中的完全一致。 - 在路徑中,
siteUrl和feedpath必須完全 URL 編碼(https%3A%2F%2Fwww.example.com%2F,sc-domain%3Aexample.com)。客戶端函式庫會自動處理;原始 HTTP 則不會。 - 務必先呼叫
sites.list,並使用完全依照回傳結果的siteUrl。siteUnverifiedUser無法讀取資料。
配額——在撰寫任何迴圈前先閱讀
完整詳細資料和預算工作表:references/LIMITS.md。
Search Analytics
- QPM 限制:每個網站 1,200 QPM、每位使用者 1,200 QPM、每個專案 40,000 QPM 和 30,000,000 QPD。例如:一個使用者存取 3 個網站,合計可達 1,200 QPM;兩個使用者共用一個網站,則共享 1,200 QPM。
- 負載配額(實際上最常觸發的):查詢的內部成本,追蹤在 10 分鐘(短期) 和 1 天(長期) 視窗內。成本會隨著以下因素增加:
- 按
page或query分組/篩選(兩者同時使用是最昂貴的), - 日期範圍的長度(6 個月 >> 1 天),
- 重新查詢已擁有的資料。
- 按
- 超出任何一項限制都會回傳相同的
quotaExceeded錯誤。短期:等待 15 分鐘後重試。如果一個 10 分鐘視窗內的單一查詢仍然失敗,則表示你超出了長期(每日)負載配額——請降低成本;重試無效,需等到隔天。
URL Inspection: 每個網站每天 2,000 QPD 和每分鐘 600 QPM;每個專案 10,000,000 QPD 和 15,000 QPM。每個資源每天 2,000 次是真正的上限——請規劃抽樣,不要規劃「檢查每個 URL」。
其他所有項目(網站、Sitemap):每位使用者 20 QPS 和 200 QPM;每個專案 100,000,000 QPD。
批次處理不會節省配額:包含 n 個呼叫的批次視為 n 個請求。批次處理僅節省 HTTP 開銷。目前用量:Google Cloud 控制台 → API 和服務 → Search Console API → 配額。
Search Analytics:取得完整且正確的資料
完整的請求和回應結構描述及範例:references/SEARCH-ANALYTICS.md。
建議模式(來自 Google 的「所有資料」指南)
- 先探查資料新鮮度。 僅按
date分組查詢最近約 10 天——無需篩選,無需其他維度。沒有資料的日子就不會出現。最終資料通常落後 2–3 天。 - 每次查詢一天(
startDate == endDate),每天一次,針對你需要的每種type。一天一次的查詢不應超過你的每日配額;而一個 16 個月的範圍並按 page+query 分組則會超出配額。 - 對結果進行分頁:
rowLimit最大 25,000(預設 1,000),每頁將startRow增加 25,000,直到某個頁面回傳少於請求數量的資料列或 0 行。 - 切勿重新拉取已最終確定的歷史資料。 儲存它;僅擷取新的日期(如果你使用
dataState: "all",則可重新擷取近期尚未最終確定的日期)。
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
{
"startDate": "2026-11-14",
"endDate": "2026-11-14",
"dimensions": ["page", "query", "country", "device"],
"type": "web",
"rowLimit": 25000,
"startRow": 0
}
你必須向利害關係人說明的硬性資料限制
- API 回傳頂層資料列,而非所有資料列:每種搜尋類型每天最多 50,000 行(按點擊排序),與分頁無關。
- 按
page和/或query分組/篩選會捨棄部分資料(以維持運算量限制),且匿名的罕見查詢永遠不會回傳。因此 資料列總和 < 資源總計。如需準確總計,請在沒有page/query維度的情況下進行查詢。 - 總計會因彙總方式而異:
byProperty(每個資源去重)vsbyPage(每個標準化 URL)。如果你按page分組或篩選,則不允許使用byProperty——請改用auto。 - 日期採用太平洋時間(
America/Los_Angeles),而非 UTC。 - Search Console 的成效資料保留期約為 16 個月。如果你需要更長的歷史記錄,請將其保存下來。
正確的指標計算
- 群組的 CTR =
sum(clicks) / sum(impressions)。絕不平均 CTR。 - 群組的 Position = 曝光加權:
sum(position × impressions) / sum(impressions)。絕不平均位置。 position是基於 1 的平均最上方位置;數值越低越好。
主要請求欄位(快速參考)
dimensions:date,hour,query,page,country(ISO 3166-1 alpha-3,結果中為小寫,例如usa),device(DESKTOP/MOBILE/TABLET),searchAppearance,brandedClassification。type:web(預設),image,video,news(新聞分頁),googleNews(news.google.com + 應用程式),discover,webMultimodal(Lens / Circle to Search / 圖片上傳)。searchType是已棄用的別名。dimensionFilterGroups[].filters[]:{dimension, operator, expression};運算子equals(預設,對 page/query 區分大小寫),notEquals,contains,notContains,includingRegex,excludingRegex(RE2)。群組之間是 AND 關係;僅支援groupType: "and"。dimensionFilterGroups[].filterLists[]:針對country/device的多值精確比對({"dimension":"country","expressions":["usa","can"]})。不能同時在filters和filterLists中篩選同一個維度。aggregationType:auto(預設),byPage,byProperty(不適用於discover/googleNews),byNewsShowcasePanel。dataState:final(預設),all(包含新的、尚未最終確定的資料),hourly_all(hour維度必須使用;約 10 天可用)。回應中的metadata.firstIncompleteDate/firstIncompleteHour標示數字可能仍會變動的位置。
注意事項
- 搜尋外觀分兩步驟:先查詢以
searchAppearance作為唯一維度來列出類型,然後篩選searchAppearance equals <TYPE>並加入其他維度——每種類型一次查詢。 brandedClassification(BRANDED/NON_BRANDED):僅equals;不能在同一個請求中與query篩選器結合;資料從 2026-02-21 開始,且僅適用於流量足夠的頂層資源。- 結果按 點擊降冪 排序,但按
date分組時除外(日期升冪)。平手時順序為任意——請勿依賴順序進行去重。 - 超出範圍的
startRow會回傳 200 且包含零行,而非錯誤。資料恰好落在 25,000 邊界時會回傳空的下一頁。 - 當沒有資料時,
rows是缺席的(而非[])。
URL Inspection
完整結構描述、列舉和問題排除表:references/URL-INSPECTION.md。
POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.example.com/page", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }
- 僅報告已建立索引的版本。它無法測試即時 URL,也無法要求建立索引。
inspectionUrl必須在siteUrl之下。- 讀取
indexStatusResult:verdict(PASS = 有效, NEUTRAL = 排除, FAIL = 錯誤),coverageState(人類可讀字串,例如 "Submitted and indexed"),robotsTxtState,indexingState,pageFetchState,lastCrawlTime,googleCanonicalvsuserCanonical,crawledAs。 - 最有用的批量訊號是
googleCanonical != userCanonical(Google 選擇了不同的標準化網址)。 mobileUsabilityResult已棄用。ampResult/richResultsResult在不適用時缺席。- 預算: 每天/每個資源 2,000 次。優先抽樣:按點擊排序的頂層頁面、近期有變更的範本、每個範本/模式一個 URL、來自新 Sitemap 的 URL。
Sites 和 Sitemaps
請參閱 references/SITES-AND-SITEMAPS.md。sites.list → siteEntry[] {siteUrl, permissionLevel},包含 siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser。sitemaps.list → sitemap[],包含 path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, errors, warnings, contents[].submitted(contents[].indexed 已棄用——請勿回報)。submit / delete 不接受請求本文,且需要讀寫範圍。這些是寫入操作。在呼叫前請先向使用者確認。
驗證和設定
逐步說明,以及每種語言的程式庫安裝指令:references/AUTH-AND-SETUP.md。
- 建立/選擇一個 Google Cloud 專案 → 啟用 Google Search Console API。
- 選擇一個憑證:
- 已安裝/桌面 OAuth 用戶端:適用於在本機執行指令碼的使用者;使用者在瀏覽器中同意,然後你儲存重新整理權杖。
- 服務帳戶:適用於無人看管的工作。然後在 Search Console 中將服務帳戶電子郵件新增為資源的使用者(設定 → 使用者和權限)。讀取操作僅需「限制」權限;寫入操作則需要「擁有者」或「完整」權限。如果缺少此步驟,每個呼叫都會回傳 403。
- API 金鑰不被接受用於這些資源;OAuth 2.0 是唯一支援的通訊協定。
- 使用客戶端函式庫(建議)— 例如 Python 的
google-api-python-client搭配build("searchconsole", "v1", credentials=creds),Node 的googleapis搭配google.searchconsole("v1")。
from google.oauth2 import service_account
from googleapiclient.discovery import build
creds = service_account.Credentials.from_service_account_file(
"sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)
resp = gsc.searchanalytics().query(siteUrl="sc-domain:example.com", body={
"startDate": "2026-11-14", "endDate": "2026-11-14",
"dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", []) # 空時缺席
絕對不要列印、記錄或提交權杖、用戶端密鑰或服務帳戶金鑰。
錯誤和重試
完整對應表:references/ERRORS.md。
| 症狀 | 原因 | 動作 |
|---|---|---|
401 authError / expired | 錯誤/過期的權杖 | 重新整理權杖;檢查範圍 |
403 insufficientPermissions / "User does not have sufficient permission for site" | siteUrl 格式錯誤,或主體不是資源的使用者 | 呼叫 sites.list,使用確切的 siteUrl;在 Search Console 中新增服務帳戶 |
403 accessNotConfigured | 專案中未啟用 API | 啟用 Search Console API |
403/429 rateLimitExceeded, userRateLimitExceeded | QPS/QPM | 使用抖動的指數退避 |
403/429 quotaExceeded(Search Analytics) | 負載配額 | 等待 15 分鐘一次;如果單一查詢仍然失敗 → 長期負載:縮小日期範圍或移除 page/query,隔天再繼續 |
400 invalidParameter / badRequest | 錯誤的列舉值、日期順序、對同一維度混合使用 filters/filterLists、使用 byProperty 搭配 page | 修正請求;不要重試 |
500 / 503 backendError | 暫時性 | 退避並重試(有限次數) |
效能
references/BATCH-AND-PERFORMANCE.md:gzip(Accept-Encoding: gzip 以及包含 gzip 的 User-Agent)、透過 fields= 進行部分回應(例如 fields=rows(keys,clicks,impressions))以及 HTTP 批次(multipart/mixed, ≤ 1,000 個呼叫,以任意順序執行,每個呼叫仍會計入配額)。
輔助指令碼
scripts/gsc.py 是一個單一檔案的 CLI,僅使用 Python 3.9+ 標準函式庫。它將進度寫入 stderr,並將資料寫入 stdout(預設為 JSONL,或 CSV/JSON)。它會進行分頁、處理配額…