Introduction

本文件將說明 YouTube Analytics API 和 YouTube Reporting API 存取 YouTube 數據分析資料之間的相似與不同之處。本文件旨在協助您為應用程式選擇合適的 API。

這兩個 API 都可讓開發人員擷取 YouTube 數據分析資料。此外,這兩種 API 都支援 YouTube 頻道擁有者和 YouTube 內容擁有者,這兩種 API 分別可存取一組特定的報表:

  • 管道報表包含指定管道的使用者活動指標。

  • 內容擁有者報表會針對與指定 YouTube 內容擁有者連結的所有頻道匯總指標。舉例來說,唱片公司可以擷取一份報表,其中包含所有唱片公司旗下所有藝人的 YouTube 頻道合併統計資料。有些內容擁有者報表包含使用者活動指標,有些則提供與收益和廣告成效相關的指標。

Reporting API 也可讓部分內容擁有者存取系統管理的廣告收益報表。您必須使用 Reporting API 擷取系統管理報表中的資料。

所有 YouTube 數據分析和 YouTube Reporting API 要求,都必須獲得擁有所需資料的頻道或內容擁有者授權。

檢舉內容

API 擷取的報表包含兩種類型的資料:

  • 「維度」是常見的資料條件,用來匯總資料,例如使用者活動發生的日期或使用者所在的國家/地區。

    在報表中,每列資料都有一組不重複的維度值。因此,每列的維度值的組合可做為該列的主鍵。

  • 指標是指使用者活動、廣告成效或預估收益的個別評估資料。使用者活動指標包括影片觀看次數與評分 (喜歡和不喜歡的人數)。

選擇適合應用程式的 API

YouTube Analytics API
YouTube Analytics API 支援即時指定查詢,可產生自訂的 YouTube 數據分析報表。API 提供篩選和排序參數,因此呼叫應用程式不需要原生支援這些函式。

每個 API 要求都會指定要傳回資料的日期範圍。您也可以透過 API 擷取每週和每月資料集。因此,呼叫應用程式不需要儲存擷取的資料集或跨日期範圍匯總統計資料。
YouTube Reporting API
YouTube Reporting API 會擷取含有頻道或內容擁有者 YouTube 數據分析資料的大量報表。這個 API 專為可匯入大型資料集的應用程式所設計,並提供篩選、排序及挖掘資料的工具。

每份報表都包含一組預先定義的欄位。開發人員可使用 API 安排報表工作,每個工作都識別 YouTube 要產生的報表。YouTube 隨後就會產生每日報表,並以非同步方式下載。每份報表包含的不重複 24 小時資料。

此外,對於可存取 YouTube 創作者工作室對應報表的內容擁有者,YouTube 會自動產生一組系統管理的報表。這些報表可讓你透過程式輔助方式存取廣告收益資料。

受支援的報表

下表列出您可以使用 API 擷取的各種報表。你可以透過 YouTube Analytics API 取得指定目標查詢,也可以透過 YouTube Reporting API 取得大量報表。

其中一個 API 提供的資料可能無法在另一個 API 中使用。舉例來說,YouTube Analytics API 可讓您每週或每月擷取使用者活動指標,但 YouTube Reporting API 規定也必須自行匯總這些資料。不過,YouTube Reporting API 也支援內容擁有者的資產報表,但無法透過 YouTube Analytics API 取得這些資料。

報表類型
影片報表 支援頻道 (查詢大量操作) 和內容擁有者 (查詢大量查詢)。

影片報表會提供與頻道影片或內容擁有者影片相關的所有使用者活動統計資料。舉例來說,這些報表包含影片獲得的觀看次數。在 YouTube Analytics API 中,部分內容擁有者影片報表也包含預估收益和廣告成效指標。
播放清單報表 支援頻道 (查詢大量操作) 和內容擁有者 (查詢大量查詢)。

播放清單報表提供與播放清單中影片觀看次數相關的統計資料。YouTube Reporting API 支援播放清單的觀眾續看率報表,但 YouTube Analytics API 不支援類似報表。
廣告成效報表 支援內容擁有者 (查詢大量查詢)。

廣告成效報表針對影片播放期間放送的廣告,提供曝光次數相關指標。這些指標會計算每次廣告曝光,而每次播放影片都可能產生多次曝光。
估算的收益報表 支援內容擁有者 (大量)。

「預估收益」報表會針對 Google 銷售廣告來源和非廣告來源的影片提供預估總收益。這些報表也提供一些廣告成效指標。請注意,系統管理的報表包含實際收益。
資產報表 支援內容擁有者 (大量)。

資產報表會針對與內容擁有者資產連結的影片,提供使用者活動指標。如果內容擁有者已聲明該影片與內容擁有者的資產相符,該部影片就會納入內容擁有者的報表中。影片可能是由內容擁有者或其他 YouTube 使用者上傳。
系統管理的報告 如果內容擁有者可存取 YouTube 工作室「報表」選單中的相應報表,即可使用這個選項。

系統管理報表會提供資產和影片實際賺取的實際收益資料。另一種報表會列出已聲明版權影片,以及影片相符的資產。請注意,目前只能透過 API 取得部分創作者工作室報表。

注意:對於可存取創作者工作室對應報表的內容擁有者,YouTube 會自動產生系統管理報表。因此,擷取這些報表的程序與這份清單中其他類型的報表不同。詳情請參閱系統管理的報表說明文件。

主要差異

下表列出 YouTube 數據分析和 Reporting API 之間的重要差異。

功能 YouTube Analytics API YouTube Reporting API
擷取資料的程序 每個 API 要求都會指定要傳回的維度和指標,以及傳回資料的時間範圍。 應用程式排定報表工作。YouTube 會針對每項工作,產生每日報表以非同步方式下載。
日期範圍 有些 API 報表會指定使用者活動發生的日期。有些報表支援維度,可依月份匯總使用者活動指標。 所有 API 報表都會指明使用者活動發生的日期。使用 API 的應用程式可實作功能,針對定期間隔匯總資料。
篩選資料 您可以篩選報表,只顯示維度具有特定值的資料列。該 API 也支援某些只能當做篩選器使用的維度,例如「洲別」和「子洲別」subContinent API 支援大量下載完整資料集。但不支援針對僅限篩選的維度篩選或傳回資料。用戶端應用程式會儲存下載的資料,並實作其專屬的篩選資料功能。
排序 報表可根據傳回的指標值排序。部分報表僅支援少數結果。舉例來說,在列出頻道觀看次數最多的影片時,報表會傳回最多 200 列資料。 這個 API 支援大量下載完整的資料集。用戶端應用程式可以實作自己專屬的功能,以排序已下載的資料。
列舉 API 報表包含「ANDROID」或「CHANNEL」等文字值,用來識別列舉的維度值。 API 報表包含可對應至文字值的整數。
配額 API 伺服器會評估每筆查詢,判斷配額費用。配額用量一節會詳細說明方法。 配額用量並不是問題,因為擷取一次資料,然後在應用程式中進行篩選、排序及查詢。
不重複報表
  • 與字幕相關的使用者活動
  • 播放清單的觀眾續看率資料
  • 內容擁有者的預估收益報表 (提供 2 份不同的報表)
  • 內容擁有者專用的資產報表 (提供 11 份不同的報表)
不重複維度 group (僅限篩選器的維度)
洲別 (僅限篩選器的維度)
subContinent (僅限篩選器的維度)

isCurated==1 (僅限篩選器的維度)
viewsPerPlaylistStart
averageTimeInPlaylist
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
不重複指標 uniques
relativeRetentionPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
estimated_partner_adsense_revenueestimated_partner_doubleclick_revenueplaylist_saves_addedplaylist_saves_removed

API 之間的命名差異

這兩個 API 目前使用不同的命名慣例來識別維度和指標。目前,YouTube 數據分析 API 名稱會使用駝峰式大小寫,而 YouTube Reporting API 名稱則是使用以底線分隔的名稱。

下表找出這兩個 API 用來識別相同的指標和維度的不同名稱。在某些情況下,這兩個名稱的差異會大於將名稱從駝峰式大小寫轉換為底線後得到的結果。舉例來說,YouTube Analytics API 中的「video」維度在 YouTube Reporting API 中稱為 video_id

尺寸

YouTube 數據分析 API 名稱 YouTube Reporting API 名稱
adType ad_type
ageGroup age_group
資產 asset_id
audienceType audience_retention_type
聲道 channel_id
claimedStatus claimed_status
contentOwner content_owner_id
country country_code
日期
deviceType device_type
elapsedVideoTimeRatio elapsed_video_time_percentage
gender gender
insightPlaybackLocationDetail playback_location_detail
insightPlaybackLocationType playback_location_type
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType traffic_source_type
liveOrOnDemand live_or_on_demand
operatingSystem operating_system
播放清單 playlist_id
province province_code
sharingService sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
影片 video_id

指標

YouTube 數據分析 API 名稱 YouTube Reporting API 名稱
adEarnings estimated_partner_ad_revenue
annotationImpressions annotation_impressions
annotationClickableImpressions annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpressions annotation_closable_impressions
annotationCloses annotation_closes
annotationCloseRate annotation_close_rate
audienceWatchRatio audience_retention_percentage
averageViewDuration average_view_duration_seconds
averageViewPercentage average_view_duration_percentage
cardClickRate card_click_rate
cardClicks card_clicks
cardImpressions card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpressions card_teaser_impressions
留言 留言
不喜歡 不喜歡
收益 estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
grossRevenue estimated_youtube_ad_revenue
impressionBasedCpm estimated_cpm
曝光 ad_impressions
喜歡次數 喜歡次數
monetizedPlaybacks estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_added
savesRemoved playlist_saves_removed
分享 分享
subscribersGained subscribers_gained
subscribersLost subscribers_lost
videosAddedToPlaylists videos_added_to_playlists
videosRemovedFromPlaylists videos_removed_from_playlist
viewerPercentage views_percentage
檢視畫面 檢視畫面