本頁面由 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，以太平洋時間 (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`」：探索結果「`googleNews`」：來自 news.google.com 以及 Android/iOS 版 Google 新聞應用程式的搜尋結果。不包含 Google 搜尋中「新聞」分頁的搜尋結果。「`news`」：Google 搜尋中「新聞」分頁的搜尋結果。「`image`」：Google 搜尋中「圖片」分頁中的搜尋結果。「`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 匯總。如要依網頁進行篩選或分組，請選擇「自動」，或者依據資料計算方法，依資源或網頁匯總資料。如要瞭解網站資料的計算方式，請分別參閱說明文件，瞭解網站與依網頁計算資料的方式有何不同。注意：如果您依網頁進行分組或篩選，就無法依資源匯總。如果您指定 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`	[選用] 如果設為「全部」(不區分大小寫)，資料就會包含最新資料。如果「最終」(不區分大小寫) 或省略此參數，傳回的資料只會包含最終的資料。

回應

系統會根據要求中指定的尺寸將結果分組。維度值相同的所有值都會歸入單一資料列。舉例來說，如果您以國家/地區維度分組，則「usa」的所有結果都會歸為一組，「mdv」的所有結果都會分為一組，以此類推。如果依國家/地區和裝置分組，則「usa, Tablet」的所有結果都會歸為一組，所有與「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，針對有效資料呼叫這個方法，然後查看回應。