此頁面列出頻道擁有者可透過 YouTube Analytics API 擷取的報告。頻道報表可提供特定頻道的使用者活動指標,並用於評估影片觀看次數、評分和訂閱人數等項目。
擷取報表
如要擷取管道報表,您必須在 API 請求中將 ids
參數值設為下列其中一個值:
-
channel==MINE
- API 會傳回已驗證使用者 YouTube 頻道的資料。
-
channel==CHANNEL_ID
- 將 CHANNEL_ID
設為您所擷取管道的專屬頻道 ID。授權要求的使用者必須是頻道擁有者。
管道編號目前是以 UC
開頭的字串,不過格式可能隨時變動。(您可以在 YouTube 頻道的進階帳戶設定頁面上找到您的頻道 ID,也可以使用 YouTube Data API's channels.list
的程式輔助方式擷取頻道的 ID)。
授權
所有的 YouTube Analytics API 要求都必須經過授權。授權指南說明如何使用 OAuth 2.0 通訊協定擷取授權權杖。
YouTube Analytics API 要求使用下列授權範圍:
範圍 |
https://www.googleapis.com/auth/yt-analytics.readonly |
查看您 YouTube 內容的 YouTube 數據分析報表。這個範圍可讓您存取使用者活動指標,例如觀看次數和評分次數。 |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
查看您 YouTube 內容的 YouTube 數據分析金額報表。這個範圍可讓您存取使用者活動指標,以及預估收益和廣告成效指標。 |
https://www.googleapis.com/auth/youtube |
管理您的 YouTube 帳戶。在 YouTube Analytics API 中,頻道擁有者可使用這個範圍來管理 YouTube 數據分析的群組和群組項目。 |
https://www.googleapis.com/auth/youtubepartner |
查看及管理 YouTube 資產和 YouTube 上的相關內容。內容擁有者可以在 YouTube Analytics API 中使用這個範圍來管理 YouTube 數據分析的群組和群組項目。 |
注意:頻道報表目前不支援預估收益和廣告成效指標。因此,https://www.googleapis.com/auth/yt-analytics-monetary.readonly
範圍目前無法授權存取這些報表中的金額資料。
篩選器
表格會說明支援的報表表格,可用於建立每份報表適用的篩選器。在表格中,括號中的篩選器為選用項目。舉例來說,在篩選器選項 video(,country)
中,影片篩選器為必要項目,而國家/地區篩選器則為選用項目。
這個 API 也支援為 video
和 playlist
篩選器指定多個值。如果您確實為上述任一篩選器指定了多個值,您也可以將這個篩選器加到您為要求指定的維度清單中。即使該報表並未列在特定報表的支援維度中也一樣。
如需篩選特定值或一組值的完整說明,請參閱 filters
參數定義。
瞭解報表表格
本節說明定義 API 支援的表格所使用的格式和術語。下表列出以時間為基礎的頻道播放清單報表支援的維度、指標和篩選條件:
這份表格包含維度的兩列、一項指標的列,以及三個列的篩選器。以維度和篩選器來說,只要每一列都符合表格中的使用規則,您就可以在 API 要求中合併各列的值。舉例來說,這份報表的有效 dimensions
參數值包括:
dimensions=day
dimensions=7DayTotals,subscribedStatus
dimensions=30DayTotals,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
然而,day,month
參數值無效,因為其使用了兩個以時間為基礎的維度,但要求必須剛好 1。在這種情況下,參數值 subscribedStatus,youtubeProduct
實際上會傳回報表,但指標不會依照日期、週次、月份等條件進行匯總 (在說明文件中會另外記錄一次)。
報表表格術語
表格使用下列詞彙來指出維度為必要或選用:
- 下列字詞代表必須提供值:
- 必要:您必須加入值。
- 僅使用 1:您必須從群組加入一個值。
- 使用 1 個以上的值:您可以加入群組中的任何或所有值,但至少必須加入一個值。
- 下列字詞代表的是選用的值:
- 選用:您可以選擇加入值。
- 使用 0 或 1:您可以選擇從群組中加入一個值。
- 使用 0 以上的值:您可以選擇加入群組中的任何或所有值。
影片報表
基本統計資料
基本使用者活動統計資料
這份報表提供了使用者與頻道動作的相關統計資料,您可以篩選報表,只傳回特定影片或國家/地區的資料。
美國各州的使用者活動統計資料
本報告提供美國各州或哥倫比亞特區的統計資料。請注意,這份報表僅支援上述國家/地區專屬報表中的部分指標。
根據時間
按國家/地區劃分的時段
這份報表提供了與頻道在特定時間範圍內的使用者動作相關的統計資料。您可以篩選報表,只傳回特定影片或國家/地區的資料。
特定時間範圍內的使用者狀態 (美國狀態)
此報告提供特定美國州或哥倫比亞特區使用者活動的相關統計資料。請注意,這份報表僅支援上述國家/地區專屬報表中的部分指標。
使用者地理位置
依國家/地區劃分的使用者活動
此報表可提供頻道各國家/地區使用者活動的相關統計資料。您可以篩選報表,只傳回特定影片的資料。
使用者活動 (依省分組)
本報告提供美國各州及哥倫比亞特區的使用者活動統計資料。在這份報表中,您必須將 filters
參數值設為 country==US
。
按城市劃分的使用者活動 (少於 250 項結果)
注意:如要使用這份報表,您必須將 maxResults
參數設為 250
以下的整數。與其他大多數的報表不同,這份報表也需要為 sort
請求參數指定值。
這份報表提供了各城市的使用者活動統計資料。
播放詳細資訊
播放詳細資料報告提供下列檢視屬性的相關統計資料:
- 是否有現場直播影片或隨選影片的觀看?
- 觀眾訂閱的是擁有影片的頻道嗎?
- 影片出現在哪些 YouTube 產品上?
注意:liveOrOnDemand 維度和篩選器無法與 averageViewPercentage 指標搭配使用。因此,每個子區段都列出兩份報表。一份報表支援 liveOrOnDemand 維度 (和篩選器),另一個報表則支援 averageViewPercentage 指標。
使用者訂閱狀態 (依訂閱狀態)
此報表可針對已訂閱和未訂閱的觀眾提供使用者活動指標。您可以按時間範圍 (日或月) 將統計資料分組,也可以依國家/地區、洲別或子洲別進行篩選。
各省的使用者訂閱狀態
此報表可提供美國州或哥倫比亞特區訂閱者和未訂閱頻道的觀眾活動指標。相較於舊版報表,這份報表支援的指標較少。
提供選用時間維度的播放詳情
這些報表的時間維度 (天 或 月份) 為選用項目,使用任何參數時,您都必須使用 startDate
和 endDate
請求參數來指定報表涵蓋的日期範圍。如果有維度 (如果有的話),表示您希望報表按日期、月份等條件匯總。
這份報表提供了特定時間間隔的播放詳情統計資料。它支援 liveOrOnDemand 維度 (和篩選器)。
這份報表提供了特定時間間隔的播放詳情統計資料。這個平台支援 averageViewPercentage 指標。
各國家/地區的播放詳情
這份報表按國家/地區提供播放播放次數統計資料。它支援 liveOrOnDemand 維度 (和篩選器)。
下列報表與前一份報表類似。新增 averageViewPercentage 指標的支援,但不支援 liveOrOnDemand 維度或篩選器。
各省的播放詳情
本報表提供美國各州與哥倫比亞特區的詳細播放統計資料。它支援 liveOrOnDemand 維度 (和篩選器)。
下列報表與前一份報表類似。新增 averageViewPercentage 指標的支援,但不支援 liveOrOnDemand 維度或篩選器。
播放位置
影片播放位置報表
此報表提供與播放影片或網頁或應用程式類型相關的統計資料。
播放位置詳細資料 (<= 25 個結果)
注意:如要使用這份報表,您必須將 maxResults
參數設為 25
以下的整數。與其他大多數的報表不同,這份報表也需要為 sort
請求參數指定值。
此報表會找出哪些頻道內嵌了某個頻道的影片觀看次數最多,或有多少觀眾最常收看該影片。
流量來源
流量來源
這份報表會依據觀眾觀看您影片內容的方式,彙整觀看相關統計資料。例如,Google 搜尋可產生的觀看次數,包括來自 Google 搜尋或相關影片連結的觀看次數。
流量來源詳細資料 (<= 25 個結果)
注意:如要使用這份報表,您必須將 maxResults
參數設為 25
以下的整數。與其他大多數的報表不同,這份報表也需要為 sort
請求參數指定值。
此報告根據頻道內容觀看次數最多的參照網址,彙整了觀看統計資料。推薦人會按照流量來源類型進行分類,而 insightTrafficSourceDetail 維度可識別可用的報表流量來源。舉例來說,如果您將 insightTrafficSourceType 篩選器設定為 ADVERTISING
,該報表就會列出為頻道內容帶來最多觀看次數或觀看時間的廣告類型。
注意:這份報表僅支援特定流量來源。舉例來說,NO_LINK_EMBEDDED
流量來源沒有其他詳細資訊,因此不支援這份報表。如要進一步瞭解哪些流量來源支援這份報表,請參閱 insightTrafficSourceType 定義。
裝置類型和作業系統
裝置類型
這份報表會依據觀眾觀看您影片內容的方式,彙整觀看相關統計資料。舉例來說,該報表會識別行動裝置或遊戲主機帶來的觀看次數。
作業系統
這份報表會依據觀眾作業系統彙整觀看統計資料。舉例來說,該報表可識別 Android 裝置或 PlayStation 發生的觀看次數。
作業系統和裝置類型
這份報表會依據觀眾作業系統和裝置類型匯總觀看統計資料。舉例來說,該報表可識別 Android 平板電腦或 Windows 電腦裝置的觀看次數。
觀眾客層
這份報表會依據觀眾年齡層和性別匯總觀看統計資料。
參與度和內容分享
這份報表提供的統計資料,顯示頻道影片在不同社交平台上的分享頻率。
觀眾續看率
這份報表會評估影片是否能持續吸引觀眾的注意力。elapsedVideoTimeRatio
維度可評估對應的指標值已播放的影片數量。audienceWatchRatio
和 relativeRetentionPerformance
指標提供兩種測量結果,顯示影片留住觀眾的成效。第一項是絕對值,第二張則是與長度相近的其他 YouTube 影片比較成效。
注意:觀眾續看率報表不支援為 video
篩選器指定值清單 (以逗號分隔),該值必須指定一個影片 ID。
熱門影片
注意:如要使用這些報表,您必須將 maxResults
參數設為 200
以下的整數。2013 年 1 月 1 日之前的資料,僅限前 10 名影片使用。與其他大多數的報表不同,這些報表會要求您為 sort
請求參數指定值。
提供選用的地區篩選器的熱門影片 (少於 200 個)
這份報表會列出頻道的熱門影片。您可以依據國家/地區、洲別或 subContinent 等條件來篩選熱門影片。
各州熱門影片 (<= 200 個結果)
這份報表會列出美國特定州或哥倫比亞特區的熱門影片。請注意,這份報表僅支援上述國家/地區專屬報表中的部分指標。
已訂閱或未訂閱的觀眾最常訂閱的影片(<= 200 筆結果)
這份報表會列出頻道訂閱頻道或未訂閱頻道的熱門影片。您可以依據國家/地區、洲別或 subContinent 等條件來篩選熱門影片。先前的報告可讓您擷取已訂閱或未訂閱頻道的觀眾在美國各部熱門影片,不過系統支援的指標比這份報表少。
熱門 YouTube 產品影片 (少於 200 項結果)
這份報表會列出頻道的熱門影片,並支援播放詳情和地理區域篩選器。這份報表與前期報表相似,但支援的指標較少,且支援 youtubeProduct 篩選器。
含播放詳細資料篩選器的熱門影片 (少於 200 個搜尋結果)
這份報表會列出頻道中的熱門影片,並依任何或所有播放詳細資料維度進行篩選:liveOrOnDemand、subscribedStatus 和 youtubeProduct。與上一份報表不同,此篩選器支援 liveOrOnDemand 篩選器,而且不支援 averageViewPercentage 指標。
播放清單報表
基本統計資料
這份報表提供使用者與頻道播放清單互動的相關統計資料,您可以篩選報表,只傳回特定播放清單或國家/地區的資料。
根據時間
這份報表提供使用者與頻道播放清單互動的相關統計資料,您可以篩選報表,只傳回特定播放清單或國家/地區的資料。
使用者地理位置
各國家/地區的播放清單活動
這份報表提供使用者與頻道播放清單互動的相關統計資料,您可以篩選報表,只傳回特定播放清單、播放清單群組或國家/地區的資料。
播放清單 (依省份)
這份報表提供了美國各州與哥倫比亞特區的播放清單活動統計資料。針對這份報表,請在 filters
參數值中加入 country==US
。
播放位置
此報表提供與播放播放清單的網頁或應用程式類型相關的統計資料。
播放位置詳細資料 (<= 25 個結果)
注意:如要使用這份報表,您必須將 maxResults
參數設為 25
以下的整數。與其他大多數的報表不同,這份報表也需要為 sort
請求參數指定值。
這份報表會列出哪些頻道內嵌在某個頻道播放清單中產生最多觀看次數或觀看時間。
流量來源
這份報表會依據觀眾瀏覽播放清單內容的方式,彙整觀看相關統計資料。例如,此資料可指出 Google 搜尋所產生的檢視次數。
流量來源詳細資料 (<= 25 個結果)
注意:如要使用這份報表,您必須將 maxResults
參數設為 25
以下的整數。與其他大多數的報表不同,這份報表也需要為 sort
請求參數指定值。
這份報表會依據頻道觀看次數最多的參照網址,彙整觀看相關統計資料。推薦人會按照流量來源類型進行分類,而 insightTrafficSourceDetail 維度的定義可用來指出報表中可用的流量來源。
舉例來說,如果您將 insightTrafficSourceType 篩選器設為 ADVERTISING
,報表會列出頻道播放清單中觀看次數最多或觀看時間最高的廣告類型。
注意:這份報表僅支援特定流量來源。舉例來說,NO_LINK_EMBEDDED
流量來源沒有其他詳細資訊,因此不支援這份報表。如要進一步瞭解哪些流量來源支援這份報表,請參閱 insightTrafficSourceType 定義。
裝置類型和作業系統
裝置類型
這份報表會依據觀眾瀏覽播放清單內容的方式,彙整觀看相關統計資料。舉例來說,該報表會識別行動裝置或遊戲主機帶來的觀看次數。
作業系統
這份報表會依據觀眾作業系統彙整觀看統計資料。舉例來說,該播放清單會識別 Android 裝置或 PlayStation 的播放清單觀看次數。
作業系統和裝置類型
這份報表會依據觀眾作業系統和裝置類型匯總觀看統計資料。舉例來說,該圖示可識別在 Android 平板電腦或 Windows 電腦裝置上產生的播放清單觀看次數。
觀眾客層
觀看時間最長的播放清單
注意:如要使用這些報表,您必須將 maxResults
參數設為 200
以下的整數。2013 年 1 月 1 日前,我們只能提供前 10 名播放清單的資料。與其他大多數的報表不同,這些報表會要求您為 sort
請求參數指定值。
這份報表會根據指定的篩選和排序條件,列出頻道的熱門播放清單。
注意:廣告成效報表需要授權憑證才能授予「https://www.googleapis.com/auth/yt-analytics-monetary.readonly
」範圍的存取權。
廣告成效報表會針對影片播放期間放送的廣告,提供曝光次數指標。這些指標會計入每次廣告曝光,且每次影片播放都會帶來多次曝光。
以曝光次數為依據的廣告成效指標如下:
此外,部分影片報表也支援以下播放型廣告成效指標。但廣告成效報表不包含這些指標。