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
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            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」和「hour」。系統會合併分組維度值,為每個結果列建立專屬鍵。如未指定維度,所有值都會合併為單一資料列。可分組的維度數量沒有限制,但無法依相同維度分組兩次。範例:[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 新聞結果。
  • 「webMultimodal」:Google 智慧鏡頭、Android 畫圈搜尋和 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」分組的查詢。 如需完整的值和說明清單,請參閱說明文件。
  • 「brandedClassification」:根據指定的含品牌名稱查詢分類篩選結果 (僅支援「equals」運算子)。依「brandedClassification」篩選或分組依據時,無法在同一要求中與「query」篩選器合併。系統可提供自 2026 年 2 月 21 日起的資料,且僅限查詢和曝光量充足的頂層資源 (請參閱含品牌名稱的查詢公告)。支援的值:
    • 品牌
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [選用] 指定的值必須與資料列的維度值相符 (或不相符)。

可接受的值如下:
  • 「contains」:資料列值必須包含或等於運算式 (不區分大小寫)。
  • 「equals」:[預設] 運算式必須與資料列值完全相同 (網頁和查詢維度會區分大小寫)。
  • 「notContains」:資料列值不得包含運算式,無論是子字串或完全相符 (不區分大小寫) 的字串。
  • 「notEquals」:運算式不得與資料列值完全相同 (網頁和查詢維度會區分大小寫)。
  • 「includingRegex」:必須符合的 RE2 語法規則運算式。
  • 「excludingRegex」:不得比對的 RE2 語法規則運算式。
dimensionFilterGroups[].filters[].expression string 篩選器要比對或排除的值,取決於運算子。
dimensionFilterGroups[].filterLists[] list [選用] 零或多個多值維度篩選器,用於測試資料列。 filters[] 只能比對每個項目的單一值,filterLists[] 則可比對單一維度的多個完全比對值。如果資料列的指定 dimension 值等於任何提供的 expressions,則該資料列與篩選器清單相符。請注意,單一要求無法同時在 filters 和 filterLists 中篩選相同維度。
dimensionFilterGroups[].filterLists[].dimension string [必要] 套用這份篩選器清單的維度。

可接受的值如下:
  • "country":使用 3 字母國家/地區代碼 (ISO 3166-1 alpha-3),篩選指定國家/地區。
  • 「device」:篩選指定裝置類型 (DESKTOP、MOBILE、TABLET)。
dimensionFilterGroups[].filterLists[].expressions[] list [必要] 要篩選的值清單 (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 維度分組時使用。

回應

結果會依要求中指定的維度分組。具有相同維度值組合的所有值都會分組到同一列。舉例來說,如果依國家/地區維度分組,系統會將「usa」的所有結果歸為一組,「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 該列的點閱率。值必須介於 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之後的所有值仍可能會有明顯變化。

試試看!

使用下方的 APIs Explorer,對即時資料呼叫這個方法,並查看回應。