需要授權
使用您定義的篩選器和參數查詢搜尋流量資料。此方法會傳回零或多個依據您定義的資料列索引鍵 (維度) 分組的資料列。您必須定義一或多天的日期範圍。
以日期做為維度之一時,結果清單會省略任何沒有資料的日期。如要瞭解哪幾天有資料,請針對所需的日期範圍,提交不含依日期分組篩選器的查詢。
結果按點擊次數遞減排序。如果兩個資料列的點擊次數相同,就會以任意方式排序。
請參閱 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 和「date」中使用任何維度名稱。系統會合併分組維度值,以建立每個結果列的專屬鍵。如未指定維度,所有值會合併為單一資料列。可分組的維度數量沒有限制,但不能按同一個維度重複分組。範例:[country、device] | |
searchType |
string |
已淘汰,請改用 type
|
|
type |
string |
[選用] 依下列類型篩選結果:
|
|
dimensionFilterGroups[] |
list |
[選用] 要套用至維度分組值的零或多個篩選器群組。所有篩選器群組都必須相符,資料列才會在回應中傳回。在單一篩選器群組中,您可以指定所有篩選器必須符合,或是至少一個篩選條件相符。 | |
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。如果您依網頁進行篩選或分組,請選擇「自動」;或者你也可以 視您想計算資料的方式而定;看 請參閱說明文件 ,瞭解網站和網頁的資料計算方式有何不同。 注意: 如果您依網頁進行分組或篩選,就無法依資源匯總資料。 如果指定 值,結果中的匯總類型會與要求的類型相符。 如果請求的類型無效,就會收到錯誤訊息。如果要求的類型無效,API 絕對不會變更您的匯總類型。 可接受的值為:
|
|
rowLimit |
integer |
[選用;有效範圍是 1 到 25,000;預設值為 1,000] 要傳回的列數上限。如要逐頁瀏覽結果,請使用 startRow 偏移。 |
|
startRow |
integer |
[選用;預設值為 0] 回應中第一列的索引從零開始。必須為非負數。如果 startRow 超過查詢結果數量,回應會是成功的回應 (零列)。 |
|
dataState |
string |
[選用] 如果「全部」(不區分大小寫),資料包括 最新資料。 如果是「最終」(不區分大小寫),或是省略此參數,傳回的資料只會包含最終資料。 |
回應
結果會按照請求中指定的尺寸進行分組。系統會將包含同一組維度值的所有值歸為單一資料列。舉例來說,如果您依國家/地區維度進行分組,則「usa」的所有結果分組後,「mdv」的所有結果都會歸為一組屬於同一組,依此類推如果您依國家/地區和裝置分組,則搜尋結果會顯示「美國、平板電腦」的所有搜尋結果系統會將所有「usa, mobile」的搜尋結果分組以此類推請參閱 搜尋 Analytics 報表說明文件,進一步瞭解點擊次數、曝光次數等值的計算方法,以及這些數據的意義。
除非您按日期分組,否則結果會按照日期由新到舊 (由新到舊) 按遞增順序排序。如果兩個資料列之間有平分,排序順序就沒有差異。
請參閱要求中的 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,針對即時資料呼叫這個方法,看看會有什麼結果。