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 和「date」中使用任何維度名稱。系統會合併分組維度值，以建立每個結果列的專屬鍵。如未指定維度，所有值會合併為單一資料列。可分組的維度數量沒有限制，但不能按同一個維度重複分組。範例：[country、device]
searchType string 已淘汰，請改用 type
type string [選用] 依下列類型篩選結果：
  • 「discover」：探索結果
  • 「googleNews」：來自 news.google.com 及 Google 新聞應用程式的搜尋結果 Android 和 iOS 裝置不包含「新聞」的搜尋結果分頁。
  • 「news」：來自「新聞」的搜尋結果分頁。
  • 「image」：來自「圖片」的搜尋結果分頁。
  • 「video」：影片搜尋結果
  • "web": [預設] 依以下模式篩選合併 (「全部」) 分頁的結果： Google 搜尋。不包括 Google 探索或 Google 新聞的搜尋結果。
dimensionFilterGroups[] list [選用] 要套用至維度分組值的零或多個篩選器群組。所有篩選器群組都必須相符，資料列才會在回應中傳回。在單一篩選器群組中，您可以指定所有篩選器必須符合，或是至少一個篩選條件相符。
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。如果您依網頁進行篩選或分組，請選擇「自動」；或者你也可以 視您想計算資料的方式而定；看 請參閱說明文件 ，瞭解網站和網頁的資料計算方式有何不同。

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

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

可接受的值為：
  • "auto": [預設] 允許服務決定適當的匯總類型。
  • 「byNewsShowcasePanel」：匯總值依據 新聞編輯推薦面板。 這必須和 NEWS_SHOWCASE searchAppearance 搭配使用 篩選及 type=discover 或 type=googleNews。 如果你依網頁分組、依頁面篩選，或篩選出其他searchAppearance， 您無法以 byNewsShowcasePanel 匯總。
  • 「byPage」：按 URI 顯示的匯總值。
  • 「byProperty」：按屬性匯總值。type=discover 或 type=googleNews 不支援
rowLimit integer [選用；有效範圍是 1 到 25,000；預設值為 1,000] 要傳回的列數上限。如要逐頁瀏覽結果，請使用 startRow 偏移。
startRow integer [選用；預設值為 0] 回應中第一列的索引從零開始。必須為非負數。如果 startRow 超過查詢結果數量，回應會是成功的回應 (零列)。
dataState string [選用] 如果「全部」(不區分大小寫)，資料包括 最新資料。 如果是「最終」(不區分大小寫)，或是省略此參數，傳回的資料只會包含最終資料。

回應

結果會按照請求中指定的尺寸進行分組。系統會將包含同一組維度值的所有值歸為單一資料列。舉例來說，如果您依國家/地區維度進行分組，則「usa」的所有結果分組後，「mdv」的所有結果都會歸為一組屬於同一組，依此類推如果您依國家/地區和裝置分組，則搜尋結果會顯示「美國、平板電腦」的所有搜尋結果系統會將所有「usa, mobile」的搜尋結果分組以此類推請參閱 搜尋 Analytics 報表說明文件，進一步瞭解點擊次數、曝光次數等值的計算方法，以及這些數據的意義。

除非您按日期分組，否則結果會按照日期由新到舊 (由新到舊) 按遞增順序排序。如果兩個資料列之間有平分，排序順序就沒有差異。

請參閱要求中的 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，針對即時資料呼叫這個方法，看看會有什麼結果。