如何使用 Google Search Console API？
Google Search Console 與其他工具比較
在 Google Cloud 控制台建立專案，啟用 Google Search Console API，建立 OAuth 2.0 憑證，再使用擁有該資源存取權的 Google 帳戶登入。接著就能對四種資源發送請求：Search Analytics（點擊、曝光、CTR 與排名）、URL Inspection（索引狀態）、Sitemaps 以及 Sites。僅使用 API 金鑰無法呼叫：每次呼叫都需要 OAuth 權杖，且配額會限制你能查詢的資料量。
API 涵蓋的範圍與不涵蓋的範圍
| 資源 | 方法 | 用途 |
|---|---|---|
| Search Analytics | query | 依查詢、網頁、國家/地區、裝置、搜尋外觀、日期或小時取得成效資料列 |
| URL Inspection | index.inspect | 單一 URL 的已索引版本：涵蓋範圍、上次檢索時間、標準網址 |
| Sitemaps | list、get、submit、delete | 管理資源已提交的 Sitemap |
| Sites | list、get、add、delete | 已登入帳戶下的資源 |
API 的功能僅止於此。連結、檢索統計資料、網頁索引報表與 Core Web Vitals 報表都沒有對應的端點，因此只能在 Search Console 介面中查看。URL Inspection 回報的是 Google 索引中的內容，並非對網頁進行即時測試。
設定存取權
- 在 Google Cloud 控制台建立或選擇一個專案。
- 為該專案啟用 Google Search Console API。
- 設定 OAuth 同意畫面，並建立 OAuth 用戶端 ID。
- 申請一個範圍：唯讀請用
https://www.googleapis.com/auth/webmasters.readonly，若還需要提交或刪除 Sitemap，則用https://www.googleapis.com/auth/webmasters。 - 使用對該資源具有權限的帳戶登入。讀取成效資料至少需要唯讀權限；API 看到的內容與該帳戶所見完全相同。
第一個 Search Analytics 查詢
POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"startDate": "2026-09-01",
"endDate": "2026-09-30",
"dimensions": ["query", "page"],
"type": "web",
"rowLimit": 25000,
"startRow": 0
}網站要放在路徑中並經過 URL 編碼：網域資源使用 sc-domain:example.com，網址前置字元資源則使用完整前置字元並保留結尾斜線，例如 https://www.example.com/。最重要的欄位如下：
- 日期為含頭尾的區間，以太平洋時間計算。
type預設為web；其他選項有image、video、news、googleNews和discover。每種類型都需要各自發送請求。- 篩選條件放在
dimensionFilterGroups中，運算子從equals、contains到includingRegex、excludingRegex（RE2 語法）皆可使用。 rowLimit範圍為 1 到 25,000（預設 1,000）；其餘資料以startRow分頁取得。dataState預設為final;all會加入最新但尚未定案的日期，hourly_all則搭配hour維度使用。
每一列會回傳 keys、clicks、impressions、ctr（0 到 1）和 position，除非依日期分組，否則會依點擊數排序。
影響程式設計的限制
- 每種搜尋類型每天 50,000 列。 以 25,000 為單位用
startRow分頁，遇到空白回應即停止。若要取得最多資料，請一次只查詢一天。 - 負載配額。 同時依網頁和查詢分組或篩選的請求成本最高，日期範圍越長成本也越高。超過短期配額時，Google 會要求你等待 15 分鐘。
- 請求頻率。 每個網站和每位使用者每分鐘 1,200 次查詢；每個專案每分鐘 40,000 次、每天 30,000,000 次。
- URL Inspection 配額。 每個資源每天 2,000 次檢查、每分鐘 600 次。
- 16 個月的歷史資料，且資料通常在當天結束後兩到三天才會提供。
- 資料列加總不等於總計。 罕見查詢不會出現在查詢層級的資料列中，而依網頁分組與依資源分組計算曝光的方式也不同，因此請從不含查詢維度的請求中讀取總計。
常見錯誤
- 資源是
https://卻使用http://，或漏掉結尾斜線，即使帳戶有存取權，也會出現權限錯誤。 - 在 URL Inspection 中查詢資源以外的 URL 會被拒絕：該 URL 必須位於你傳入的
siteUrl之下。 - 一次呼叫就以查詢和網頁分組整個月的資料，只會回傳排名最前面的資料列。改用逐日請求可取得更多資料。
AutoPSEO 如何提供協助
如果你不想自行維護 OAuth 與分頁，AutoPSEO 會透過 Google 登入連線，並以自家位於 /v1 的 REST API（附 OpenAPI 3.1 文件）和 MCP 伺服器提供相同的資料，授權方式為使用 Account → API keys 中的 API 金鑰。AutoPSEO 提供唯讀金鑰，搜尋分析端點每次呼叫最多回傳 5,000 列，且應用程式中的 URL Inspection 工具會替你統計 Google 每天 2,000 次的配額用量。請參閱 MCP 與 API 金鑰。若想在不撰寫資料管線的情況下保留超過 16 個月的資料，請參閱 Search Console 會保留資料多久。
資料來源：Google 的 API 參考文件、Search Analytics query 方法、使用限制、取得所有資料以及授權指南。