需要授權
使用您定義的篩選器和參數,查詢搜尋流量資料。這個方法會傳回零或多個資料列,並以您定義的列鍵 (維度) 進行分組。您必須將日期範圍定義為一或多天。
日期為維度之一時,結果清單中會省略所有不含資料的日期。若要瞭解哪幾天的資料有其可用,請針對符合日期範圍的日期範圍發出不含篩選器的查詢。
結果是按點擊次數遞減排序。如果兩列的點擊次數相同,則會以任意方式排序。
請參閱 python 範例,瞭解如何呼叫這個方法。
這個 API 受到 Search Console 的內部限制,因此不保證能傳回所有資料列,而非傳回最上方的資料列。
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 }
資源名稱 | 值 | 說明 | Notes |
---|---|---|---|
startDate |
string |
[必要] 要求日期範圍的開始日期,格式為 YYYY-MM-DD (UTC 時間 - 7:00/8:00)。必須小於或等於結束日期。這個範圍包含這個值。 | |
endDate |
string |
[必要] 要求日期範圍的結束日期,格式為 YYYY-MM-DD,格式為 UTC 時間 (UTC - 7:00/8:00)。必須大於或等於開始日期。這個範圍包含這個值。 | |
dimensions[] |
list |
[選用] 零或多個維度將結果分組。結果會按照這些維度的提供順序來排序。您可以在 dimensionFilterGroups[].filters[].dimension 和「日期」中使用任何維度名稱。系統會合併分組維度值,為每個結果列建立專屬鍵。如果未指定維度,系統會將所有值合併成一列。可分組的維度數量沒有限制,但不能按相同維度分組兩次。範例:[country, device] | |
searchType |
string |
已淘汰,請改用 type
|
|
type |
string |
[選用] 篩選搜尋結果類型:
|
|
dimensionFilterGroups[] |
list |
[選擇性] 要套用至維度分組值的零或多個篩選器群組。所有篩選器群組都必須相符,才能在回應中傳回資料列。在單一篩選器群組中,您可以指定所有篩選器都必須相符,還是至少符合一項篩選條件。 | |
dimensionFilterGroups[].groupType |
string |
此群組中的所有篩選器都必須傳回 True (「和」) 或一或多個篩選器傳回 true (尚不支援)。 可接受的值如下:
|
|
dimensionFilterGroups[].filters[] |
list |
[選用] 零或多個篩選器來測試資料列。每個篩選器都是由維度名稱、運算子和值所組成。長度上限為 4096 個字元。範例:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
要套用這個篩選器的維度。即使未按該維度分組,仍可按這裡列出的任何維度進行篩選。
可接受的值如下:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[選用] 指定值必須與資料列的維度值相符 (或不符合) 的值。
可接受的值如下: |
|
dimensionFilterGroups[].filters[].expression |
string |
依運算子而定,要比對或排除的篩選器值。 | |
aggregationType |
string |
[選用] 匯總資料的方式。如果按屬性匯總,相同資源的所有資料都會經過匯總;如果依網頁進行匯總,所有資料都會以標準 URI 進行匯總。如要依網頁篩選或分組,請選擇自動選項;視資料的處理方式而定,您可以依資源或網頁進行匯總;請參閱說明文件,瞭解不同網站和網頁的資料計算方式。 注意:如果您依網頁分組或篩選資料,就無法依據資源進行匯總。 如果您指定以外的值,結果中的匯總類型會與要求的類型相符;如果您要求無效類型,則會收到錯誤訊息。如果要求的類型無效,API 絕不會變更您的匯總類型。 可接受的值為:
|
|
rowLimit |
integer |
[選用;有效範圍是 1–25,000;預設值是 1,000] 要傳回的資料列數量上限。如要切換結果頁面,請使用 startRow 偏移值。 |
|
startRow |
integer |
[選用;預設值為 0] 回應中第一列的索引為零。必須為非負數。如果 startRow 超出查詢的結果數量,則回應將會是沒有回應的成功回應。 |
|
dataState |
string |
[選用] 如果選擇 [全部] (不區分大小寫),資料就會包含最新資料。 如果 "final" (不區分大小寫) 或省略此參數,則傳回的資料只會包含最終的資料。 |
回應
結果會根據要求中指定的維度進行分組。維度值相同的所有值都會歸入同一列。例如,如果您依國家/地區維度分組,則「usa」的所有結果都會歸為「Gother」,而「mdv」的所有結果也會歸到一組,依此類推。如果您依國家/地區和裝置將結果分組,則「usa、Tablet」的所有結果都會歸入同一組,「usa, mobile」的所有結果也會歸到其他類別,以此類推。請參閱搜尋分析報表說明文件,進一步瞭解點擊、曝光等項目的計算方式,以及這些指標的意義。
除非以日期分組,否則系統會依照日期的先後順序,以遞增方式排序結果 (在此情況下,由新到舊,由新到舊)。如果兩列之間有相匹配的排序,則任意排列順序。
請查看要求中的 rowLimit 屬性,瞭解可傳回的值數量上限。
{ "rows": [ { "keys": [ string ], "clicks": double, "impressions": double, "ctr": double, "position": double } ], "responseAggregationType": string }
資源名稱 | 值 | 說明 | Notes |
---|---|---|---|
rows[] |
list |
依查詢中指定的順序依鍵值分組的列清單。 | |
rows[].keys[] |
list |
該列的維度值清單,並按照要求中的順序 (按要求中指定的順序) 分組。 | |
rows[].clicks |
double |
資料列的點擊次數。 | |
rows[].impressions |
double |
資料列的曝光次數。 | |
rows[].ctr |
double |
此列的點閱率 (CTR)。這個值必須介於 0 到 1.0 (含) 之間。 | |
rows[].position |
double |
搜尋結果中的平均排名。 | |
responseAggregationType |
string |
結果匯總方式。請參閱說明文件,瞭解不同網站和網頁的資料計算方式。
可接受的值如下:
|
試試看!
使用 APIs Explorer 針對即時資料呼叫這個方法,並查看回應。