本頁面由 Cloud Translation API 翻譯而成。

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，以太平洋時間 (PST) 為準 (比世界標準時間晚 7 小時/8 小時)。必須小於或等於結束日期。這個值包含在範圍中。
`endDate`	`string`	[必填] 所要求日期範圍的結束日期，格式為 YYYY-MM-DD，以太平洋時間 (UTC-7:00/8:00) 為準。必須大於或等於開始日期。這個值包含在範圍內。
`dimensions[]`	`list`	[選擇性] 用來分類結果的零或多個維度。結果會按照您提供的維度順序分組。您可以在 `dimensionFilterGroups[].filters[].dimension` 中使用任何維度名稱，以及「日期」。系統會合併分組維度值，以建立每個結果列的專屬鍵。如未指定維度，所有值會合併為單一資料列。您可以依據的維度數量沒有限制，但不能重複使用同一個維度進行分組。範例：[country、device]
`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`	[選用] ：零個或多個篩選器群組，用於套用至維度分組值。所有篩選器群組都必須相符，資料列才會在回應中傳回。在單一篩選器群組中，您可以指定是否必須符合所有篩選條件，或是至少要符合一個篩選條件。
`dimensionFilterGroups[].groupType`	`string`	這個群組中的所有篩選器是否都必須傳回「是」(「and」)，或是至少有一或多個篩選器必須傳回「是」(尚未支援)。可接受的值如下：「`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`」：依指定裝置類型篩選結果。支援的值： DESKTOP MOBILE 平板電腦「`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=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`	[選用] 如果是「all」(不區分大小寫)，資料就會包含最新資料。如果指定「final」(不區分大小寫)，或是省略這項參數，則傳回的資料只會包含已定案的資料。

回應

系統會根據請求中指定的維度分組結果。所有具有相同維度值的值都會分組為單一列。舉例來說，如果您依國家/地區維度分組，所有「美國」的結果就會歸入同一組，所有「MDV」的結果也會歸入同一組，以此類推。如果您依國家/地區和裝置分組，系統會將「美國、平板電腦」的所有結果分組、「美國、行動裝置」的所有結果分組，以此類推。如要進一步瞭解點擊次數、曝光次數等指標的計算方式和意義，請參閱搜尋分析報表說明文件。

結果會依點擊次數由高至低排序，除非您選擇以日期分組，則結果會依日期由新至舊排序。如果兩個資料列的值相同，系統會以任意順序排序。

如要瞭解可傳回的最大值數量，請參閱要求中的 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 (含 0 和 1.0)。
`rows[].position`	`double`	搜尋結果中的平均排序。
`responseAggregationType`	`string`	結果的匯總方式。請參閱說明文件，瞭解依網站和網頁計算資料的差異。可接受的值為：「`auto`」「`byPage`」：結果是依網頁匯總。「`byProperty`」：結果是依資源匯總。

試試看！

您可以使用下方的 API Explorer，針對即時資料呼叫這個方法，然後查看回應。