需要授權
使用您定義的篩選器和參數,查詢搜尋流量資料。這個方法會傳回零或多個依您定義的列鍵 (維度) 分組的資料列。您必須定義一或多天的日期範圍。
如果日期是其中一個維度,結果清單會省略沒有資料的日期。如要瞭解哪些日期有資料,請針對感興趣的日期範圍發出查詢,但不要使用依日期分組的篩選器。
結果會依點擊次數遞減排序。如果兩列的點擊次數相同,系統會任意排序。
如要呼叫這個方法,請參閱 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 中使用任何維度名稱,以及「日期」和「時數」。系統會合併分組維度值,為每個結果列建立專屬鍵。如果未指定任何維度,所有值都會合併為單一資料列。您可以依任意數量的維度分組,但無法依同一維度分組兩次。範例:[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 的所有資料。如要依網頁篩選或分組,請選擇「自動」;否則,您可以依資源或網頁匯總資料,視您要如何計算資料而定;請參閱說明文件,瞭解網站和網頁的資料計算方式有何不同。 注意: 如果依網頁分組或篩選,就無法依資源匯總。 如果您指定 auto 以外的值,結果中的匯總類型會與要求的類型相符;如果要求無效類型,則會收到錯誤訊息。如果要求的類型無效,API 絕不會變更匯總類型。 可接受的值如下:
|
|
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 |
結果的匯總方式。請參閱說明文件,瞭解系統如何依網站與依網頁計算資料。 可接受的值如下:
|
|
metadata |
object |
這個物件可能會與查詢結果一併傳回,提供資料狀態的相關背景資訊。 當您要求最近的資料 (使用 這個物件中提供的所有日期和時間都採用 這個物件中傳回的特定欄位,取決於您在要求中分組資料的方式:
|
試試看!
您可以使用下方的 API Explorer,針對即時資料呼叫這個方法,然後查看回應。