Search Analytics: query

需要授權

使用您定義的篩選器和參數查詢搜尋流量資料。這個方法會傳回零或多個資料列,並依照您定義的資料列索引鍵 (維度) 分組。您必須定義日期範圍至少一天。

如果日期是其中一個維度,結果清單會忽略沒有資料的任何日期。如要瞭解哪幾天有資料,請發出查詢,不要使用依日期進行分組的篩選器,然後在選定的日期範圍內進行查詢。

結果是按點擊次數遞減排序。如果兩列的點擊次數相同,則會以任意方式排序。

如需呼叫此方法,請參閱 Python 範例

這個 API 受到 Search Console 內部限制的限制,因此不保證會傳回所有資料的資料列,而不是最上方的資料列。

查看可用資料量的限制

JSON POST 範例:
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
立即試用

要求

HTTP 要求

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

參數

參數名稱 說明
路徑參數
siteUrl string Search Console 中定義的資源網址。範例: http://www.example.com/ (適用於網址前置字元資源) 或 sc-domain:example.com (適用於網域資源)

授權

這項要求至少需要取得下列其中一個範圍的授權 (進一步瞭解驗證和授權)。

範圍
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

要求主體

在要求主體中,請依下列結構提供資料:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
資源名稱 說明 附註
startDate string [必要] 所請求日期範圍的開始日期,格式為 YYYY-MM-DD,以太平洋時間 (UTC - 7:00/8:00) 顯示。必須小於或等於結束日期。這個值包含在範圍中。
endDate string [必要] 所請求日期範圍的結束日期,格式為 YYYY-MM-DD,以太平洋時間 (UTC - 7:00/8:00) 顯示。必須大於或等於開始日期。這個值包含在範圍中。
dimensions[] list [選用] 零或多個維度做為結果分組依據。系統會根據您提供的這些維度,將結果分組。您可以在 dimensionFilterGroups[].filters[].dimension 和「日期」中使用任何維度名稱。分組維度值會組合,以建立每個結果資料列的專屬鍵。如果未指定維度,系統會將所有值合併為單一資料列。可分組的維度數量沒有上限,但您無法按同一個維度分組兩次。範例:[國家/地區、裝置]
searchType string 已淘汰,請改用 type
type string [選用] 依以下類型篩選結果:
  • discover」:Google 探索結果
  • googleNews」:來自 news.google.com 的結果,以及 Android 版和 iOS 版 Google 新聞應用程式的結果。不包含 Google 搜尋中「新聞」分頁的搜尋結果。
  • news」:來自 Google 搜尋「新聞」分頁的搜尋結果。
  • image」:來自 Google 搜尋「圖片」分頁的搜尋結果。
  • video」:影片搜尋結果
  • "web": [預設] 篩選 Google 搜尋中合併分頁的結果 (「全部」)。不包含 Google 探索或 Google 新聞的搜尋結果。
dimensionFilterGroups[] list [選用] 可套用至維度分組值的 0 或多個篩選器群組。所有篩選器群組都必須相符,才能在回應中傳回資料列。在單一篩選器群組中,您可以指定所有篩選器必須符合,還是至少一個篩選器相符。
dimensionFilterGroups[].groupType string 指出這個群組中的所有篩選器都必須傳回 true (「and」),還是一或多個值必須傳回 True (尚未支援)。

可接受的值如下:
  • "and": 群組中的所有篩選器都必須針對篩選器群組傳回 True 為 true。
dimensionFilterGroups[].filters[] list [選用] 用於測試資料列的零或多個篩選器。每個篩選器都是由維度名稱、運算子和值組成。長度上限為 4096 個字元。範例:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string 套用此篩選器的維度。您可以按這裡列出的任何維度進行篩選,即使不是按照該維度分組也一樣。

可接受的值如下:
  • country」:根據 3 個字母的國家/地區代碼 (ISO 3166-1 alpha-3) 指定特定國家/地區。
  • device」:根據指定的裝置類型篩選搜尋結果。支援的值:
    • 電腦
    • 行動裝置
    • 平板電腦
  • page」:根據指定的 URI 字串進行篩選。
  • query」:根據指定的查詢字串進行篩選。
  • searchAppearance」:篩選特定搜尋結果功能。如要查看可用值清單,請依「searchAppearance」執行分組查詢。
dimensionFilterGroups[].filters[].operator string [選用] 您指定的值必須與資料列的維度值相符 (或不相符)。

可接受的值如下:
  • contains」:資料列值必須包含或等於運算式 (不區分大小寫)。
  • "equals": [預設] 運算式必須完全符合資料列值 (對網頁和查詢維度區分大小寫)。
  • notContains」:這個資料列值不得包含運算式做為子字串或完整比對 (不區分大小寫)。
  • notEquals」:運算式不得與資料列值完全相同 (頁面和查詢維度須區分大小寫)。
  • includingRegex」:必須比對的 RE2 語法規則運算式。
  • excludingRegex」:不得比對的 RE2 語法規則運算式。
dimensionFilterGroups[].filters[].expression string 篩選器值 (視運算子而定)。
aggregationType string

[選擇性] 資料的匯總方式。如果依資源匯總,系統會匯總相同資源的所有資料;如果依網頁匯總,所有資料都會依標準 URI 匯總。如要依網頁篩選或分組,請選擇「自動」。否則,您可根據資源的計算方式或網頁進行匯總;如要瞭解資料的計算方式,請參閱說明文件

注意:如果您依網頁分組或篩選,就無法依資源進行匯總。

如果您指定 Auto 以外的值,結果中的匯總類型就會與要求類型相符;或者,如果您要求類型無效,就會收到錯誤訊息。如果要求的類型無效,API 就不會變更匯總類型。

可接受的值如下:
  • "auto": [預設] 讓服務決定適當的匯總類型。
  • byNewsShowcasePanel」:依照「新聞編輯推薦」面板顯示匯總值。 這個名稱必須與 NEWS_SHOWCASE searchAppearance 篩選器和 type=discovertype=googleNews 搭配使用。如果您依網頁分組、依網頁篩選或依其他 searchAppearance 進行篩選,就無法依 byNewsShowcasePanel 匯總。
  • byPage」:依 URI 匯總值。
  • byProperty」:依屬性顯示匯總值。不適用於 type=discovertype=googleNews
rowLimit integer [選用;有效範圍為 1–25,000;預設值為 1,000] 要傳回的列數上限。如要逐頁瀏覽結果,請使用 startRow 偏移。
startRow integer [選用;預設值為 0] 回應中第一列的從零開始索引。必須為非負數。如果 startRow 超過查詢的結果數量,回應就會是成功的回應 (沒有任何資料列)。
dataState string [選用] 如果設為「全部」(不區分大小寫),資料就會納入最新資料。 如果「最終」(不區分大小寫) 或省略此參數,傳回的資料只會納入最終資料。

回應

系統會根據要求中指定的維度來分組結果。系統會將包含一組相同維度值的所有值歸入同一列。舉例來說,如果按照國家/地區維度分組,系統會將「usa」的所有結果歸為一組,而「mdv」的所有搜尋結果都會歸為一組,依此類推。假如您按照國家/地區和裝置分組,系統會將「usa, Table」(電腦、平板電腦) 的所有搜尋結果分組,同時納入所有「usa, mobile」(行動、手機) 的搜尋結果,依此類推。請參閱搜尋分析報表說明文件,瞭解點擊次數、曝光次數等數據的具體計算方式,以及代表的意義。

除非你是按日期分組,否則結果會按照日期遞減排序。在這種情況下,搜尋結果會按照日期遞增排序 (由舊到新)。如果兩列之間有平局,則排序順序將是任意順序。

請參閱要求中的 rowLimit 屬性,瞭解可傳回的值數量上限。

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
資源名稱 說明 附註
rows[] list 按照查詢中指定的順序,以鍵值分組的資料列清單。
rows[].keys[] list 該列的維度值清單,根據請求中的維度進行分組,並依照請求中指定的順序排列。
rows[].clicks double 資料列的點擊次數。
rows[].impressions double 資料列的曝光次數。
rows[].ctr double 資料列的點閱率 (CTR)。以 0 到 1.0 (含) 之間的值。
rows[].position double 搜尋結果中的平均排名。
responseAggregationType string 結果的匯總方式。請參閱說明文件,瞭解網站與網頁計算資料的方式有所不同。

可接受的值如下:
  • auto
  • byPage」:結果是依網頁匯總。
  • byProperty」:結果是依資源匯總。

試試看!

使用下方的 APIs Explorer,針對即時資料呼叫這個方法,看看會有什麼結果。