修訂記錄

本頁列出 YouTube Reporting API 和 YouTube Analytics API 的 API 異動和說明文件更新。這兩個 API 都能讓開發人員存取 YouTube 數據分析資料，但方式不同。

2026 年 11 月 6 日

YouTube Reporting API 和 YouTube Analytics API 的播放位置維度說明文件已更新：

  • 在 YouTube Reporting API 中，playback_location_type 維度表格現在會記錄 11 (在直向直播動態中發生的觀看次數) 和 12 (在 YouTube Music「發現」分頁中發生的觀看次數) 的值。
  • 在 YouTube Analytics API 中，insightPlaybackLocationType 維度定義現在會列出 IMMERSIVE_LIVE_FEED (在直式直播動態中發生的觀看次數) 和 SHORTS_FEED (在 YouTube Shorts 動態中發生的觀看次數)。

2026 年 11 月 4 日

自 2027 年 1 月 15 日起，內容擁有者每週參考檔案報表 (content_owner_active_references_a1) 的 1.0 版已淘汰，並由 1.1 版 (content_owner_active_references_a2) 取代。請務必在 2027 年 1 月 15 日前遷移至最新版本。

2026 年 10 月 30 日

YouTube Reporting API 現在支援下列內容擁有者系統管理報表：

類別 報表名稱 報表類型 ID
財務摘要 每月管道調整摘要 content_owner_channel_adjustments_summary_a1
財務摘要 每月付費功能交易收益 content_owner_transactions_paid_features_revenue_a1
財務摘要 每月 TVOD 交易收益 (依影視內容和國家/地區細分) tvod_content_owner_country_title_tvod_revenue_a1
財務摘要 各國家/地區的每月 TVOD 交易收益 tvod_content_owner_country_transactions_tvod_revenue_a1
Shorts 每月音樂唱片公司 Shorts 資產作品 music_content_owner_shorts_asset_creations_a1
Shorts 每月音樂唱片公司 Shorts 資產觀看次數 music_content_owner_shorts_asset_views_a1
Shorts 每月詞曲出版社 Shorts 資產作品 publisher_content_owner_shorts_asset_creations_a1
Shorts 每月詞曲出版社 Shorts 資產觀看次數 publisher_content_owner_shorts_asset_views_a1
稅金 MCN 聯盟頻道每月退稅摘要報表 content_owner_affiliate_tax_refund_summary_a1
資產 每週 SRMF 報表 publisher_content_owner_weekly_srmf
資產 每日藝人官方頻道要求狀態報表 content_owner_oac_request_status_a1
資產 每日藝人官方頻道要求品質報表 content_owner_oac_quality_status_a1

2026 年 9 月 13 日

YouTube Reporting API 現在支援內容擁有者每週參考檔案報表 (content_owner_active_references_a2) 的 1.1 版。

1.1 版包含下列異動：

  • 新增 status_detail 欄位，提供參考檔案狀態的額外詳細資料或原因。
  • 更新 asset_owners 欄位，改用內容擁有者顯示名稱或外部 ID，而非合作夥伴代碼。

舊版報表版本 1.0 (content_owner_active_references_a1) 仍可使用。

2026 年 9 月 9 日

YouTube Analytics API 和 YouTube Reporting API 說明文件已更新，新增及釐清下列內容：

  • 資料更新間隔和延遲服務水準協議：在「資料模型」中新增專屬章節，說明 48 到 72 小時的資料處理延遲、結束日期截斷至最後一個完整處理日，並建議使用 YouTube Data API videos.list 方法取得即時影片統計資料。

  • 頻道報表中的營利指標：更新頻道報表授權說明文件，明確指出如果頻道是 YouTube 合作夥伴計畫 (YPP) 成員，則使用 https://www.googleapis.com/auth/yt-analytics-monetary.readonly 範圍授權的頻道報表支援預估收益和廣告成效指標，而未營利的頻道會傳回 HTTP 403 Forbidden。

  • 查詢限制和參數相容性：在「瞭解報表表格」中新增建議附註，說明無效或互斥的維度、指標和篩選器組合會傳回 HTTP 400 badRequest ("The query is not supported.")。

  • 大量報表中的空白維度值：更新 YouTube Reporting API 報表特性，說明 video_id 或 channel_id 等維度欄包含空白字串，以保留已刪除資源的匯總指標計數，並代表頻道層級事件。

2026 年 8 月 27 日

YouTube 將統一所有影片格式的公開觀看次數計算方式，包括長篇影片、直播和 Shorts。只要影片開始播放，YouTube 就會計入公開觀看次數。

營利資格和大多數核心成效指標仍以參與度指標為依據，因此不受影響。創作者的收益仍會以「互動 Shorts 觀看次數」和「互動觀看時數」為計算依據。如要查看這些數據，請依序前往「YouTube 數據分析」>「進階模式」。

YouTube 合作夥伴計畫的資格規定並未變更。YouTube 合作夥伴計畫的加入條件，也將改稱為「有效 Shorts 觀看次數」和「有效觀看時數」(原稱為「有效公開 Shorts 觀看次數」和「有效公開影片觀看時數」)。

詳情請參閱「瞭解 YouTube 內容成效」。

指標 狀態 觸發條件 用途
查看 已更新 影片從第一格開始播放 (包括自動播放、將滑鼠游標懸停在影片上，以及點選/輕觸播放)。 標準公開觀看次數。
參與收視 未變更 第一個影格播放完畢後繼續播放，或使用者點選/輕觸播放。 透過 YouTube 合作夥伴計畫營利、大部分核心數據分析 (點閱率、平均觀看時間) 和參與度報表。
縮圖曝光 未變更 縮圖會直接顯示，不需互動或自動播放。 評估動態消息層級的曝光和包裝。

API 說明文件更新：更新 YouTube Analytics API 指標和 YouTube Reporting API 指標說明文件中的 engagedViews 指標定義。

2026 年 6 月 25 日

YouTube Analytics API (指定查詢) 說明文件已更新，內容擁有者的「依城市劃分的使用者活動」報表已移除。內容擁有者不支援這份報表；內容擁有者查詢使用者活動 (依城市) 時，會傳回空白結果。

2026 年 3 月 9 日

ageGroup (YouTube Analytics API) 和 age_group (YouTube Reporting API) 維度現在包含 YouTube 預估未滿 18 歲的使用者。

2026 年 1 月 15 日

YouTube Reporting API 現已支援頻道和內容擁有者的觸及率報表。觸及率報表提供影片縮圖曝光次數和點閱率的統計資料。

  • channel_reach_basic_a1和channel_reach_combined_a1報表適用於頻道。
  • 內容擁有者可查看content_owner_reach_basic_a1和content_owner_reach_combined_a1報表。

這些報表支援下列新指標：

  • video_thumbnail_impressions
  • video_thumbnail_impressions_ctr

2025 年 9 月 22 日

先前宣布的報表淘汰日期已從 2025 年 9 月 30 日延後至 2025 年 10 月 31 日。在上述日期前，因應 Shorts 觀看次數計算方式異動而更新的報表，仍可取得舊版本，但 Claims 報表 1.0 版 (content_owner_active_claims_a1) 和 Claims 報表 1.1 版 (content_owner_active_claims_a2) 除外，這兩份報表仍會在 9 月 30 日淘汰。

2025 年 6 月 24 日

我們在 2025 年 3 月 26 日宣布，大量報表 API 將配合新的 Shorts 觀看次數計算方式進行更新。異動如下：

  • 我們已為包含檢視畫面的每份報表 (即大多數報表) 建立新版報表。每個受影響報表的版本都會遞增一，例如從版本 a2 變成版本 a3。
  • Shorts 觀看次數現在會以 Shorts 開始播放或重播的次數計算。影片則不受影響。
  • 更新後的報表會新增「engaged_views」欄，反映先前的觀看次數計算方式。

Bulk Reports API 的異動將於 2025 年 6 月 30 日生效。請務必據此調整報表處理方式。

舊版報表將保留至 2025 年 9 月 30 日。2025 年 9 月 30 日後，舊版將會淘汰。請務必遷移至最新版本。

最後，請務必遵循最佳做法處理報表，以免日後報表變更導致處理管道中斷。

下表列出各報表類型的新版本：

YouTube 數據分析的大量資料報表

頻道報表 - 影片報表
報表名稱 舊版 最新版本
使用者活動 channel_basic_a2 channel_basic_a3
使用者活動 (依省分組) channel_province_a2 channel_province_a3
播放位置 channel_playback_location_a2 channel_playback_location_a3
流量來源 channel_traffic_source_a2 channel_traffic_source_a3
裝置類型和作業系統 channel_device_os_a2 channel_device_os_a3
字幕 channel_subtitles_a2 channel_subtitles_a3
合併 channel_combined_a2 channel_combined_a3
頻道報表 - 播放清單報表
報表名稱 舊版 最新版本
使用者活動 playlist_basic_a1 playlist_basic_a2
使用者活動 (依省分組) playlist_province_a1 playlist_province_a2
播放位置 playlist_playback_location_a1 playlist_playback_location_a2
流量來源 playlist_traffic_source_a1 playlist_traffic_source_a2
裝置類型和作業系統 playlist_device_os_a1 playlist_device_os_a2
合併 playlist_combined_a1 playlist_combined_a2
內容擁有者報表 - 影片報表
報表名稱 舊版 最新版本
使用者活動 content_owner_basic_a3 content_owner_basic_a4
使用者活動 (依省分組) content_owner_province_a2 content_owner_province_a3
播放位置 content_owner_playback_location_a2 content_owner_playback_location_a3
流量來源 content_owner_traffic_source_a2 content_owner_traffic_source_a3
裝置類型和作業系統 content_owner_device_os_a2 content_owner_device_os_a3
字幕 content_owner_subtitles_a2 content_owner_subtitles_a3
合併 content_owner_combined_a2 content_owner_combined_a3
內容擁有者報表 - 播放清單報表
報表名稱 舊版 最新版本
使用者活動 content_owner_playlist_basic_a1 content_owner_playlist_basic_a2
使用者活動 (依省分組) content_owner_playlist_province_a1 content_owner_playlist_province_a2
播放位置 content_owner_playlist_playback_location_a1 content_owner_playlist_playback_location_a2
流量來源 content_owner_playlist_traffic_source_a1 content_owner_playlist_traffic_source_a2
裝置類型和作業系統 content_owner_playlist_device_os_a1 content_owner_playlist_device_os_a2
合併 content_owner_playlist_combined_a1 content_owner_playlist_combined_a2
內容擁有者報表 - 素材資源報表
報表名稱 舊版 最新版本
使用者活動 content_owner_asset_basic_a2 content_owner_asset_basic_a3
使用者活動 (依省分組) content_owner_asset_province_a2 content_owner_asset_province_a3
影片播放位置 content_owner_asset_playback_location_a2 content_owner_asset_playback_location_a3
流量來源 content_owner_asset_traffic_source_a2 content_owner_asset_traffic_source_a3
裝置類型和作業系統 content_owner_asset_device_os_a2 content_owner_asset_device_os_a3
合併 content_owner_asset_combined_a2 content_owner_asset_combined_a3

系統代管報表 - 財務 (非音樂)

內容擁有者報表 - Shorts 報告 (非音樂)
報表名稱 舊版 最新版本
全球廣告收益摘要 content_owner_shorts_global_ad_revenue_summary_a1 content_owner_shorts_global_ad_revenue_summary_a2
每日廣告收益摘要 content_owner_shorts_day_ad_revenue_summary_a1 content_owner_shorts_day_ad_revenue_summary_a2
國家/地區廣告收益摘要 content_owner_shorts_country_ad_revenue_summary_a1 content_owner_shorts_country_ad_revenue_summary_a2
廣告收益摘要 content_owner_shorts_ad_revenue_summary_a1 content_owner_shorts_ad_revenue_summary_a2

系統管理的報表 - 非財務

內容擁有者報表 - 版權聲明報表
報表名稱 舊版 最新版本
有效的著作權聲明 content_owner_active_claims_a2 content_owner_active_claims_a3
內容擁有者報表 - 影片中繼資料報表
報表名稱 舊版 最新版本
影片中繼資料 content_owner_video_metadata_a3 content_owner_video_metadata_a4
內容擁有者報表 - 素材資源報表
報表名稱 舊版 最新版本
素材資源 content_owner_asset_a2 content_owner_asset_a3
資產衝突 content_owner_asset_conflict_a2 content_owner_asset_conflict_a3

2025 年 4 月 24 日

如 2025 年 3 月 26 日公告所述，指定查詢 API 將配合新的 Shorts 觀看次數計算方式進行更新：

  • Shorts 的views現在會以 Shorts 開始播放或重播的次數計算。
  • 新指標 engagedViews 會反映先前的觀看次數計算方法。engagedViews 將與 views 一起顯示在所有報表中。

Targeted Queries API 的異動將於 2025 年 4 月 30 日生效。請務必據此調整查詢。

請查看這份修訂版本記錄，瞭解 Bulk Reports API 的異動內容和時間。

2025 年 4 月 22 日

如 2024 年 4 月 7 日公告所述，頻道報表和內容擁有者播放清單報表已淘汰 isCurated 維度。2024 年 12 月 31 日起，系統將不再支援這個維度。該維度已從報表和說明文件中移除。

2025 年 3 月 26 日

本次更新包含下列與 YouTube 數據分析和 YouTube Reporting API 相關的異動：

2025 年 3 月 31 日起，YouTube 將調整 Shorts 觀看次數的計算方式。以往在 YouTube，一部 Shorts 的播放時間達特定秒數後，才計為一次觀看。現在，觀看次數會採計 Shorts 開始播放或重播的次數，且不需達到最短觀看時間門檻。 瞭解詳情

YouTube 數據分析 (指定查詢) 和 Reporting (大量報表) API 將有下列異動：

  • Shorts 的views會計算 Shorts 開始播放或重播的次數。
  • 我們將推出新指標 engagedViews，反映先前的觀看次數計算方法。
  • 如果你是頻道擁有者，或有權存取頻道資料，將能查詢更新後的觀看次數和互動觀看次數。

指定查詢將於 4 月 30 日更新，大量報表則於 6 月 30 日更新。在此之前，觀看次數仍會以舊方法計算。Shorts 和頻道觀看次數與工作室中的數據分析不一致。

此外，先前宣布淘汰每日版權聲明 (1.0 版) 報表的時程已延後。

請查看這份修訂版本記錄，瞭解 API 的變更時間。

2025 年 3 月 3 日

本次更新包含下列 YouTube Reporting API 相關異動：

注意：這是淘汰公告。

每日版權聲明 (1.0 版) 報表已淘汰，2025 年 4 月 30 日起，我們將不再支援這項功能。該報表的定義已相應更新。請改用最新的每日版權聲明報表。

2024 年 11 月 15 日

注意：下列異動將於 2024 年 11 月 18 日生效。

YouTube Analytics (指定查詢) API 說明文件已更新，指出在流量來源報表中，如果查詢的影片數量乘以日期範圍內的天數超過 50,000，API 的 reports.query 方法現在會傳回錯誤。舉例來說，如果查詢擷取 500 個影片 ID 的資料，最多可以要求 100 天的資料。

這項異動會影響頻道和內容擁有者的報表。

如要減少要求傳回的資料列數量，請將查詢拆分為多個查詢，並指定較少的影片或設定較短的日期範圍。一般來說，建議使用大量報表處理大型資料集。

2024 年 5 月 6 日

YouTube 數據分析 (指定查詢) API 支援三種新的頻道報表：

  • 「使用者活動 (按指定行銷區域劃分)」報表是地理區域報表，可提供按指定行銷區域劃分的使用者活動統計資料。如要產生這份報表，請務必將 filters 參數值設為 country==US。

  • 「同時觀看人數」報表會顯示單一直播影片不同片段的同時觀看人數。

  • 會員取消報表提供統計資料，顯示使用者取消頻道會員資格的原因。

    這份報表採用新的 membershipsCancellationSurveyReason 維度，可指出使用者取消頻道會員資格的原因。此外，這份報表也會使用新的 membershipsCancellationSurveyResponses 指標，指出因該原因而取消的頻道會員人數。

此外，觀眾續看率報表也經過強化，支援三項新指標：

2024 年 4 月 7 日

YouTube 數據分析 (指定查詢) API 有多項與內容擁有者播放清單報表相關的更新。這些更新與 2024 年 1 月 19 日宣布的頻道播放清單報表相關更新相同。

下列修訂版本記錄項目提供的資訊，與 2024 年 1 月 19 日的項目幾乎相同。不過請注意，內容擁有者播放清單報表支援 isCurated 維度的期限為 2024 年 12 月 31 日，而頻道播放清單報表支援該維度的期限為 2024 年 6 月 30 日。

  • 注意：這是淘汰公告。

    內容擁有者播放清單報表已淘汰 isCurated 維度。2024 年 12 月 31 日起，我們將不再支援這項功能。該維度的定義已相應更新。

    如要在移除 isCurated 維度時保留回溯相容性，您也必須更新程式碼，擷取 playlistViews 指標，而非僅限播放清單報表的 views 指標。雖然播放清單報表仍支援 views 指標，但意義不同，因此即使您未更新指標名稱，API 仍會傳回資料。當然，您也可以修改應用程式，擷取並顯示 views 和 playlistViews。

    除了 isCurated 維度外，新報表也不再支援下列 API 功能：

    • 新的頻道播放清單報表不支援位置篩選器，例如 continent 和 subcontinent。
    • 新的頻道播放清單報表不再支援 redViews 和 estimatedRedMinutesWatched 指標。YouTube 工作室不提供這些指標，因此這項異動可讓 API 功能與工作室應用程式的功能保持一致。
    • 頻道播放清單報表不再支援 subscribedStatus 和 youtubeProduct 維度做為篩選條件。YouTube 工作室不提供這些篩選器，因此這項異動可讓 API 功能與工作室應用程式的功能保持一致。

  • 內容擁有者報表說明文件的播放清單報表一節已更新，更詳盡地說明播放清單報表支援的指標類型：

    • 匯總影片指標 提供使用者活動和曝光指標，這些指標是針對內容擁有者播放清單中所有影片匯總而成，且這些影片也屬於該內容擁有者。只有不使用 isCurated 維度的 API 要求，才支援匯總影片指標。
    • 播放清單指標反映使用者在播放清單頁面上的活動和參與度。這些指標也包含播放清單中非自有影片的觀看次數，但僅限於在播放清單中產生的觀看次數。
    • 支援的播放清單指標一節會列出播放清單報表支援的匯總影片指標和播放清單內指標。

  • 內容擁有者的播放清單報表支援下列新的播放清單內指標。請注意，只有在擷取報表的 API 要求「不」使用 isCurated 維度時，系統才支援這些指標。如需各項指標的定義，請參閱指標說明文件：

  • views 指標的行為現在取決於擷取播放清單報表的 API 要求是否使用 isCurated 維度：

    • 如果要求包含 isCurated 維度，views 指標就是播放清單內指標，代表影片在內容擁有者播放清單中的觀看次數。
    • 如果要求不含 isCurated 維度，views 指標會是匯總影片指標，指定內容擁有者播放清單中影片的總觀看次數，無論這些觀看次數是否發生在播放清單中。匯總總數只會計入與播放清單擁有者頻道相關聯的內容擁有者所擁有的影片觀看次數。

      在這些報表中，playlistViews 指標代表影片在播放清單中播放的次數，不使用 isCurated 維度。這項指標會計算播放清單中所有影片的觀看次數，無論影片屬於哪個頻道。

  • 針對每份播放清單報表，內容擁有者報表說明文件現在會根據 API 要求是否包含 isCurated 維度，提供表格顯示該報表支援的指標。如需範例，請參閱以時間為準的播放清單報表定義一節。

2024 年 1 月 19 日

YouTube 數據分析 (指定查詢) API 有幾項與頻道播放清單報表相關的更新。包括淘汰一項維度，以及新增/更新多項指標：

  • 注意：這是淘汰公告。

    管道報表已淘汰 isCurated 維度。2024 年 6 月 30 日起，我們將不再支援這項功能。該維度的定義已相應更新。

    如要在移除 isCurated 維度時保留回溯相容性，您也必須更新程式碼，擷取 playlistViews 指標，而非僅限播放清單報表的 views 指標。雖然播放清單報表仍支援 views 指標，但意義不同，因此即使您未更新指標名稱，API 仍會傳回資料。當然，您也可以修改應用程式，擷取並顯示 views 和 playlistViews。

    除了 isCurated 維度外，新報表也不再支援下列 API 功能：

    • 新的頻道播放清單報表不支援位置篩選器，例如 continent 和 subcontinent。
    • 新的頻道播放清單報表不再支援 redViews 和 estimatedRedMinutesWatched 指標。YouTube 工作室不提供這些指標，因此這項異動可讓 API 功能與工作室應用程式的功能保持一致。
    • 頻道播放清單報表不再支援 subscribedStatus 和 youtubeProduct 維度做為篩選條件。YouTube 工作室不提供這些篩選器，因此這項異動可讓 API 功能與工作室應用程式的功能保持一致。

  • 頻道報表說明文件的播放清單報表一節已更新，更詳盡地說明播放清單報表支援的指標類型：

    • 匯總影片指標提供使用者活動和曝光指標，這些指標是針對頻道播放清單中所有影片匯總而得，且這些影片也屬於該頻道。只有不使用 isCurated 維度的 API 要求，才支援匯總影片指標。
    • 播放清單指標反映使用者在播放清單頁面上的活動和參與度。這些指標也包含播放清單中非自有影片的觀看次數，但僅限於在播放清單中產生的觀看次數。
    • 支援的播放清單指標一節會列出播放清單報表支援的匯總影片指標和播放清單內指標。

  • 頻道播放清單報表支援下列新的播放清單內指標。 內容擁有者報表尚不支援這些指標。請注意，只有在擷取報表的 API 要求「未」使用 isCurated 維度時，系統才支援這些指標。如需各項指標的定義，請參閱指標說明文件：

  • views 指標的行為現在取決於擷取播放清單報表的 API 要求是否使用 isCurated 維度：

    • 如果要求包含 isCurated 維度，views 指標會是播放清單內指標，代表影片在頻道播放清單中的觀看次數。
    • 如果要求不含 isCurated 維度，views 指標會是匯總影片指標，指定頻道播放清單中影片的總觀看次數，無論這些觀看次數是否發生在播放清單情境中。匯總總數只包含播放清單擁有者頻道所擁有的影片觀看次數。

      在這些報表中，playlistViews 指標代表影片在播放清單中播放的次數，不使用 isCurated 維度。這項指標會計算播放清單中所有影片的觀看次數，無論影片屬於哪個頻道。

  • 針對每份播放清單報表，頻道報表說明文件現在會根據 API 要求是否包含 isCurated 維度，提供表格顯示該報表支援的指標。如需範例，請參閱以時間為準的播放清單報表定義一節。

2023 年 12 月 4 日

YouTube 數據分析 (指定查詢) API 已更新，可合併兩個 insightTrafficSourceType 維度值。先前，這個維度會區分播放清單中播放的影片 (PLAYLIST) 和列出播放清單中所有影片的頁面 (YT_PLAYLIST_PAGE)。日後，這兩種觀看次數都會與 PLAYLIST 維度值建立關聯。

2022 年 12 月 15 日

YouTube 數據分析 (指定查詢) API 支援兩項新維度和一份新報表：

  • 新報表會依城市提供使用者活動資料。這份報表適用於頻道和內容擁有者。這份報表包含新的 city 維度，可指出 YouTube 預估的使用者活動發生城市。

  • 新的 creatorContentType 維度會識別與資料列中使用者活動指標相關聯的 YouTube 內容類型。支援的值為 LIVE_STREAM、SHORTS、STORY 和 VIDEO_ON_DEMAND。

    所有頻道和內容擁有者影片報表都支援 creatorContentType 維度，可做為選用維度。

  • YouTube Analytics API 要求範例指南現在包含這兩個新維度的範例。

  • 7DayTotals 和 30DayTotals 維度的參照已從說明文件中移除。我們已於 2019 年 10 月宣布淘汰這些維度。

2022 年 8 月 26 日

YouTube 數據分析 (指定查詢) API 和 YouTube Reporting (大量報表) API 都支援新的流量來源詳細資料值：

2022 年 2 月 11 日

gender 維度的有效值組合將於 2022 年 8 月 11 日當天或之後變更。這可能是 API 實作中回溯不相容的變更。根據《YouTube API 服務條款》的「回溯不相容異動」一節，我們會在異動生效前六個月宣布。請在 2022 年 8 月 11 日前更新 API 導入方式，確保能順利轉換至新的一組值。

具體異動如下：

  • 在 YouTube 數據分析 (指定查詢) API 中，gender 維度目前支援兩個值：female 和 male。2022 年 8 月 11 日當天或之後，該維度將支援三個值：female、male 和 user_specified。
  • 在 YouTube Reporting (大量報表) API 中，gender 維度目前支援三個值：FEMALE、MALE 和 GENDER_OTHER。2022 年 8 月 11 日起，支援的值將變更為 FEMALE、MALE 和 USER_SPECIFIED。

2022 年 2 月 9 日

自 2021 年 12 月 13 日起，我們更新了兩項指標，排除循環播放片段的流量。這項異動會影響 YouTube 數據分析 (指定查詢) API 和 YouTube Reporting (大量報表) API。

2022 年 2 月 2 日

YouTube Reporting (大量報表) API 支援新的流量來源維度值，指出觀看次數來自直播重新導向：

如果是這類流量來源，traffic_source_detail 維度會指定觀眾來源的頻道 ID。

2020 年 9 月 23 日

YouTube Analytics (指定查詢) API 和 YouTube Reporting (大量報表) API 都支援新的流量來源維度值，指出觀眾是透過在 YouTube Shorts 觀看體驗中垂直滑動而來：

YouTube Analytics API 中的 insightTrafficSourceDetail 或 YouTube Reporting API 中的 traffic_source_detail 流量來源詳細資料維度，不會填入這項新流量來源類型的資料。

2020 年 7 月 20 日

本次更新包含兩項異動，會影響 YouTube 數據分析 (指定查詢) API：

  • YouTube 數據分析報表群組的大小上限已從 200 個實體增加到 500 個。
  • reports.query 方法的 filters 參數會識別擷取 YouTube 數據分析資料時應套用的篩選器清單。這項參數可為 video、playlist 和 channel 篩選器指定多個值，且這些篩選器可指定的 ID 數量上限已從 200 個增加到 500 個。

2020 年 2 月 13 日

本次更新包含下列與 YouTube 數據分析 (指定查詢) API 和 YouTube Reporting (大量報表) API 相關的異動。如要進一步瞭解異動內容，歡迎前往 YouTube 說明中心。

在這兩個 API 中，通知的流量來源詳細資料可能值組合將有所變更。 在指定查詢中，通知會回報為 insightTrafficSourceType=NOTIFICATION。在大量報表中，通知會回報為 traffic_source_type=17。

新值會將與上傳影片和直播相關的通知 (先前回報為 uploaded) 分為兩類：

  • uploaded_push - 影片上傳後，系統向訂閱者傳送推播通知，並由該通知帶來的觀看次數
  • uploaded_other：影片上傳後，系統傳送給訂閱者的非推播通知 (例如電子郵件或收件匣通知) 帶來的觀看次數。

系統會傳回 2020-01-13 (2020 年 1 月 13 日) 起的日期範圍值。

另外提醒你，這些值不代表通知本身，而是帶來特定 YouTube 觀看次數的流量來源。舉例來說，如果報表資料列顯示 views=3、traffic_source_type=17 (NOTIFICATION) 和 traffic_source_detail=uploaded_push，表示有三次觀看次數來自觀眾點選影片上傳時傳送的推播通知。

2019 年 10 月 15 日

本次更新包含下列與 YouTube 數據分析 (指定查詢) API 相關的異動：

  • 注意：這是淘汰公告。

    YouTube 將停止支援 7DayTotals 和 30DayTotals 維度。在 2020 年 4 月 15 日前，您仍可使用這些維度擷取資料。上述日期過後，嘗試使用 7DayTotals 或 30DayTotals 維度擷取報表時，系統會傳回錯誤。

    請注意，使用者可以透過 day 維度查詢，並匯總或衍生 7 天或 30 天內的資料，重現這些維度的部分資料。例如：

    • 如要計算七天內的觀看次數，可以將該期間內每天的觀看次數加總。
    • 如要計算七天內的 viewerPercentage，請將每天的觀看次數乘以當天的 viewerPercentage，即可得出當天觀看影片時登入的觀眾人數。接著，系統會將整個期間內已登入的觀看者人數相加，再除以該期間的總觀看次數，得出整個期間的 viewerPercentage。
    • 由於同一位觀眾可能會在不同日期計為不重複觀眾，因此無法計算七天內的不重複觀眾人數。不過，您可以使用「month」維度取代「30DayTotals」維度，推算 30 天內的不重複觀眾人數資料。請注意，month 維度是指日曆月，而 30DayTotals 維度則是根據指定的開始和結束日期計算 30 天。

2019 年 6 月 27 日

本次更新包含下列與 YouTube 數據分析 (指定查詢) API 相關的異動：

  • 由於 API 第 1 版已完全淘汰，說明文件已更新，移除該版本的相關資訊，包括淘汰通知和遷移指南 (說明如何更新至第 2 版)。

2018 年 11 月 1 日

本次更新包含下列與 YouTube 數據分析 (指定查詢) API 相關的異動：

  • API 第 1 版已淘汰。如果您尚未更新 API 用戶端，請盡快更新至第 2 版，盡可能減少服務中斷情形。詳情請參閱遷移指南。

    請注意，這項淘汰作業的時間表原定於 2018 年 4 月 26 日公布。

2018 年 9 月 17 日

本次更新包含下列與 YouTube 數據分析 (指定查詢) API 相關的異動：

  • 資料模型總覽文件的「資料匿名化」新章節說明，如果指標未達特定門檻，部分 YouTube 數據分析資料會受到限制。這可能發生在多種情況下。也就是說，如果發生下列情況，報表可能不會包含所有 (或任何) 資料：

    1. 影片或頻道在特定時間範圍內的流量不足

      或

    2. 您選取的篩選條件或維度 (例如流量來源或國家/地區) 未達到特定門檻。

    新章節也討論了 YouTube 數據分析報表中可能受限的資料類型。

  • 我們已更新頻道報表和內容擁有者報表文件，反映播放位置、流量來源和裝置類型/作業系統報表不再支援 redViews 和 estimatedRedMinutesWatched 指標。

2018 年 6 月 18 日

本次更新對 YouTube 數據分析 (指定查詢) API 進行了下列變更：

  • 下列方法的範圍規定已變更：
    • 對 reports.query 方法提出的要求必須具備 https://www.googleapis.com/auth/youtube.readonly 範圍的存取權。
    • 如要向 groupItems.list 方法提出要求，必須具備下列其中一項存取權：
      • https://www.googleapis.com/auth/youtube 範圍
        或
      • https://www.googleapis.com/auth/youtube.readonly 範圍
        和
        https://www.googleapis.com/auth/yt-analytics.readonly 範圍

      第一個選項使用一個範圍 (剛好是讀寫範圍)，第二個選項則使用兩個唯讀範圍。

2018 年 5 月 23 日

本次更新對 YouTube 數據分析 (指定查詢) API 進行了下列變更：

  • API 總覽新增了「匯總指標和已刪除項目」一節，說明 API 回應如何處理與已刪除資源 (例如影片、播放清單或頻道) 相關聯的資料。
  • 我們更新了 API 總覽的最佳做法一節，提醒您可以使用 YouTube Data API，擷取 YouTube Analytics API 回應中識別資源的其他中繼資料。根據《YouTube API 服務開發人員政策》(第 III.E.4.b 至 III.E.4.d 節)，API 用戶端必須在 30 天後刪除或重新整理儲存的資源中繼資料。

2018 年 5 月 22 日

這項更新包含下列與 YouTube Reporting (大量報表) API 相關的異動：

  • 下列異動目前預定於 2018 年 7 月生效，新政策將全面適用於所有報表和報表工作。

    • 異動後，大部分 API 報表 (包括補播報表) 的效期為 60 天，自產生當日起算。不過，含有歷來資料的報表自產生當日起 30 天內有效。

      在這項公告發布前，所有 API 報表自產生當日起有 180 天的效期。再次強調，這項政策異動生效後，您也無法再透過 API 存取超過 30 天的歷來資料報表。超過 60 天的其他報表也無法再存取。因此，說明文件現在指出，在政策異動前建立的報表最多可保留 180 天。

    • 這項異動生效後，當你排定報表工作時，YouTube 會從當天開始產生報表，並涵蓋排定工作前 30 天的資料。在異動前，當您排定報表工作時，YouTube 會產生涵蓋工作排定時間前 180 天的報表。

  • 我們更新了最佳做法一節，提醒您可以使用 YouTube Data API 擷取報表中資源的其他中繼資料。根據《YouTube API 服務開發人員政策》(第 III.E.4.b 至 III.E.4.d 節)，API 用戶端必須在 30 天後刪除或重新整理儲存的資源中繼資料。

  • 「報表特性」一節已更新，說明即使報表資料未經過篩選，只要報表包含 2018 年 6 月 1 日當天或之後的「時間範圍」資料，就不會包含在報表產生日期前至少 30 天刪除的 YouTube 資源。

  • 我們更新了 API 總覽的歷來資料部分，說明安排新的報表工作後，歷來報表通常會在幾天內發布。先前的文件指出，這類報表最多可能需要 30 天才會提供。

  • 我們更新了 API 總覽的「回填資料」部分，更清楚地將「回填資料」定義為取代先前傳送資料集的新資料集。

2018 年 4 月 26 日

YouTube 數據分析 (指定查詢) API 第 2 版 (v2) 現已公開推出。以下列出與新版 API 相關的產品和說明文件異動：

  • 第 2 版 API 與第 1 版 API 幾乎相同，不過，您可能需要更新程式碼，以反映下列變更。如要進一步瞭解所有異動，請參閱新的遷移指南。

    • API 版本已從 v1 變更為 v2。
    • API 要求的基準網址已從 https://www.googleapis.com/youtube/analytics/v1 變更為 https://youtubeanalytics.googleapis.com/v2。
    • reports.query 方法的多個參數已更新名稱。具體來說，在 v1 API 中包含連字號的參數名稱 (例如 end-date)，在 v2 API 中會使用駝峰式大小寫 (endDate)，而非連字號。這項異動可讓 API 的參數名稱保持一致，因為 API 用於建立及管理群組的方法，已使用駝峰式大小寫做為參數名稱。
    • v2 API 不支援傳送至 Google 全域 HTTP 批次端點 (www.googleapis.com/batch) 的批次要求。如要透過 v2 API 傳送批次要求，請改用端點 https://youtubeanalytics.googleapis.com/v2。

    此外，v2 API 不支援部分 v1 功能：

    • reports.query 方法不再支援 alt、quotaUser 和 userIp 要求參數。
    • v2 API 不提供批次端點，可支援由不同 API 要求組成的批次。(不過，批次可以包含對同一 API 的不同方法提出的要求)。這項淘汰措施並非僅針對 YouTube Analytics API，Google 將淘汰所有 API 的全域批次端點。
    • v2 API 不支援 API v1 支援的 JSON-RPC 通訊協定。再次提醒，這項淘汰措施並非僅限於 YouTube Analytics API。

  • 注意：這是淘汰公告。

    API 第 1 版 (v1) 現已淘汰，支援服務將於 2018 年 10 月 31 日終止。屆時，所有向第 1 版 API 提出的要求都會失敗。因此，請務必在 2018 年 10 月 31 日前升級至第 2 版 API，以免無法透過 API 存取 YouTube 數據分析資料。

2018 年 2 月 21 日

本次更新對 YouTube 數據分析 (指定查詢) API 進行了下列變更：

  • 觀眾客層報表會根據觀眾的年齡層和性別匯總觀看統計資料，但不再支援 youtubeProduct 維度，該維度會識別發生使用者活動的 YouTube 服務。

2018 年 1 月 18 日

這次更新的修改如下：

  • YouTube Reporting API (大量報表)

    • operating_system 維度可識別影片播放裝置的軟體系統，現在支援下列值：
      • 25：KaiOS

  • YouTube Analytics API (指定查詢)

2017 年 12 月 20 日

本次更新包含兩項與 YouTube Reporting API 相關的異動：

  • API 伺服器現在支援對下載報表的要求進行 gzip 壓縮。請注意，其他類型的 API 要求不支援 gzip 壓縮。啟用 gzip 壓縮功能可減少每個 API 回應所需的頻寬。雖然應用程式需要額外的 CPU 作業時間來解壓縮 API 回應，但減少網路資源消耗的好處通常大於這項成本。

    如要接收 gzip 編碼的回應，請將 Accept-Encoding HTTP 要求標頭設為 gzip，如下例所示：

    Accept-Encoding: gzip

    如要瞭解這項功能，請參閱 API 總覽和 report 資源 downloadUrl 屬性的定義。

  • age group 和 gender 維度的說明文件已修正，顯示 API 針對這些維度傳回的實際值。請注意，這項異動僅修正說明文件，不影響 API 功能或行為。具體來說，下列值已變更：

    • age_group 維度的值使用大寫字母，在 AGE 字詞和年齡層中的數字之間包含底線，並使用底線而非連字號。因此，age13-17 和 age18-24 等值已分別更正為 AGE_13_17 和 AGE_18_24。
    • gender 維度的值使用大寫字母。因此，female、male 和 gender_other 的值已更正為 FEMALE、MALE 和 GENDER_OTHER。

2017 年 8 月 10 日

2016 年 8 月 10 日，這份說明文件宣布淘汰 YouTube Analytics API 的 earnings 指標。(同時，API 也新增了名為 estimatedRevenue 的新指標，可提供相同資料)。

由於「earnings」是指標核心，因此在公告日期後的一年內仍可使用。不過，一年期限已過，系統不再支援earnings指標。因此，指定 earnings 指標的 API 要求現在會傳回 400 HTTP 回應代碼。如果您尚未更新應用程式，請盡快將 earnings 指標改為 estimatedRevenue 指標。

API 說明文件已更新，移除 earnings 指標的所有剩餘參照。

2017 年 7 月 6 日

這次更新的修改如下：

  • YouTube Analytics API (指定查詢)

    • API 說明文件已更新，反映 API 回應包含的資料，直到所查詢的所有指標都可用的要求日期範圍最後一天。

      舉例來說，如果要求指定的結束日期是 2017 年 7 月 5 日，但所有要求指標的值都只到 2017 年 7 月 3 日，則回應中包含的資料最後日期就是 2017 年 7 月 3 日。(即使 2017 年 7 月 4 日有部分所要求指標的資料，也是如此)。

    • adType 維度現在支援 reservedBumperInstream 值，代表最長 6 秒的不可略過影片廣告，會在影片播放前顯示。廣告格式與auctionBumperInstream廣告相同，但這種類型是指以預訂而非競價方式銷售的廣告。

  • YouTube Reporting API (大量報表)

    • ad_type 維度現在支援 20 值，代表以預訂方式銷售的串場廣告。串場廣告是不可略過的影片廣告，最長 6 秒，會在影片播放前放送。請注意，這個維度的 19 值也代表透過競價 (而非預訂) 銷售的串場廣告。

    • 下列 YouTube Reporting API 報表的報表工作已刪除：

      • channel_basic_a1
      • channel_province_a1
      • channel_playback_location_a1
      • channel_traffic_source_a1
      • channel_device_os_a1
      • channel_subtitles_a1
      • channel_combined_a1
      • content_owner_basic_a2
      • content_owner_province_a1
      • content_owner_playback_location_a1
      • content_owner_traffic_source_a1
      • content_owner_device_os_a1
      • content_owner_subtitles_a1
      • content_owner_combined_a1
      • content_owner_asset_basic_a1
      • content_owner_asset_province_a1
      • content_owner_asset_playback_location_a1
      • content_owner_asset_traffic_source_a1
      • content_owner_asset_device_os_a1
      • content_owner_asset_combined_a1

      我們已於 2016 年 9 月 15 日宣布淘汰這些報表類型，並於 2016 年 12 月 15 日後停止產生這些類型的報表。先前產生的報表在產生後 180 天內仍可使用。因此，部分報表在 2017 年 6 月 15 日前仍可存取。不過，由於報表已無法使用，因此與報表相關聯的工作也不再需要。

2017 年 5 月 24 日

下列 YouTube Reporting API 報表的所有報表工作都已刪除：

  • content_owner_ad_performance_a1
  • content_owner_asset_estimated_earnings_a1
  • content_owner_estimated_earnings_a1

我們在 2016 年 6 月 22 日宣布淘汰這些報表類型，並於 2016 年 9 月 22 日起停止產生這類報表。先前產生的報表在產生後 180 天內仍可使用。因此，部分報表在 2017 年 3 月 22 日前仍可存取。不過，由於報表已無法使用，因此與報表相關聯的工作也不再需要。

2017 年 5 月 22 日

這次更新的修改如下：

  • YouTube Reporting API (大量報表)

    • sharing_service 維度用於識別分享影片時使用的服務，目前支援下列值：
      • 85：YouTube Music
      • 86：YouTube Gaming
      • 87：YouTube Kids
      • 88：YouTube TV

      此外，說明文件中用來識別 52 值的名稱已更新為 Kakao (Kakao Talk)，以便與 73 值 (Kakao Story) 區分。這項異動不會影響 API 行為，也不會影響與這些服務分享的影片分類。

  • YouTube Analytics API (指定查詢)

    • sharingService 維度現在支援下列值：
      • YOUTUBE_GAMING
      • YOUTUBE_KIDS
      • YOUTUBE_MUSIC
      • YOUTUBE_TV

2017 年 3 月 28 日

頻道擁有者可透過創作者工作室的 YouTube 數據分析查看收益資料，現在也能透過 YouTube Analytics API 存取這些資料：

2017 年 3 月 17 日

這次更新的修改如下：

2017 年 3 月 3 日

這次更新的修改如下：

  • YouTube Reporting API (大量報表)

    • date 維度的定義已修正，指出維度值是指從太平洋時間凌晨 12:00 開始，到指定日期、月份和年份的太平洋時間晚上 11:59 結束。視一年中的時間而定，太平洋時間可能是 UTC-7 或 UTC-8。

      雖然日期通常代表 24 小時，但時鐘向前調整的日期代表 23 小時，時鐘向後調整的日期則代表 25 小時。(先前說明文件指出，每個日期代表不重複的 24 小時，且太平洋時間一律為世界標準時間 -8)。

      請注意，這項修正不代表實際 API 行為有所變更。

    • operating_system 維度可識別影片播放裝置的軟體系統，目前支援下列值：
      • 22：Tizen
      • 23：Firefox
      • 24：RealMedia

    • 已刪除「content_owner_basic_a1」報表類型的所有報表工作。這類報表已於 2016 年 8 月 19 日全面淘汰，但先前產生的 content_owner_basic_a1 報表仍可使用 180 天 (自產生當日起算)。因此，部分報表最晚在 2017 年 2 月 19 日前仍可存取。不過，由於報表已無法使用，因此與報表相關聯的工作也不再需要。

  • YouTube Analytics API (指定查詢)

    • time periods 相關維度的說明已修正，指出維度值是指從太平洋時間凌晨 12:00 開始，到指定日期、月份和年份的太平洋時間晚上 11:59 結束。視一年中的時間而定，太平洋時間可能是 UTC-7 或 UTC-8。

      雖然日期通常代表 24 小時，但時鐘向前調整的日期代表 23 小時，時鐘向後調整的日期則代表 25 小時。(舊版說明文件指出太平洋時間為世界標準時間 -8，且未提及一天可能不代表 24 小時)。

      請注意，這項修正不代表實際 API 行為有所變更。

    • 管道報表說明文件已更新，註明管道報表目前不含收益或廣告成效指標。因此，https://www.googleapis.com/auth/yt-analytics-monetary.readonly 範圍目前不會授予頻道報表中營利資料的存取權。

    • operatingSystem 維度支援三個新的維度值：
      • FIREFOX
      • REALMEDIA
      • TIZEN

2017 年 2 月 8 日

YouTube Analytics API 現在支援選用的 include-historical-channel-data 參數。請注意，只有在擷取內容擁有者報表時，這個參數才適用。

內容擁有者可透過這個參數，指定 API 回應應包含頻道與內容擁有者連結前的觀看時間和觀看次數資料。預設參數值為 false，表示 API 回應預設只會包含頻道連結至內容擁有者後的觀看時間和觀看次數資料。

如果 API 要求擷取多個頻道的資料，也適用這些規則：

  • 如果參數值為 false，則任何指定頻道傳回的觀看時間和觀看次數資料，都會以該頻道連結至內容擁有者的日期為準。

    請務必注意，不同頻道連結至內容擁有者的日期可能不同。如果 API 要求擷取多個頻道的資料，且參數值為 false，則 API 回應會根據各頻道的連結日期，包含觀看時間和觀看次數資料。
  • 如果參數值為 true，回應會根據 API 要求中指定的開始和結束日期，傳回所有頻道的觀看時間和觀看次數資料。

2016 年 12 月 15 日

我們已不再支援下列 YouTube Reporting API 報表，並已從說明文件中移除。每份報表都有新版本。(這些報表的淘汰公告已於 2016 年 9 月 15 日發布)。

API 參考文件中的目前報表類型清單也已更新。

2016 年 11 月 11 日

這次更新的修改如下：

YouTube Reporting API 支援三種新的片尾報表，以及這些報表的新維度和指標。報表會提供影片停止播放後顯示的片尾曝光和點閱統計資料。

2016 年 11 月 8 日

本次更新對 YouTube Analytics API 進行了下列異動：

  • 下列指標已完全淘汰，不再支援。我們已於 2016 年 8 月 10 日宣布，系統已支援參照相同資料的新指標。下表列出已淘汰的指標名稱和新指標名稱：

    已淘汰的指標 新指標
    adEarnings estimatedAdRevenue
    impressionBasedCpm cpm
    impressions adImpressions
    redPartnerRevenue estimatedRedPartnerRevenue

2016 年 10 月 27 日

YouTube 現在會自動為內容擁有者產生一組系統管理的廣告收益報表，內容擁有者可以在 YouTube 創作者工作室的「報表」部分存取對應的報表。新的系統管理 API 報表可讓您透過程式輔助方式，存取創作者工作室手動下載報表中的資料。

系統管理的報表總覽簡要說明新報表，並解釋透過 API 擷取報表的程序。這項程序與擷取 YouTube 數據分析大量報表稍有不同，因為合作夥伴不需要排定工作來產生報表。

reportType 資源的 id 屬性已更新，納入可透過 API 存取的系統管理報表清單：

  • 每月全球每部影片的廣告收益
  • 每部影片在各國家/地區的每日廣告收益
  • 每項資產的每月全球廣告收益
  • 每項資產在各國家/地區的每日廣告收益
  • 著作權聲明 (這份報表不含收益資料)

2016 年 9 月 27 日

注意：這是淘汰公告。

YouTube Analytics API 的 uniques 指標已淘汰。這不是核心指標，支援期限至 2016 年 10 月 31 日。

2016 年 9 月 15 日

本次更新包含下列 YouTube Reporting API 異動：

2016 年 8 月 19 日

本次更新包含下列 YouTube Reporting API 異動：

2016 年 8 月 11 日

這次更新的修改如下：

  • 新發布的《YouTube API 服務條款》(下稱「新版條款」) 對現行《服務條款》進行了多項更新，詳情請參閱 YouTube 工程與開發人員網誌。除了將於 2017 年 2 月 10 日生效的新版條款外，本次更新也包含幾份輔助文件，說明開發人員必須遵守的政策。

    如需新文件的完整組合，請參閱更新條款的修訂版本記錄。此外，日後對「更新版條款」或相關支援文件所做的任何變更，也會在修訂版本記錄中說明。

2016 年 8 月 10 日

本次更新包含以下異動：

  • YouTube Analytics API (指定查詢)

    • 注意：這是淘汰公告。

      下表中的指標即將淘汰。同時，我們也會推出參照相同資料的新指標。這實際上代表舊指標將重新命名，但 YouTube Analytics API 會同時支援這兩種指標名稱，直到表格中列出的淘汰日期為止。

      舊版指標名稱 新版指標名稱 支援日期
      earnings estimatedRevenue 2017 年 8 月 10 日
      adEarnings estimatedAdRevenue 2016 年 11 月 4 日
      redPartnerRevenue estimatedRedPartnerRevenue 2016 年 11 月 4 日
      impressionBasedCpm cpm 2016 年 11 月 4 日
      impressions adImpressions 2016 年 11 月 4 日

      請注意，earnings 指標是核心指標，因此自公告日期起，我們將繼續支援一年。其他非核心指標則會支援三個月，直到 2016 年 11 月 4 日為止。

      舉例來說，在 2016 年 11 月 4 日前，API 要求可以指定 impressionBasedCpm 指標、cpm 指標，或同時指定兩者。但之後就只支援cpm指標。

    • insightTrafficSourceType 維度支援兩個新的維度值：
      • CAMPAIGN_CARD：這項流量來源僅適用於內容擁有者報表。這表示觀看次數來自使用者上傳、已聲明版權的影片，內容擁有者使用這些影片宣傳觀眾觀看的內容。
      • END_SCREEN：這項資料與源自其他影片片尾的觀看次數有關。

      您也可以擷取這兩種新流量來源的 traffic source detail 報表。在這兩種情況下，insightTrafficSourceDetail 維度都會識別觀眾來源影片。

    • adType 維度現在支援 auctionBumperInstream 值，代表最長 6 秒、在影片播放前放送的不可略過影片廣告。

  • YouTube Reporting API (大量報表)

    • traffic_source_type 維度現在支援下列值：
      • 19：這項流量來源僅適用於內容擁有者報表。這表示觀看次數來自使用者上傳、已聲明版權的影片，內容擁有者使用這些影片宣傳觀眾觀看的內容。
      • 20：這項資料與源自其他影片片尾的觀看次數有關。

      這兩個新流量來源的 traffic_source_detail 維度，會指出觀眾是從哪部影片連到你的內容。

    • API 的核心指標清單已修正，將 estimated_partner_revenue 列為核心指標，並從清單中移除 earnings。(YouTube Reporting API 從未支援 earnings 指標)。

    • ad_type 維度現在支援 19 值，代表串場廣告，也就是在影片播放前放送、長度不超過 6 秒且不可略過的影片廣告。

2016 年 7 月 18 日

本次更新包含以下異動：

  • YouTube Analytics API (指定查詢)

    • 下列管道報表支援的指標清單已更新，納入資訊卡指標。我們在 2016 年 6 月 28 日新增了這些報表的資訊卡指標支援，當天的修訂版本記錄項目會更詳細地說明這項異動。報表如下：
      • 美國各州的基本使用者活動
      • 特定時間範圍內美國各州的使用者活動
      • 使用者活動 (依省分組)
      • 使用者活動 (依訂閱狀態劃分)
      • 各省分的使用者活動 (依訂閱狀態劃分)
      • 各州熱門影片
      • 已訂閱或未訂閱觀眾最常觀看的影片

    • 我們已修正頻道觀眾續看率報表和內容擁有者觀眾續看率報表的篩選器清單，反映出必須使用 video 篩選器，且不支援 group 篩選器。

      先前，這兩份報表的文件誤稱，可以使用其中一個篩選器或不使用任何篩選器來擷取報表。

  • YouTube Reporting API (大量報表)

    • 在 API 總覽中，說明如何擷取報表下載網址的部分已修正，指出 YouTube 會針對沒有可用資料的日子產生可下載的報表。這些報表包含標題列，但不含其他資料。這項資訊已於 2016 年 4 月 12 日更新至同一份文件的「報表特性」一節。
    • content_owner_asset_cards_a1報表中的維度清單已修正，反映報表使用card_id維度。舊版說明文件誤將維度名稱列為 card_title。

2016 年 6 月 28 日

YouTube Analytics API 說明文件已更新，反映多個頻道和內容擁有者報表支援資訊卡指標。新支援的指標如下：

下列類型的報表支援這些指標：

2016 年 6 月 22 日

本次更新包含下列 YouTube Reporting API 異動。第一項異動與 API 整體有關，其餘異動則只會影響內容擁有者報表：

  • 我們更新了 API 總覽的「報表特性」一節，明確指出報表自產生當日起 180 天內，可透過 API 存取。

    先前說明文件指出，報表可提供 API 要求傳送日期前最多 180 天的資料。雖然這在技術上也是正確的，但原始文字充其量只是相當令人困惑。

  • 這個 API 支援三種報表的新版本。其中兩份報表也包含新指標和重新命名的指標：

    • 「content_owner_ad_rates_a1」報表是「content_owner_ad_performance_a1」報表的新版本。重新命名的報表與先前版本完全相同。

    • 有兩份報表已推出新版本，並重新命名：

      • 新版content_owner_estimated_earnings_a1報表名為「content_owner_estimated_revenue_a1」。
      • 新版content_owner_asset_estimated_earnings_a1報表名為「content_owner_asset_estimated_revenue_a1」。

      這兩份重新命名的報表與舊版有以下差異：

    請注意，如果您已建立工作來產生這些報表的舊版本，則需要為重新命名的報表建立新工作。隨著新版報表推出，content_owner_ad_performance_a1、content_owner_estimated_earnings_a1 和 content_owner_asset_estimated_earnings_a1 報表已淘汰。

    如果您有任何這類報表的工作，請注意，YouTube 在 2016 年 9 月 22 日後不會再為這些工作產生新報表。已產生的報表在產生後 180 天內仍可使用。

  • reportType 資源的 id 屬性定義已更新，反映目前可用的報表組合。

  • 我們已修正說明文件中的兩項指標名稱，使其與報表中顯示的名稱一致。這只是說明文件修正，不代表實際報表內容有變動：

    • estimated_partner_adsense_revenue 指標的名稱已更新為 estimated_partner_ad_sense_revenue。不過請注意，這項指標只會出現在兩份報表中，而這兩份報表將隨著本次更新而淘汰。如上所述，在新版報表中，這項指標已重新命名為「estimated_partner_ad_auction_revenue」。
    • estimated_partner_doubleclick_revenue 指標的名稱已更新為 estimated_partner_double_click_revenue。再次提醒，這項指標只會出現在本次更新淘汰的兩份報表中。如上所述，這項指標在新版報表中已重新命名為「estimated_partner_ad_reserved_revenue」。

  • Reporting API 的維度說明文件已更新，不再列出 elapsed_video_time_percentage 和 audience_retention_type 屬性。目前 API 提供的報表都不支援這些維度。

2016 年 5 月 19 日

本次更新包含下列 YouTube Reporting API 異動：

  • 這個 API 支援新版內容擁有者使用者活動報表。新報表的報表類型 ID 為 content_owner_basic_a2。與舊版報表 content_owner_basic_a1 不同，新版報表支援likes和dislikes指標。

    即使您已有建立content_owner_basic_a1報表的工作，仍須為content_owner_basic_a2報表建立新工作。YouTube 不會自動將內容擁有者遷移至新版報表，也不會自動建立工作來產生新版報表。在某些實作中，出現新的非預期工作可能會造成破壞性變更。

    隨著新報表推出，content_owner_basic_a1 報表已淘汰。如果您有該報表的工作，YouTube 在 2016 年 8 月 19 日後就不會再為該工作產生新報表。已產生的報表在產生後 180 天內仍可使用。

  • reportType、job 和 report 資源都支援新屬性，可識別相關聯的資源是否代表已淘汰的報表類型：

    • reportType 資源的 deprecateTime 屬性會指定報表類型的淘汰日期和時間。只有在報表已宣布淘汰時，這個屬性才會有值，這個值代表 YouTube 停止產生該類型報表的日期。

      宣布淘汰某種報表類型後，YouTube 會繼續產生該類型的報表三個月。舉例來說，2016 年 5 月 19 日的更新公告指出 content_owner_basic_a1 報表已淘汰。因此，該報表類型的 deprecateTime 會指定 2016 年 8 月 19 日的某個時間，YouTube 將在該時間後停止產生該類型的報表。

    • job 資源的 expireTime 屬性會指定工作的到期日期和時間。如果與工作相關聯的報表類型已淘汰，或系統為工作產生的報表長時間未下載，這個屬性就會有值。這個日期代表 YouTube 不再為該工作產生新報表的時間。

    • report 資源的 jobExpireTime 屬性會指定與報表相關聯的工作已到期或將到期的日期和時間。這個屬性的值與 job 資源中的 expireTime 屬性相同，如本清單前一項所述。

  • 如果您嘗試為已淘汰的報表建立工作，jobs.create 方法現在會傳回 400 HTTP 回應代碼 (Bad Request)。此外，方法說明文件現在也列出導致 API 要求失敗的其他幾個原因。

2016 年 4 月 12 日

本次更新包含下列異動，且僅影響 YouTube Reporting API：

  • YouTube 現在會產生報表工作首次排定前 180 天內的資料。先前，Reporting API 不會提供任何歷來資料。這項異動會影響所有工作，包括在本公告發布前建立的工作。

    歷來報表會在可用時立即發布，但一項工作的所有歷來資料大約需要一個月才能發布。因此，在安排報表工作一個月後，您將可存取約七個月的資料。(公告發布前建立的工作，其所有歷來資料應在公告發布後一個月內發布)。

    請注意，歷來資料最早只能回溯至 2015 年 7 月 1 日。因此，2015 年 12 月 28 日前建立的工作，歷來資料會少於 180 天。

    Reporting API 總覽的新「歷來資料」部分，會說明所有這些異動。

  • YouTube Reporting API 總覽的報表特性部分已更新，異動如下：

    • 說明文件現在指出，報表產生後 180 天內可供 API 用戶端下載。先前說明文件指出，報表可提供 API 要求傳送日期前最多六個月的資料。

    • 說明文件已更新，反映 API 現在會為沒有資料的日子產生可下載的報表。這些報表會包含標題列，但不會包含其他資料。

  • YouTube Reporting API 即將支援一組自動產生、由系統管理的報表，其中包含廣告收益資料或 YouTube Red 訂閱收益資料。內容擁有者只要能存取 YouTube 創作者工作室中可手動下載的收益報表，就能查看這些報表。因此，新的 API 功能將提供程式輔助方式存取該資料。

    為因應系統管理報表功能上線，我們將推出下列 API 異動：

    • job 資源的新 systemManaged 屬性會指出資源是否描述產生系統管理報表的工作。YouTube 會自動為 YouTube 內容擁有者產生系統管理的報表，內容擁有者無法修改或刪除建立這些報表的工作。

    • jobs.list 方法的新 includeSystemManaged 參數會指出 API 回應是否應包含系統管理報表的工作。參數的預設值為 false。

    • jobs.reports.list 方法的新 startTimeAtOrAfter 參數表示，只有在報表中的最早資料日期等於或晚於指定日期時，API 回應才應包含報表。同樣地，startTimeBefore 參數表示只有在報表中的最早資料早於指定日期時，API 回應才應包含報表。

      與方法 createdAfter 參數 (與報表建立時間有關) 不同，新參數與報表中的資料有關。

    • reportType 資源的新 systemManaged 屬性會指出資源是否描述系統管理的報表。

    • reportTypes.list 方法的新 includeSystemManaged 參數會指出 API 回應是否應包含系統管理的報表。參數的預設值為 false。

2016 年 3 月 28 日

YouTube Reporting API 和 YouTube Analytics API 現在會傳回多個額外分享服務的觀看統計資料。

  • 在 YouTube Reporting API 中，sharing_service 維度支援下列新值：
    • 82：iOS 系統活動對話方塊
    • 83：Google Inbox
    • 84：Android Messenger
  • 在 YouTube Analytics API 中，sharingService 維度支援下列新值：
    • ANDROID_MESSENGER：Android Messenger
    • INBOX：Google Inbox
    • IOS_SYSTEM_ACTIVITY_DIALOG：iOS 系統活動對話方塊

2016 年 3 月 16 日

這項更新包含下列變更，會影響 YouTube Reporting API 和 YouTube Analytics API：

YouTube Reporting API

  • playback_location_type 維度支援兩個新的維度值：
    • 7：資料與 YouTube 首頁或主畫面、使用者訂閱頻道動態消息，或其他 YouTube 瀏覽功能中的觀看次數有關。
    • 8：資料與直接在 YouTube 搜尋結果網頁上觀看的影片有關。
  • traffic_source_type 維度現在支援 18 做為維度值。這個值代表影片觀看次數來自列出播放清單中所有影片的頁面。這個來源與來源類型「14」不同，後者表示觀看次數是在影片做為播放清單的一部分播放時產生。

YouTube Analytics API

  • insightPlaybackLocationType 維度支援兩個新的維度值：
    • BROWSE：資料與 YouTube 首頁或主畫面、使用者訂閱頻道動態消息，或其他 YouTube 瀏覽功能中的觀看次數有關。
    • SEARCH：資料與直接在 YouTube 搜尋結果網頁上觀看的影片有關。
  • insightTrafficSourceType 維度現在支援 YT_PLAYLIST_PAGE 做為維度值。這個值代表影片觀看次數來自列出播放清單中所有影片的頁面。這個來源與 PLAYLIST 來源類型不同，後者表示觀看次數是在影片做為播放清單的一部分播放時產生。

2016 年 2 月 8 日

YouTube Analytics API 支援的指標清單已更新，因此資訊卡指標不再列為該 API 支援的指標。(該 API 的報表皆未記錄為支援任何資訊卡指標)。

請注意，您仍可使用 YouTube Reporting API 擷取資訊卡指標，該 API 支援多種頻道和內容擁有者報表的指標。

2016 年 1 月 6 日

YouTube Reporting API 和 YouTube Analytics API 現在會特別識別透過 Chromecast 裝置產生的觀看次數。

  • 在 YouTube Reporting API 中，operating_system 維度會使用 21 值來識別透過 Chromecast 產生的觀看次數。
  • 在 YouTube Analytics API 中，operatingSystem 維度會使用 CHROMECAST 值來識別透過 Chromecast 產生的觀看次數。

2015 年 12 月 21 日

在說明文件中，annotation_clickable_impressions 和 annotation_closable_impressions 指標的名稱已更新，與報表中傳回的名稱一致。先前，名稱記錄為 clickable_annotation_impressions 和 closable_annotation_impressions。

2015 年 12 月 18 日

根據歐盟法律規定，您必須向歐盟境內的使用者揭露特定資訊，並徵得同意聲明。因此，對於歐盟地區的使用者，您必須遵守《歐盟地區使用者同意授權政策》。我們已在《YouTube API 服務條款》中新增這項規定的通知。

2015 年 12 月 15 日

本次更新包含下列異動，全部都會影響 YouTube Analytics API：

  • YouTube Analytics API 現在支援三種新的播放詳細資料維度，可用於各種頻道和內容擁有者報表：

    • liveOrOnDemand：這個維度會指出報表中的資料是否描述現場直播期間發生的使用者活動。
    • subscribedStatus：這項維度會指出資料中的使用者活動指標，是否與訂閱影片或播放清單所屬頻道的觀眾相關。
    • youtubeProduct：這項維度會識別發生使用者活動的 YouTube 資源。可能的值包括 YouTube 核心網站 (或 YouTube 應用程式)、YouTube Gaming 和 YouTube Kids。

    說明文件已更新，列出頻道和內容擁有者可用的新播放詳細報表。此外，許多其他報表也已更新，指出可視需要使用一或多個這類維度，做為報表中的維度和/或篩選器。

  • 我們調整了報表說明表格的格式，方便您找出可擷取各報表的有效維度、指標和篩選器組合。下表說明頻道的「裝置類型」報表，並顯示新格式：

    屬性 值
    尺寸：
    必填 deviceType
    使用 0 或以上 day、liveOrOnDemand、subscribedStatus、youtubeProduct
    指標：
    使用 1 個以上 views、estimatedMinutesWatched
    篩選器：
    使用 0 或 1 country、province、continent、subContinent
    使用 0 或 1 video、group
    使用 0 或以上 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct

    如要瞭解必要和選用欄位的術語，請參閱頻道和內容擁有者報表的說明文件。

  • 現在，如果 API 使用者無法從支援多個值的篩選器 (video、playlist 和 channel) 擷取資料，YouTube Analytics API 會自動捨棄實體。先前，如果 API 使用者無法存取至少一個指定項目的資料，API 伺服器只會傳回錯誤。

    舉例來說，假設使用者提交 API 要求，其中 video 篩選器列出 20 個影片 ID。使用者擁有其中 18 部影片。不過，其中一個影片 ID 屬於其他頻道擁有的影片，另一個 ID 則屬於已刪除的影片，因此不再存在。在這種情況下，API 伺服器不會傳回錯誤，而是會捨棄使用者無法存取的兩部影片，並在 API 回應中包含 API 使用者擁有的 18 部影片資料。

  • 如果要求的 YouTube 數據分析group沒有資料，API 現在會傳回空白資料集，而非錯誤。

  • 如果您嘗試將實體加入群組，但沒有該實體的存取權，YouTube Analytics API 的 groupItems.insert 方法現在會傳回未授權 (403 HTTP 回應代碼) 錯誤。在過去，API 會允許您將實體新增至群組，但之後嘗試擷取該群組的報表資料時，會傳回未授權錯誤。

  • YouTube Analytics API 的 groups.list 方法現在支援分頁。如果 API 回應未包含所有可用群組，回應的 nextPageToken 參數會指定權杖，可用於擷取下一頁結果。將方法的 pageToken 參數設為該值，即可擷取其他結果。

2015 年 11 月 10 日

這次更新的修改如下：

2015 年 10 月 29 日

這次更新的修改如下：

  • YouTube Reporting API 的 date 維度說明文件已修正，日期會參照太平洋時間 (UTC-8) 午夜 12:00 開始的 24 小時。先前的文件指出，日期是從凌晨 12:00 (格林威治標準時間) 開始。

    此外，YouTube Analytics API 說明文件也已更新，註明所有與日期相關的維度 (day、7DayTotals、30DayTotals 和 month) 都是指太平洋時間 (UTC-8) 凌晨 12:00 開始的日期。

  • YouTube Reporting API 的 jobs.reports.list() 方法現在支援 createdAfter 查詢參數。如果指定這項參數，API 回應只會列出在指定日期和時間之後建立的報表，包括含有回填資料的新報表。請注意，參數值與報表建立時間有關，與傳回資料的相關日期無關。

    參數值是採用 RFC3339 UTC「Zulu」格式的時間戳記，精確度可達微秒。範例："2015-10-02T15:01:23.045678Z"。

    YouTube Reporting API 最佳做法也已更新，說明如何使用 createdAfter 參數，避免重複處理同一份報表。

  • job 資源的 createTime 屬性，以及 report 資源的 startTime、endTime 和 createTime 屬性定義皆已修正，註明屬性值精確到微秒，而非奈秒。此外，所有定義現在都能準確反映屬性值為時間戳記。

2015 年 10 月 8 日

這次更新的修改如下：

  • YouTube Analytics API 的 sharingService 維度說明文件已更新，納入可能的維度值清單。清單中包含多項新支援的服務。

    YouTube Reporting API 的 sharing_service 維度定義也已更新，列出新支援的值。大於 59 的列舉值是清單中的新值。

2015 年 9 月 24 日

這次更新的修改如下：

  • 新的 YouTube Reporting API 可擷取大量資料報表，內含頻道或內容擁有者的 YouTube 數據分析資料。這類應用程式可匯入大型資料集，並提供篩選、排序及挖掘資料的工具。

    每份 YouTube Reporting API 報表都包含一組預先定義的維度和指標。(YouTube Analytics API 報表也會使用指標和維度)。在報表中，每列資料都有不重複的維度值組合。你可以根據維度值匯總各列資料，計算個別影片、國家/地區、直播影片、訂閱使用者等項目的指標。

    你可以使用 API 安排報表工作，每項工作都會指定 YouTube 應產生的報表。設定工作後，YouTube 會產生每日報表，供您非同步下載。每份報表都包含不重複的 24 小時資料。

  • YouTube Analytics API 和 YouTube Reporting API 是不同的 API，但開發人員都能用來擷取 YouTube 數據分析資料。由於這兩個 API 都能存取類似的資料集，因此我們將這兩個 API 的說明文件合併為一份。

    • 說明文件集中的「指南」分頁包含這兩個 API 的通用資訊，包括授權 API 要求的操作說明。
    • 「大量報表」分頁包含 YouTube Reporting API 專用的參考文件和其他內容。
    • 「指定查詢」分頁包含 YouTube Analytics API 專用的參考文件和其他內容。
    • 「Samples」(範例) 分頁會列出這兩個 API 的程式碼範例。
    • 「工具」分頁列出其他可用資源，協助開發人員導入這兩個 API。

2015 年 8 月 20 日

這次更新的修改如下：

  • 我們重新調整了 API 說明文件的結構，讓 API 更容易理解。因此，這些變更並非新功能：

    • 說明文件現在包含一個列出所有可用頻道報表的頁面，以及另一個列出所有可用內容擁有者報表的頁面。舊版說明文件將頻道影片報表、頻道播放清單報表等內容分開在不同頁面。

    • 新的資料模型總覽旨在更清楚地介紹 API 的運作方式。具體來說，本文旨在進一步說明 YouTube 如何使用指標、維度和篩選條件來計算報表值。

    • 用於擷取報表的 API reports.query 方法，現在會另外記錄。該頁面的資訊先前位於其他頁面。新頁面可協助您更輕鬆地找出需要傳送的資訊，以便擷取報表。

2015 年 7 月 22 日

這項更新包含多項異動，且僅適用於內容擁有者：

  • 新的adEarnings指標包含所有 Google 售出廣告來源的預估總收益 (淨收益)。這不是核心指標。只要報表支援 earnings 指標，API 就會支援 adEarnings 指標。

    此外，我們也修正了 earnings 指標的定義，反映其值包含所有 Google 銷售廣告來源和非廣告來源的預估總收益。先前，定義誤指這項指標僅包含廣告來源的收益。

  • primaryAdGrossRevenue 指標已淘汰。請改用 grossRevenue 指標擷取收益資料。

  • 除了已淘汰的 primaryAdGrossRevenue 指標外，廣告成效報表也不再支援 monetizedPlaybacks 和 playbackBasedCpm 指標。不過，部分影片報表仍支援這些指標。

2015 年 6 月 1 日

這次更新的修改如下：

  • API 現在支援兩項新的影片報表指標：videosAddedToPlaylists 和 videosRemovedFromPlaylists。頻道和內容擁有者的影片報表清單均已更新，可識別支援新指標的報表。

    • videosAddedToPlaylists：查詢範圍內的影片加入任何 YouTube 播放清單的次數。這些影片可能已加入影片擁有者的播放清單，或加入其他頻道的播放清單。
    • videosRemovedFromPlaylists：查詢範圍內的影片從任何 YouTube 播放清單中移除的次數。影片可能已從擁有者的播放清單或其他頻道的播放清單中移除。

    這兩項指標都包含「稍後觀看」等預設播放清單。不過，系統不會計入自動加入影片的播放清單，例如頻道的上傳播放清單或使用者的觀看記錄。另請注意，這些指標反映的是新增和刪除的絕對數量。因此，如果使用者將影片加入播放清單，然後移除，接著再次加入，指標會顯示影片已加入兩個播放清單，並從一個播放清單中移除。

    系統可提供 2014 年 10 月 1 日起的指標資料。

2015 年 3 月 31 日

這次更新的修改如下：

2015 年 3 月 16 日

這次更新的修改如下：

  • 新的 currency 參數可讓您擷取美元 (USD) 以外幣別的收益指標。設定參數後，API 會將 earnings、grossRevenue、playbackBasedCpm 和 impressionBasedCpm 指標的值轉換為指定幣別。傳回的值是根據每日變動的匯率計算而得的預估值。

    參數值是三個字母組成的 ISO 4217 貨幣代碼。預設值為 USD。參數定義包含支援的貨幣代碼清單。

2015 年 2 月 25 日

這次更新的修改如下：

  • 現在，您可以使用 API 建立及管理 YouTube 數據分析群組，以及擷取這些群組的報表資料。

    • 建立及管理群組

      本次更新推出 group 和 groupItem 資源，可用於建立及管理群組。

      • group 資源代表 Analytics 群組，也就是最多 200 個頻道、影片、播放清單或資產的自訂集合。API 支援這項資源的 list、insert、update 和 delete 方法。
      • groupItem 資源代表 Analytics 群組中的項目。API 支援這項資源的 list、insert 和 delete 方法。

      舉例來說，您可以使用 groups.insert 方法建立群組，然後使用 groupItems.insert 方法將項目新增至該群組。

    • 擷取群組的報表資料

      維度說明文件已更新，納入 group 維度，可用於篩選多種頻道報表和內容擁有者報表。使用 group 篩選器時，API 會傳回該群組中所有項目的資料。請注意，API 目前不支援為素材資源群組建立報表。

    如要進一步瞭解 YouTube 數據分析群組，請前往 YouTube 說明中心。

2015 年 2 月 13 日

這次更新的修改如下：

  • API 不再支援 show 維度。

2014 年 8 月 28 日

這次更新的修改如下：

  • 現在，當 video、playlist、channel 和 show 維度做為篩選條件時，API 支援為這些維度指定多個值。如要指定多個值，請將 filters 參數值設為以半形逗號分隔的清單，列出要篩選 API 回應的影片、播放清單、頻道或節目 ID。參數值最多可指定 200 個 ID。

    如果您為同一個篩選器指定多個值，也可以將該篩選器新增至您為要求指定的維度清單。即使篩選器未列為特定報表支援的維度，也適用這項規則。如果您將篩選器加入維度清單，API 也會使用篩選器值將結果分組。

    如需這項功能的完整詳細資料，請參閱 filters 參數定義。

2014 年 7 月 16 日

這次更新的修改如下：

  • 現在，只要將 ids 參數的值設為 channel==MINE，即可在擷取頻道報表時，擷取已驗證使用者的頻道資料。(您仍可將 ids 參數設為 channel==CHANNEL_ID，擷取指定頻道的資料)。

  • API 現在支援播放清單報表，其中包含與播放清單中影片觀看次數相關的統計資料。播放清單報表適用於頻道和內容擁有者。

    所有播放清單報表都支援 views 和 estimatedMinutesWatched 指標，部分報表也支援 averageViewDuration 指標。

    此外，所有播放清單報表都支援下列新指標。請注意，這些指標只會反映在網頁上發生的播放清單觀看次數。

    擷取播放清單報表的所有要求都必須使用 isCurated 篩選器，且必須設為 1 (isCurated==1)。

  • API 現在支援觀眾續看率報表。這份報表會評估影片留住觀眾的能力。報表的新elapsedVideoTimeRatio維度會評估對應指標值的影片播放時間：

    • audienceWatchRatio 指標會顯示在影片特定時間點觀看的觀眾絕對比率。計算方式是將影片某個片段的觀看次數，與影片的總觀看次數進行比較。

      請注意，在特定影片觀看中，影片的某個部分可能會觀看多次 (或完全不觀看)。舉例來說，如果使用者多次倒轉並觀看影片的同一部分，則該部分影片的絕對比率可能會大於 1。

    • relativeRetentionPerformance指標會顯示與所有長度相近的 YouTube 影片相比，你的影片在播放期間留住觀眾的成效。0 代表影片的觀眾續看率低於其他長度相近的影片，1 則代表影片的觀眾續看率高於其他長度相近的影片。中間值為 0.5，表示長度相近的影片中，有一半的觀眾續看率較高，另一半則較低。

    你也可以使用 audienceType 篩選器，讓報表只傳回與自然觀看、TrueView 串流內廣告觀看或 TrueView 影片探索廣告觀看相關的資料。(自然觀看次數是使用者主動觀看而直接產生的觀看次數，例如搜尋影片或點選推薦影片)。

  • API 支援多項與註解相關的新指標。下列指標可透過先前支援 annotationClickThroughRate 和 annotationCloseRate 指標的任何報表擷取。

    所有新指標都是核心指標，並受廢止政策規範。不過請注意，新指標的資料是從 2013 年 7 月 16 日開始提供。(annotationClickThroughRate 和 annotationCloseRate 指標的資料自 2012 年 6 月 10 日起提供)。

  • GOOGLE_SEARCH 不再回報為 insightTrafficSourceType 維度的獨立值。現在，來自 Google 搜尋結果的參照連結網址會歸因於EXT_URL流量來源類型。因此，也無法再擷取將 insightTrafficSourceType 篩選器設為 GOOGLE_SEARCH 的 insightTrafficSourceDetail 報表。

2014 年 1 月 31 日

這次更新的修改如下：

2014 年 1 月 16 日

這次更新的修改如下：

  • 範例要求文件經過重新設計，採用與近期發布的頻道和內容擁有者報表類似的分頁格式，將範例分門別類。新設計將範例分為以下類別：

    • 基本統計資料
    • 時間型
    • 地理區域
    • 播放位置
    • 流量來源
    • 裝置/作業系統
    • 客層
    • 社群媒體
    • 收益/廣告 (僅限內容擁有者報表)

  • 要求範例文件現在包含新範例，說明如何在頻道報表或內容擁有者報表中擷取特定省份的資料。

    • 美國各州和華盛頓特區的特定省份指標：這份報表會擷取頻道影片的觀看次數和其他統計資料，並依省份細分。資料涵蓋美國各州和華盛頓特區。這個範例使用 province 維度，並使用 filters 參數限制回應，只納入美國的結果。

    • 加州觀眾客層 (年齡層和性別)：這份報表會擷取加州觀眾的年齡層和性別統計資料，這些觀眾曾觀看頻道影片，或觀看內容擁有者聲明擁有權的內容 (適用於內容擁有者報表)。這個範例使用 filters 參數，確保回應只包含特定省份的資料。

  • province 維度的定義已更新，指出當 dimensions 參數值包含 province 時，要求也必須在 filters 參數值中加入 country==US，將資料限制在美國。

2014 年 1 月 6 日

這次更新的修改如下：

  • 我們重新設計了列出支援頻道和內容擁有者報表的文件。我們不會提供列出所有可能報表的表格，而是將報表分門別類：

    • 基本統計資料
    • 時間型
    • 地理區域
    • 播放位置
    • 流量來源
    • 裝置/作業系統
    • 客層
    • 社群媒體
    • 熱門影片

    每份文件都會以分頁清單的形式顯示這些類別，您可以點選任何分頁，查看該類別支援的報表。

  • API 現在支援三個新的地理維度：province、continent 和 subContinent。

    • province 維度可讓您擷取美國各州和哥倫比亞特區的統計資料。API 支援這個維度的兩種用途：

      • 這個 API 支援兩種報表，可依州別細分統計資料。頻道和內容擁有者皆可使用這兩份報表。

        • 核心數據報表提供多項統計資料，包括觀看次數和預估觀看時間。
        • 時間報表提供相同的統計資料，但會按日、7 天、30 天或月匯總資料。

      • 您可以使用 filters 查詢參數，限制報表只包含特定州的統計資料。有多種報表支援這類篩選功能，包括地區報表、播放位置報表、流量來源報表、裝置報表、作業系統報表、客層報表和熱門影片報表。

    • continent 維度會指定聯合國 (UN) 統計區域代碼，用於識別洲別。這個維度只能做為篩選條件使用。

    • subContinent 維度會指定聯合國 (UN) 統計區域代碼，用於識別洲別的子區域。這個維度也只能做為篩選條件使用。

      由於每個子區域只與一個洲相關聯，因此使用 subContinent 篩選器時，不需要同時使用 continent 篩選器。(事實上，如果要求同時使用這兩個維度，API 會傳回錯誤)。

  • 我們已修正說明文件，insightTrafficSourceDetail 維度不會再將 insightTrafficSourceType 值 PROMOTED 視為有效的篩選器值。

2013 年 9 月 30 日

這次更新的修改如下：

  • YouTube Analytics API 現已適用《服務條款》中的廢止政策。不過，API 的非核心維度和非核心指標不適用「廢止政策」。維度和指標頁面已更新，列出核心維度和核心指標。此外，這些頁面上的定義也已更新，明確指出核心維度和指標。

  • API 現在支援 EXTERNAL_APP 做為 insightPlaybackLocationType 維度的值。配合這項更新，自 2013 年 9 月 10 日起，播放次數不再歸類為MOBILE播放次數，但該日期之前發生的行動播放次數仍會歸類為該值。

    這項更新推出後，系統會根據播放發生的應用程式類型，將行動播放次數歸類為 WATCH、EMBEDDED 或 EXTERNAL_APP 播放次數。

  • API 現在支援 PLAYLIST 做為 insightTrafficSourceType 維度的值。這個值代表影片觀看次數來自播放清單。以往，這些觀看次數會歸類到該維度的 YT_OTHER_PAGE 類別。

2013 年 7 月 16 日

這次更新的修改如下：

  • API 現在支援依多個維度和指標排序報表。範例要求文件包含新的範例「依多個維度/指標排序要求」，示範這項功能。這項要求會擷取流量來源資料，且 sort 參數值為 day,-views。結果會依時間順序排列，但每天的結果集中，第一列包含產生最多觀看次數的流量來源資料，第二列包含產生次多觀看次數的來源資料，依此類推。

  • API 現在支援 deviceType 和 operatingSystem 兩項新維度，可用於擷取觀眾觀看影片時使用的裝置資料。API 支援使用其中一個或兩個維度的報表。

    • deviceType 報表可讓你擷取不同類型裝置 (包括電腦、行動裝置和平板電腦) 的觀看次數和預估觀看時間。您也可以使用 operatingSystem 篩選器，限制裝置類型報表只包含執行特定作業系統 (例如 Android 或 iOS) 的裝置統計資料。

    • operatingSystem 報表可讓你擷取不同作業系統 (例如 Android、iOS、Linux 等) 的觀看次數和預估觀看時間。您也可以使用 deviceType 篩選器，限制作業系統報表只包含特定類型裝置 (例如行動裝置或平板電腦) 的統計資料。

    頻道和內容擁有者可查看新的裝置類型和作業系統報表。

  • 要求範例文件已更新，納入三份頻道裝置報表和三份內容擁有者裝置報表。

  • insightPlaybackLocationType 維度可能會傳回 YT_OTHER 值，代表未歸類至該維度其他值的觀看次數。

2013 年 5 月 23 日

這次更新的修改如下：

2013 年 5 月 10 日

這次更新的修改如下：

2013 年 5 月 6 日

這次更新的修改如下：

  • API 現在支援擷取觀看時間指標 (estimatedMinutesWatched、averageViewDuration 和 averageViewPercentage)，以及其他指標，包括觀看指標、參與度指標、收益指標和廣告成效指標。

    可用的頻道報表和內容擁有者報表清單已更新，反映這項異動。(由於觀看時間指標可透過其他列出的報表擷取，因此清單實際上已縮短)。

    API 要求範例文件也已更新。

  • 使用「insightPlaybackLocationDetail」和「insightTrafficSourceDetail」維度的報表已進行下列強化：

    • 現在支援選用的 country 篩選器。

    • 內容擁有者現在可以使用下列任一新 filter 組合擷取這些報表。請注意，所有這些組合也支援選用的 country 篩選器。

      • 播放位置詳細資料

        • channel,insightPlaybackLocationType==EMBEDDED
        • show,insightPlaybackLocationType==EMBEDDED
        • claimedStatus,insightPlaybackLocationType==EMBEDDED
        • uploaderType,insightPlaybackLocationType==EMBEDDED
        • uploaderType,claimedStatus,insightPlaybackLocationType==EMBEDDED

      • 流量來源詳細資料

        • channel,insightTrafficSourceType
        • show,insightTrafficSourceType
        • claimedStatus,insightTrafficSourceType
        • uploaderType,insightTrafficSourceType
        • uploaderType,claimedStatus,insightTrafficSourceType

2013 年 5 月 3 日

這次更新的修改如下：

  • 新的範例 API 要求文件提供範例，示範如何使用 YouTube Analytics API 擷取多種不同類型的報表。每個範例都會簡短說明要求擷取的報表，然後顯示要求的維度、指標、篩選器和排序參數。

  • insightTrafficSourceType 維度現在支援 SUBSCRIBER 做為有效值。這個值代表來自 YouTube 首頁動態消息或 YouTube 訂閱功能的影片觀看次數。如果根據這項流量來源篩選，insightTrafficSourceDetail 欄位會指定首頁動態消息或觀看次數來源的其他頁面。

2013 年 3 月 28 日

這次更新的修改如下：

2013 年 3 月 21 日

這次更新的修改如下：

  • API 現已支援收益和廣告成效指標，以及新的廣告成效報表。只有加入 YouTube 合作夥伴計畫的 YouTube 內容合作夥伴，才能查看這些指標和報表。

    • 新支援的報表支援依播放次數計算的廣告成效指標，以及依曝光次數計算的廣告成效指標。如要進一步瞭解廣告成效報表，請參閱內容擁有者報表說明文件。

    • 以下列出新支援的指標。內容擁有者報表清單已更新，可識別支援這些指標的報表，包括兩份新報表。

      • earnings：所有 Google 售出廣告來源的預估總收益。
      • grossRevenue：Google 或 DoubleClick 合作夥伴的預估總收益。
      • primaryAdGrossRevenue：預估總收益，依報表涵蓋的影片播放主要廣告類型加總及分類，來源為 Google 或 DoubleClick 合作夥伴。
      • monetizedPlaybacks：至少顯示一次廣告曝光的播放次數。
      • playbackBasedCpm：每千次播放的預估總收益。
      • impressions：已驗證的廣告曝光次數。
      • impressionBasedCpm：每千次廣告曝光的預估總收益。

      注意：如需完整詳細資料，請參閱指標定義。

    • 凡是擷取收益或廣告成效指標的要求，都必須傳送授權權杖，使用新的 https://www.googleapis.com/auth/yt-analytics-monetary.readonly 範圍授予存取權。

  • 我們重新整理了 API 說明文件，在不同頁面中說明各種報表。因此，我們現在提供個別頁面，說明不同類型的頻道報表和內容擁有者報表。

2013 年 2 月 4 日

這次更新的修改如下：

  • API 參考指南現在提供範例一節，其中包含程式碼範例，示範如何使用 Java、JavaScript、Python 和 Ruby 用戶端程式庫呼叫 API。JavaScript 程式碼範例與範例應用程式說明文件中詳細討論的範例相同。

2012 年 11 月 14 日

這次更新的修改如下：

  • API 參考指南現在提供 APIs Explorer，可讓您呼叫 API、查看 API 要求，並在回應中擷取實際資料。

  • 這個 API 支援多種頻道和內容擁有者適用的新報表，詳情請見下方說明。每份報表都提供頻道報表或內容擁有者報表。維度和指標頁面也已相應更新。

    • 播放位置報表會列出不同類型網頁或應用程式的影片觀看次數。

    • 播放位置詳細報表會列出為特定影片帶來最多觀看次數的嵌入式播放器。這份報表會找出與熱門嵌入播放器相關聯的網址，提供比播放位置報表更精細的資料。

    • 流量來源報表會列出不同類型參照網址帶來的影片觀看次數。

    • 流量來源詳細報表會列出為指定影片和指定流量來源類型帶來最多觀看次數的參照網址。舉例來說，這份報表會顯示哪些相關影片為特定影片帶來最多流量。這份報表支援多種流量來源。

    • 觀看時間報表會顯示觀眾觀看內容的時間長度。報表可匯總特定時間範圍 (例如當天、過去 7 天、過去 30 天等) 或國家/地區的資料。如果報表是依日期或國家/地區匯總資料，則還可以指定每部影片的平均觀看長度，以及使用者觀看每部影片的平均百分比。

2012 年 10 月 2 日

這次更新的修改如下：

  • YouTube Analytics API 現已開放所有開發人員使用。您可以在 APIs console 的「Services」(服務) 面板中，為專案啟用 API，不必先申請存取權。

  • 新的「入門指南」專區概述了建構使用 YouTube Analytics API 的應用程式時，所需具備的先決條件和基本步驟。

2012 年 9 月 12 日

這次更新的修改如下：

  • 新的「瞭解配額用量」一節提供最佳化 API 配額用量的指南。API 伺服器會計算每項要求的查詢費用，並從 API 用量配額中扣除。不同類型的報表，查詢費用可能會有很大的差異，因此請務必有效率地使用配額，並確保應用程式只要求實際需要的指標和資料。

  • 「時間維度」一節已更新，說明這些維度代表 Analytics 報表應根據時間範圍匯總資料。API 現在支援下列額外的時間維度：

    • 7DayTotals：報表中的資料會匯總，因此每列會包含七天內的資料。
    • 30DayTotals：報表中的資料會匯總，因此每一列都包含 30 天內的資料。
    • month：報表中的資料會依日曆月彙整。

    同樣地，「可用的報表」一節也已更新，反映 API 支援使用這些維度的報表。

  • 「報表實體維度」一節已更新，說明擷取內容擁有者報表的 API 要求，必須使用下列其中一個維度 (video、channel 或 show)，或 claimedStatus 和 uploaderType 維度的支援組合來篩選資料。

  • API 現在支援兩種新的熱門影片報表排序選項。這些報表分為頻道報表和內容擁有者報表，包含各國家/地區的指標 (觀看次數、留言數、喜歡次數等)，並依影片細分這些指標。現在，你可以根據在影片觀賞頁面訂閱或取消訂閱頻道的使用者人數，排序這些報表。

  • 我們更新了subscribersGained和subscribersLost指標的定義，說明頻道可透過多個位置獲得或失去訂閱者，包括影片觀賞頁面、頻道頁面，以及 YouTube 首頁顯示的導覽面板。如果這些指標出現在影片專屬報表中，則只會包含指定影片觀賞頁面的統計資料。