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
}
資源名稱 值 說明 Notes
startDate string [必要] 要求日期範圍的開始日期，格式為 YYYY-MM-DD (UTC 時間 - 7:00/8:00)。必須小於或等於結束日期。這個範圍包含這個值。
endDate string [必要] 要求日期範圍的結束日期，格式為 YYYY-MM-DD，格式為 UTC 時間 (UTC - 7:00/8:00)。必須大於或等於開始日期。這個範圍包含這個值。
dimensions[] list [選用] 零或多個維度將結果分組。結果會按照這些維度的提供順序來排序。您可以在 dimensionFilterGroups[].filters[].dimension 和「日期」中使用任何維度名稱。系統會合併分組維度值，為每個結果列建立專屬鍵。如果未指定維度，系統會將所有值合併成一列。可分組的維度數量沒有限制，但不能按相同維度分組兩次。範例：[country, device]
searchType string 已淘汰，請改用 type
type string [選用] 篩選搜尋結果類型：
  • 「discover」：探索搜尋結果
  • "googleNews"：來自 news.google.com 以及 Android 和 iOS 版 Google 新聞應用程式的搜尋結果。不會納入 Google 搜尋中「新聞」分頁的結果。
  • 「news」：Google 搜尋中「新聞」分頁所提供的搜尋結果。
  • 「image」：來自 Google 搜尋中「圖片」分頁的搜尋結果。
  • 「video」：影片搜尋結果
  • "web"：[預設] 篩選搜尋結果在 Google 搜尋中的合併 (「全部」) 分頁。但不含 Google 探索或 Google 新聞搜尋結果。
dimensionFilterGroups[] list [選擇性] 要套用至維度分組值的零或多個篩選器群組。所有篩選器群組都必須相符，才能在回應中傳回資料列。在單一篩選器群組中，您可以指定所有篩選器都必須相符，還是至少符合一項篩選條件。
dimensionFilterGroups[].groupType string 此群組中的所有篩選器都必須傳回 True (「和」) 或一或多個篩選器傳回 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 進行匯總。如要依網頁篩選或分組，請選擇自動選項；視資料的處理方式而定，您可以依資源或網頁進行匯總；請參閱說明文件，瞭解不同網站和網頁的資料計算方式。

注意：如果您依網頁分組或篩選資料，就無法依據資源進行匯總。

如果您指定以外的值，結果中的匯總類型會與要求的類型相符；如果您要求無效類型，則會收到錯誤訊息。如果要求的類型無效，API 絕不會變更您的匯總類型。

可接受的值為：
  • "auto": [Default] 讓服務決定適當的匯總類型。
  • "byPage"：依照 URI 匯總值。
  • "byProperty"：依屬性匯總值。不適用於 type=discover 或 type=googleNews
rowLimit integer [選用；有效範圍是 1–25,000；預設值是 1,000] 要傳回的資料列數量上限。如要切換結果頁面，請使用 startRow 偏移值。
startRow integer [選用；預設值為 0] 回應中第一列的索引為零。必須為非負數。如果 startRow 超出查詢的結果數量，則回應將會是沒有回應的成功回應。
dataState string [選用] 如果選擇 [全部] (不區分大小寫)，資料就會包含最新資料。 如果 "final" (不區分大小寫) 或省略此參數，則傳回的資料只會包含最終的資料。

回應

結果會根據要求中指定的維度進行分組。維度值相同的所有值都會歸入同一列。例如，如果您依國家/地區維度分組，則「usa」的所有結果都會歸為「Gother」，而「mdv」的所有結果也會歸到一組，依此類推。如果您依國家/地區和裝置將結果分組，則「usa、Tablet」的所有結果都會歸入同一組，「usa, mobile」的所有結果也會歸到其他類別，以此類推。請參閱搜尋分析報表說明文件，進一步瞭解點擊、曝光等項目的計算方式，以及這些指標的意義。

除非以日期分組，否則系統會依照日期的先後順序，以遞增方式排序結果 (在此情況下，由新到舊，由新到舊)。如果兩列之間有相匹配的排序，則任意排列順序。

請查看要求中的 rowLimit 屬性，瞭解可傳回的值數量上限。

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
資源名稱 值 說明 Notes
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 針對即時資料呼叫這個方法，並查看回應。