Introduction

本文件說明 YouTube Analytics API 和 YouTube Reporting API 提供 YouTube 數據分析資料存取權時,兩者相似和的差異。本文件旨在協助您選擇適合應用程式的 API。

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

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

  • 內容擁有者報表會針對與特定 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 排定報表工作,每個工作都代表 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 份不同的報表)
不重複維度 群組 (僅限篩選器維度)
洲別 (僅限篩選的維度)
子洲別 (僅限篩選器維度)

匯總==1 (僅限篩選器維度)
平均觀看時間播放清單
平均時間清單
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
不重複指標 Uniques
relativereservationPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
estimated_partner_adsense_revenue
estimated_partner_adsense_revenue

API 之間的命名差異

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

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

尺寸

YouTube Analytics API 名稱 YouTube Reporting API 名稱
廣告類型 ad_type
ageGroup age_group [年齡層]
資產 asset_id
audienceType audience_retention_type
頻道 channel_id
claimedStatus claimed_status
內容擁有者 content_owner_id
country country_code
日期
deviceType device_type
經過時間處理 E 經過時間_video_time_percentage
性別 性別
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
共用服務 sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
影片 video_id

指標

YouTube Analytics API 名稱 YouTube Reporting API 名稱
廣告收益 estimated_partner_ad_revenue
annotationImpression annotation_impressions
annotationClickableImpression annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpression 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
cardImpression card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpression card_teaser_impressions
comments comments
不喜歡 不喜歡
收益 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
喜歡次數 喜歡次數
營利播放次數 estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_add
savesRemoved playlist_saves_removed
分享次數 分享次數
獲得的訂閱人數 subscribers_gained
流失的訂閱人數 subscribers_lost
videosAddedTo 播放清單 videos_add_to_playlists
影片從播放清單中移除 video_removed_from_playlist
觀眾百分比 views_percentage
觀看次數 觀看次數