修訂記錄

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

2025 年 6 月 24 日

如 2025 年 3 月 26 日公告所述，我們將更新 Bulk Reports API，以配合 Shorts 觀看次數的新異動。變更內容如下：

  • 系統已為每個包含檢視畫面的報表 (大多數報表) 建立新版報表。每個受影響的報表版本都會遞增 1，例如從版本 a2 變成版本 a3。
  • 現在 Shorts 觀看次數會以 Shorts 開始播放或重播的次數計算。影片則沒有任何異動。
  • 更新後的報表會新增 engaged_views 資料欄，顯示以舊方法計算的觀看次數。

這些異動將於 2025 年 6 月 30 日生效，適用於大量報表 API。請務必據此調整報表處理方式。

您可以在 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 日公告所述，Targeted Queries API 將配合新的 Shorts 觀看次數計算方式異動進行更新：

  • 現在 Shorts 的 views 會計算 Shorts 開始播放或重播的次數。
  • 新指標「engagedViews」會沿用先前的觀看次數計算方式。engagedViews會與 views 一併顯示在所有報表中。

這些異動將於 2025 年 4 月 30 日生效，適用於目標查詢 API。請務必據此調整查詢。

請查看這份修訂記錄，瞭解 Bulk Reports API 的變更內容和時間。

2025 年 4 月 22 日

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

2025 年 3 月 26 日

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

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

YouTube 數據分析 (指定查詢) 和 Reporting (大量報表) API 將更新，異動如下：

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

目標查詢將於 4 月 30 日前更新，大量報表則於 6 月 30 日前更新。在此之前，觀看次數仍會採用舊的計算方式。Shorts 和頻道觀看次數與 YouTube 工作室中的數據分析不符。

此外，我們先前宣布的每日索賠 (1.0 版) 報表淘汰作業將延後。

請查看這個修訂記錄，瞭解 API 的異動時間。

2025 年 3 月 3 日

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

注意：這是淘汰公告。

合作夥伴已無法使用每日著作權聲明 (1.0 版) 報表。2025 年 4 月 30 日後，系統將不再支援這項功能。因此，該報表的定義也已更新。請改用最新的每日著作權聲明報表。

2024 年 11 月 15 日

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

YouTube 數據分析 (目標查詢) 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 指標是匯總的影片指標，會指定內容擁有者播放清單中影片的總觀看次數，無論這些觀看次數是否發生在播放清單環境中。累計總觀看次數只會計入播放清單所屬頻道，以及與該頻道相關聯的內容擁有者所擁有的影片。

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

  • 在每個播放清單報表的內容擁有者報表說明文件中，現在都包含表格，顯示該報表支援的指標，具體取決於 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 指標是匯總影片指標，會指定頻道播放清單中影片的總觀看次數，無論這些觀看次數是否發生在播放清單環境中。匯總總計只會納入播放清單所屬頻道擁有的影片觀看次數。

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

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

2023 年 12 月 4 日

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

2022 年 12 月 15 日

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

  • 新報表會依城市顯示使用者活動。這份報表適用於頻道和內容擁有者。這份報表包含新的 city 維度，可識別 YouTube 估計的使用者活動發生城市。

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

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

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

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

2022 年 8 月 26 日

YouTube Analytics (指定查詢) 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 Analytics (指定查詢) API 和 YouTube Reporting (大量報表) API。

2022 年 2 月 2 日

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

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

2020 年 9 月 23 日

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

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

2020 年 7 月 20 日

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

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

2020 年 2 月 13 日

本次更新包含下列與 YouTube Analytics (指定查詢) API 和 YouTube Reporting (大量報表) API 相關的異動。如要進一步瞭解這些異動，請參閱 YouTube 說明中心。

在兩個 API 中，通知的可能流量來源詳細資料值組合都會變更。 在目標查詢中，通知會回報為 insightTrafficSourceType=NOTIFICATION。在大量報表中，通知會以 traffic_source_type=17 形式回報。

新值會將先前以 uploaded 回報的上傳影片和直播相關通知，分成兩類：

  • uploaded_push - 影片上傳時，系統向訂閱者傳送推播通知所帶來的觀看次數
  • uploaded_other - 來自非推播通知的觀看次數，例如在影片上傳時傳送給訂閱者的電子郵件或收件匣通知。

這些值是從 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 維度，並彙整或衍生七天或 30 天期間的資料，重現部分維度資料。例如：

    • 如要計算七天內的觀看次數，請加總這段期間每天的觀看次數。
    • 如要計算七天期間的 viewerPercentage，請將每天的觀看次數乘以當天的 viewerPercentage，即可得出當天觀看影片時登入的觀眾人數。接著，將整個期間的登入觀眾人數加總，然後除以該期間的總觀看次數，即可得出整個期間的觀眾百分比。
    • 由於同一位觀眾可能在不同天計為不重複觀眾，因此無法計算七天期間的不重複觀眾人數。不過，您或許可以改用 month 維度，而非 30DayTotals 維度，藉此推斷 30 天內的不重複觀眾人數資料。請注意，month 維度是指日曆月，而 30DayTotals 維度會根據指定的開始和結束日期計算 30 天的週期。

2019 年 6 月 27 日

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

  • 由於 API 第 1 版已全面淘汰，因此我們更新了說明文件，移除了該版本的參照內容，包括淘汰通知和遷移指南 (說明如何更新至第 2 版)。

2018 年 11 月 1 日

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

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

    請注意，我們原先於 2018 年 4 月 26 日公告這項淘汰時間表。

2018 年 9 月 17 日

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

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

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

      或

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

    新版專區也討論了 YouTube 數據分析報表可能受限的資料類型。

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

2018 年 6 月 18 日

本次更新對 YouTube Analytics (指定查詢) 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 Analytics (指定查詢) API 進行了下列變更：

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

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 天後刪除或重新整理從該 API 儲存的資源中繼資料。

  • 我們更新了「報表特徵」一節，指出即使報表資料未經過濾，如果報表包含 2018 年 6 月 1 日當天或之後的資料，就不會參照在報表產生日期前至少 30 天刪除的 YouTube 資源。

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

  • API 總覽的「回填資料」一節已更新，更清楚地將回填資料定義為取代先前傳送資料集的資料集。

2018 年 4 月 26 日

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

  • v2 API 與 v1 API 幾乎相同。不過，您可能需要更新程式碼，才能反映下列變更。如要瞭解所有變更，請參閱新的遷移指南。

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

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

    • reports.query 方法不再支援 alt、quotaUser 和 userIp 要求參數。
    • V2 API 不提供批次端點，因此無法支援由不同 API 要求組成的批次。(不過，批次可以包含對同一 API 不同方法的要求)。這項淘汰作業不只針對 YouTube Analytics API，Google 將淘汰所有 API 的全域批次端點。
    • v2 API 不支援 JSON-RPC 通訊協定，但 API v1 支援。再次提醒，這項淘汰作業不只影響 YouTube Analytics API。

  • 注意：這是淘汰公告。

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

2018 年 2 月 21 日

本次更新對 YouTube Analytics (指定查詢) 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 回應代碼。如果尚未更新應用程式，請盡快改用 estimatedRevenue 指標，而非 earnings 指標。

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 Analytics API 存取收益資料，方法與透過創作者工作室的 YouTube 數據分析存取收益資料相同：

2017 年 3 月 17 日

這次更新的修改如下：

2017 年 3 月 3 日

這次更新的修改如下：

  • YouTube Reporting API (大量報表)

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

      雖然日期通常代表 24 小時，但時鐘向前調快時代表 23 小時，向後調慢時則代表 25 小時。(先前文件指出每個日期代表一個不重複的 24 小時週期，且太平洋時間一律為 UTC-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 點 開始，到太平洋時間晚上 11 點 59 分為止的期間。太平洋時間會因一年中的時間而異，可能是 UTC-7 或 UTC-8。

      雖然日期通常代表 24 小時，但時鐘向前調快時代表 23 小時，向後調慢時則代表 25 小時。(舊版說明文件指出太平洋時間為 UTC-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 日生效的修訂版條款，本次更新也包含多份輔助文件，協助開發人員瞭解必須遵守的政策。

    如要查看完整的新文件，請參閱更新版條款的修訂記錄。此外，修訂記錄也會說明日後對更新版條款或支援文件所做的變更。您可以透過文件中的連結，訂閱列出修訂版本記錄變更的 RSS 動態消息。

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 總覽的「報表特徵」部分已更新，明確指出報表可透過 API 存取 180 天 (自報表產生當日起算)。

    先前文件指出，報表最多可提供 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。與舊版報表不同，新版報表支援 likes 和 dislikes 指標。content_owner_basic_a1

    如果您已有建立 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 訊息
  • 在 YouTube Analytics API 中，sharingService 維度支援下列新值：
    • ANDROID_MESSENGER：Android 訊息
    • 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 日

根據歐盟 (EU) 法律規定，您必須向歐盟境內的使用者揭露特定資訊，並徵得同意聲明。因此，如果使用者位於歐盟地區，您必須遵守《歐盟地區使用者同意授權政策》。我們已在《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 影片、群組
    使用 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 數據分析 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 點開始的 24 小時期間。舊版說明文件指出日期從格林威治標準時間凌晨 12 點開始。

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

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

    參數值是採用 RFC3339 世界標準時間「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 報表 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 的參考說明文件和其他內容。
    • 「範例」分頁會列出這兩個 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 資源代表數據分析群組，最多可自訂 200 個頻道、影片、播放清單或資產的集合。這個資源支援 list、insert、update 和 delete 方法。
      • groupItem 資源代表 Analytics 群組中的項目。這個資源支援 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 維度的定義已更新，指出當 province 納入 dimensions 參數值時，要求也必須在 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 數據分析 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 的「服務」面板中，為專案啟用 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 首頁上顯示的導覽。如果這些指標出現在特定影片的報表中，則只會包含指定影片觀賞頁面的統計資料。