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 中使用任何維度名稱，以及「日期」和「時數」。系統會合併分組維度值，為每個結果列建立專屬鍵。如果未指定任何維度，所有值都會合併為單一資料列。您可以依任意數量的維度分組，但無法依同一維度分組兩次。範例：[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 這個群組中的所有篩選器是否都必須傳回 true (「and」)，或是一或多個篩選器必須傳回 true (尚不支援)。

可接受的值如下：
  • 「and」：群組中的所有篩選條件都必須傳回 true，篩選條件群組 t才會為 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
    • 行動裝置
    • 平板電腦
  • 「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」(不區分大小寫)，或省略這項參數，傳回的資料就只會包含最終資料。 如果為「hourly_all」(不區分大小寫)，資料會包含每小時的細目。這表示每小時資料包含部分資料，且應在依 HOUR API 維度分組時使用。

回應

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

除非您依日期分組，否則結果會依點擊次數降序排序；如果依日期分組，結果會依日期升序排序 (最舊的排在最前面，最新的排在最後面)。如果兩列之間有繫結，排序順序會是任意。

請參閱要求中的 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 資料列的點閱率。值介於 0 到 1.0 之間 (含 0 和 1.0)。
rows[].position double 在搜尋結果中的平均排名。
responseAggregationType string 結果的匯總方式。請參閱說明文件，瞭解系統如何依網站與依網頁計算資料。

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

這個物件可能會與查詢結果一併傳回，提供資料狀態的相關背景資訊。

當您要求最近的資料 (使用 all 或 hourly_all 查詢 dataState)，傳回的部分資料列可能代表不完整的資料，也就是說，系統仍在收集及處理資料。這個中繼資料物件可協助您判斷確切的開始和結束時間。

這個物件中提供的所有日期和時間都採用 America/Los_Angeles 時區。

這個物件中傳回的特定欄位，取決於您在要求中分組資料的方式：

  • first_incomplete_date (string)：系統仍在收集及處理資料的第一個日期，格式為 YYYY-MM-DD (ISO-8601 擴充本機日期格式)。

    只有在要求的 dataState 為 all，且資料依 date 分組，而要求的日期範圍包含不完整的資料點時，系統才會填入這個欄位。

    first_incomplete_date 後的所有值仍可能大幅變動。

  • first_incomplete_hour (string)：資料仍在收集和處理的第一個小時，格式為 YYYY-MM-DDThh:mm:ss[+|-]hh:mm (ISO-8601 擴充偏移日期時間格式)。

    只有在要求的 dataState 為 hourly_all，且資料依 hour 分組，而要求的日期範圍包含不完整的資料點時，系統才會填入這個欄位。

    first_incomplete_hour 後的所有值仍可能大幅變動。

試試看！

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