需要授權
使用您定義的篩選器和參數查詢搜尋流量資料。這個方法會傳回零或多個資料列,並依照您定義的資料列索引鍵 (維度) 分組。您必須定義日期範圍至少一天。
如果日期是其中一個維度,結果清單會忽略沒有資料的任何日期。如要瞭解哪幾天有資料,請發出查詢,不要使用依日期進行分組的篩選器,然後在選定的日期範圍內進行查詢。
結果是按點擊次數遞減排序。如果兩列的點擊次數相同,則會以任意方式排序。
如需呼叫此方法,請參閱 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 }
資源名稱 | 值 | 說明 | 附註 |
---|---|---|---|
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 |
[選用] 依以下類型篩選結果:
|
|
dimensionFilterGroups[] |
list |
[選用] 可套用至維度分組值的 0 或多個篩選器群組。所有篩選器群組都必須相符,才能在回應中傳回資料列。在單一篩選器群組中,您可以指定所有篩選器必須符合,還是至少一個篩選器相符。 | |
dimensionFilterGroups[].groupType |
string |
指出這個群組中的所有篩選器都必須傳回 true (「and」),還是一或多個值必須傳回 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 匯總。如要依網頁篩選或分組,請選擇「自動」。否則,您可根據資源的計算方式或網頁進行匯總;如要瞭解資料的計算方式,請參閱說明文件。 注意:如果您依網頁分組或篩選,就無法依資源進行匯總。 如果您指定 Auto 以外的值,結果中的匯總類型就會與要求類型相符;或者,如果您要求類型無效,就會收到錯誤訊息。如果要求的類型無效,API 就不會變更匯總類型。 可接受的值如下:
|
|
rowLimit |
integer |
[選用;有效範圍為 1–25,000;預設值為 1,000] 要傳回的列數上限。如要逐頁瀏覽結果,請使用 startRow 偏移。 |
|
startRow |
integer |
[選用;預設值為 0] 回應中第一列的從零開始索引。必須為非負數。如果 startRow 超過查詢的結果數量,回應就會是成功的回應 (沒有任何資料列)。 |
|
dataState |
string |
[選用] 如果設為「全部」(不區分大小寫),資料就會納入最新資料。 如果「最終」(不區分大小寫) 或省略此參數,傳回的資料只會納入最終資料。 |
回應
系統會根據要求中指定的維度來分組結果。系統會將包含一組相同維度值的所有值歸入同一列。舉例來說,如果按照國家/地區維度分組,系統會將「usa」的所有結果歸為一組,而「mdv」的所有搜尋結果都會歸為一組,依此類推。假如您按照國家/地區和裝置分組,系統會將「usa, Table」(電腦、平板電腦) 的所有搜尋結果分組,同時納入所有「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 |
結果的匯總方式。請參閱說明文件,瞭解網站與網頁計算資料的方式有所不同。
可接受的值如下:
|
試試看!
使用下方的 APIs Explorer,針對即時資料呼叫這個方法,看看會有什麼結果。