修訂記錄

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

2023 年 12 月 4 日

YouTube 數據分析 (目標查詢) API 已更新,現在合併兩個 insightTrafficSourceType 維度值。先前,這項維度會區分隨著播放清單 (PLAYLIST) 的一部分播放的影片,以及源自播放清單內所有影片 (YT_PLAYLIST_PAGE) 的觀看次數。往後這兩種觀看次數都會與 PLAYLIST 維度值建立關聯。

2022 年 12 月 15 日

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

  • 新報表會依城市提供使用者活動。這份報表適用於頻道內容擁有者。這份報表包含新的 city 維度,指出 YouTube 推測使用者活動時所在的城市。

  • 新的 creatorContentType 維度可識別與資料列中的使用者活動指標相關聯的 YouTube 內容類型。支援的值為 LIVE_STREAMSHORTSSTORYVIDEO_ON_DEMAND

    系統支援所有頻道和內容擁有者影片報表的「creatorContentType」維度做為選用維度。

  • 現在,YouTube Analytics (分析) API 要求範例指南提供這兩種新維度的範例。

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

2022 年 8 月 26 日

YouTube Analytics (目標查詢) API 和 YouTube Reporting (大量報表) API 均支援新的流量來源詳細資料值:

2022 年 2 月 11 日

我們將於 2022 年 8 月 11 日當天或之後變更「gender」維度的有效值組合。這在 API 實作中可能與回溯不相容的變更。為配合《YouTube API 服務條款》的「回溯不相容變更」一節規定,這項異動將於六個月生效前公告。請在 2022 年 8 月 11 日前更新 API 實作項目,確保能順暢轉換至新的值組。

要進行的特定變更如下:

  • 在 YouTube 數據分析 (指定查詢) API 中,gender 維度目前支援兩個值:femalemale。自 2022 年 8 月 11 日起,該維度將支援三個值:femalemaleuser_specified
  • 在 YouTube Reporting (大量報表) API 中,「gender」維度目前支援三個值:FEMALEMALEGENDER_OTHER。2022 年 8 月 11 日起,支援的值組合將變更為 FEMALEMALEUSER_SPECIFIED

2022 年 2 月 9 日

已更新兩項指標,自 2021 年 12 月 13 日起排除循環剪輯流量。這項異動會影響 YouTube Analytics (目標查詢) API 和 YouTube Reporting (大量報表) API。

2022 年 2 月 2 日

這個 YouTube Reporting (大量報表) API 支援新的流量來源維度值,這表示觀看次數源自直播重新導向

這個流量來源類型的 traffic_source_detail 維度會指定觀眾的來源頻道 ID。

2020 年 9 月 23 日

這個 YouTube 數據分析 (指定目標查詢) API 和 YouTube Reporting (大量報表) API 都支援新的流量來源維度值,指出觀眾在 YouTube Shorts 觀看體驗中是以垂直滑動的方式參照觀眾:

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

2020 年 7 月 20 日

本次更新涵蓋兩項會影響 YouTube Analytics (目標查詢) API 的變更:

  • YouTube 數據分析報表群組的大小上限已從 200 個增加到 500 個實體。
  • reports.query 方法的 filters 參數會列出擷取 YouTube 數據分析資料時應套用的篩選器清單。這個參數支援為 videoplaylistchannel 篩選器指定多個值,且這些篩選器可指定的 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 日 (2020 年 1 月 13 日) 這個時間範圍傳回這些值。

另外提醒您,這些值不代表通知本身,而是帶來某些 YouTube 觀看次數的流量來源。舉例來說,假設報表資料列指出 views=3traffic_source_type=17 (NOTIFICATION) 和 traffic_source_detail=uploaded_push,這一列表示影片上傳時,觀眾點按傳送推播通知而產生三次觀看。

2019 年 10 月 15 日

本次更新內含下列 YouTube Analytics (目標查詢) API 相關異動:

  • 注意:這是淘汰公告,

    YouTube 即將移除對「7DayTotals」和「30DayTotals」維度的支援。在 2020 年 4 月 15 日前,您仍可使用這些維度擷取資料。上述日期當天或之後,嘗試使用「7DayTotals」或「30DayTotals」維度擷取報表時,系統會傳回錯誤。

    請注意,使用者可以使用「day」維度查詢資料,以及匯總或取得七天或 30 天期間的資料,藉此重現這些維度的部分資料。例如:

    • 在為期七天內,您可以匯總該期間每一天的觀看次數,
    • 7 天內的觀眾百分比的計算方式是將每日發生的觀看次數乘以該日的觀眾百分比,得出當天觀看影片時已記錄的觀眾人數。接著,您可以將整個時段的已登入觀眾人數除以該期間的總觀看次數,得出整段時段的觀眾百分比。
    • 系統無法計算七天內的不重複觀眾人數,因為系統可能會將同一位觀眾計為不同天的不重複觀眾。不過,您可以使用「month」維度取代「30DayTotals」維度,推斷 30 天內的不重複觀眾人數資料。請注意,month 維度是指日曆月份,30DayTotals 維度是根據指定的開始和結束日期來計算 30 天的週期。

2019 年 6 月 27 日

本次更新內含下列 YouTube Analytics (目標查詢) API 相關異動:

  • 因為 API 的第 1 版現已完全淘汰,說明文件已更新,移除對該版本的參照,包括淘汰通知和遷移指南,說明如何更新至第 2 版。

2018 年 11 月 1 日

本次更新內含下列 YouTube Analytics (目標查詢) API 相關異動:

  • 第 1 版 API 現已淘汰。如果您尚未這麼做,請盡快將您的 API 用戶端更新為使用第 2 版 API,盡量避免服務中斷。詳情請參閱遷移指南

    請注意,淘汰時程表最初是在 2018 年 4 月 26 日公告。

2018 年 9 月 17 日

本次更新內含下列 YouTube Analytics (目標查詢) API 相關異動:

  • 我們在「資料模型」總覽文件中新增「資料去識別化」一節,說明當指標未達特定門檻時,部分 YouTube 數據分析資料會受到限制。發生這種情況的原因有很多種。就實務而言,這表示如果發生以下情況,報表可能不會包含部分或全部資料:

    1. 影片或頻道在指定的時間範圍內流量有限

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

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

  • 頻道報表內容擁有者報表文件已更新,以反映 YouTube 不再支援播放位置、流量來源和裝置類型/作業系統報表,因此無法提供 redViewsestimatedRedMinutesWatched 指標。

2018 年 6 月 18 日

本次更新內含下列 YouTube Analytics (分析) API (鎖定查詢) 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 回應如何處理與已刪除資源 (例如影片、播放清單或頻道) 相關的資料。
  • 我們更新了 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 日

第 2 版 YouTube Analytics (Targeted Query) API (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,請使用駝峰式大小寫 (endDate),而不是 v2 API 中的連字號。這項變更會讓 API 中的參數名稱保持一致,因為這個 API 能夠利用各種方法建立及管理參數,並使用駝峰式大小寫。
    • v2 API 不支援傳送至 Google 全球 HTTP 批次端點 (www.googleapis.com/batch) 的批次要求。如果您在 v2 API 中傳送批次要求,請改用端點 https://youtubeanalytics.googleapis.com/v2

    此外,v2 API 不支援部分第 1 版功能:

    • reports.query 方法不再支援 altquotaUseruserIp 要求參數。
    • v2 API 並未提供批次端點,支援將要求組成不同 API 的批次。(批次可以包含對相同 API 不同方法的要求)。這項淘汰作業不僅適用於 YouTube Analytics API,因為 Google 即將淘汰所有 API 中的全域批次端點。
    • v2 API 不支援 JSON-RPC 通訊協定,但 API v1 支援這種通訊協定。再次重申,這項淘汰作業與 YouTube Analytics API 無關。

  • 注意:這是淘汰公告,

    第 1 版 API (v1) 已淘汰,將於 2018 年 10 月 31 日停止提供支援。在這之後,所有向 v1 API 發出的要求都會停止運作。因此,請務必在 2018 年 10 月 31 日前升級至 2 版 API,以免暫時無法透過此 API 存取 YouTube 數據分析資料。

2018 年 2 月 21 日

本次更新內含下列 YouTube Analytics (分析) API (鎖定查詢) API 變更:

  • 觀眾客層報表 (根據觀眾的年齡層和性別匯總觀看統計資料),不再支援「youtubeProduct」維度,用來識別使用者活動所屬的 YouTube 服務。

2018 年 1 月 18 日

這次更新的修改如下:

  • YouTube Reporting API (大量報表)

    • operating_system 維度現在支援下列值,該維度可識別發生觀看次數的裝置軟體系統:
      • 25:KaiOS
  • YouTube Analytics API (指定查詢)

2017 年 12 月 20 日

這項更新包含兩項與 YouTube Reporting API 相關的變更:

  • API 伺服器現在支援對下載報表的要求使用 gzip 壓縮。請注意,gzip 壓縮不適用於其他類型的 API 要求。啟用 gzip 壓縮功能可降低每個 API 回應所需的頻寬。雖然應用程式需要更多 CPU 時間來解壓縮 API 回應,但使用較少網路資源的好處通常遠大於該成本。

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

    Accept-Encoding: gzip

    如要進一步瞭解這項功能,請參閱 API 總覽,以及 report 資源的 downloadUrl 屬性定義。

  • 修正了 age groupgender 維度的說明文件,以顯示 API 針對這些維度傳回的實際值。請注意,這是說明文件修正內容,無法反映 API 功能或行為的變化。具體而言,下列值已變更:

    • age_group 維度的值需使用大寫字母、字詞 AGE 與年齡層的數字之間包含底線,並使用底線 (而非連字號)。因此,age13-17age18-24 等值已分別更正為 AGE_13_17AGE_18_24
    • gender」維度的值須使用大寫字母。因此,femalemalegender_other 值已更正為 FEMALEMALEGENDER_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 月 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 遊戲
      • 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 點開始,到指定日期、月份及年份,11:59 結束的期間。視當下時間而定,太平洋時間為 UTC-7 或 UTC-8。

      雖然日期通常以 24 小時為計算依據,但將時鐘往後調整的日期代表 23 小時,而將時鐘往回調整的日期則代表 25 小時。(先前說明文件指出每個日期分別代表不同的 24 小時期間,而太平洋時間一律為 UTC-8)。

      請注意,這項修正不代表實際的 API 行為變化。

    • operating_system 維度現在支援下列值,該維度可識別發生觀看次數的裝置軟體系統:
      • 22:本地化
      • 23:Firefox
      • 24:RealMedia
    • 已刪除 content_owner_basic_a1 報表類型的所有報表工作。此報表類型已於 2016 年 8 月 19 日完全淘汰,但先前產生的 content_owner_basic_a1 報表仍可從產生後的 180 天內使用。因此,部分報表最早可至 2017 年 2 月 19 日存取。不過,由於報表已不再提供,因此不需要與報表相關聯的工作。

  • YouTube Analytics API (指定查詢)

    • time periods」相關維度的說明已更正,請注意,維度值是指從太平洋時間開始,到太平洋時間指定日期/月份的晚上 11:59 結束的期間。視當下時間而定,太平洋時間為 UTC-7 或 UTC-8。

      雖然日期通常以 24 小時為計算依據,但將時鐘往後調整的日期代表 23 小時,而將時鐘往回調整的日期則代表 25 小時。(先前說明文件指出太平洋時間為世界標準時間,但未說明一天可能並非 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 變更:

    • content_owner_basic_a1」報表已完全淘汰,並從說明文件中移除。YouTube 不會再產生該類型的新報表,但自產生當日起算的 180 天內,您仍可查看先前產生的報表。

      content_owner_basic_a1 報告的取代項目為 content_owner_basic_a2 報告,如 2016 年 5 月 19 日的修訂版本記錄項目所述。

    2016 年 8 月 11 日

    這次更新的修改如下:

    • YouTube 工程與開發人員網誌上,我們新發布的《YouTube API 服務條款》(下稱「新版條款」) 針對目前的服務條款提供了內容豐富的更新內容。除了將於 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 日更新同一份文件的「報表特性」一節。
      • 為反映該報表使用「card_id」維度,「content_owner_asset_cards_a1」報表中的維度清單已經過修正。先前說明文件誤將維度名稱列為 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_a1content_owner_estimated_earnings_a1content_owner_asset_estimated_earnings_a1 報表也已經淘汰。

      如果您有任何工作需要處理,在 2016 年 9 月 22 日之後,YouTube 應該就不會再產生這些工作的新報表。所產生報表的報表在產生後的 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_percentageaudience_retention_type 屬性。目前由 API 提供的任何報表都不支援這些維度。

    2016 年 5 月 19 日

    本次更新包含以下 YouTube Reporting API 異動:

    • 這個 API 支援新版的內容擁有者使用者活動報告。新報表的報表類型 ID 為 content_owner_basic_a2。有別於舊版報表 content_owner_basic_a1,新版支援 likesdislikes 指標。

      如果您已經有建立「content_owner_basic_a1」報表的工作,您仍然需要為「content_owner_basic_a2」報表建立新工作。YouTube 不會自動將內容擁有者遷移至新版報表版本,也不會自動建立工作來產生新的報表版本。在某些實作項目中,出現未預期的新工作外觀可能是破壞性變更。

      隨著新版報表推出,content_owner_basic_a1 報表已經淘汰。如果有該報表的工作,在 2016 年 8 月 19 日之後,YouTube 就不會再產生該工作的新報表。所產生報表的報表在產生後的 180 天內仍可存取。

    • reportTypejobreport 資源都支援一個新屬性,可識別相關聯的資源是否代表已淘汰的報表類型:

      • reportType 資源的 deprecateTime 屬性會指定報表類型即將淘汰的日期和時間。這個屬性僅適用於已公告淘汰的報表,這個值代表 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 收件匣
      • 84:Android Messenger
    • 在 YouTube Analytics API 中,sharingService 維度支援下列新值:
      • ANDROID_MESSENGER:Android Messenger
      • INBOX:Google 收件匣
      • 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 擷取資訊卡指標,這項功能支援許多頻道內容擁有者報表的這些指標。

    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_impressionsannotation_closable_impressions 指標名稱已更新,現在會與報表傳回的名稱相符。先前的名稱是記錄為 clickable_annotation_impressionsclosable_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 以上的值 dayliveOrOnDemandsubscribedStatusyoutubeProduct
      指標:
      使用 1 或更多 viewestimatedMinutesWatched
      篩選器:
      請使用 0 或 1 countryprovince洲別subContinent
      請使用 0 或 1 videogroup
      請使用 0 以上的值 operatingSystemliveOrOnDemandsubscribedStatusyoutubeProduct

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

    • YouTube Analytics API 現在會自動捨棄 API 使用者無法從支援多個值的篩選器 (videoplaylistchannel) 擷取資料的實體。過去,如果 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) 自凌晨 24 點起的 24 小時期間。先前說明文件載明日期的開始日期為格林威治標準時間凌晨 12:00。

      此外,YouTube Analytics (分析) API 說明文件也已更新,請注意,所有與日期相關的維度 (day7DayTotals30DayTotalsmonth) 都是從太平洋時間凌晨 12 點 (UTC-8) 開始的日期。

    • YouTube Reporting API 的 jobs.reports.list() 方法現在支援 createdAfter 查詢參數。若指定,這個參數表示 API 回應只應列出指定日期和時間之後建立的報表,包括含有補充資料的新報表。請注意,參數值取決於報表建立時間,而不是與傳回資料相關聯的日期。

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

      另外,我們也更新了 YouTube Reporting API 最佳做法,說明如何使用 createdAfter 參數避免重複處理相同的報表。

    • 已修正 job 資源 createTime 屬性的定義,以及 report 資源 startTimeendTimecreateTime 屬性的定義,請注意,屬性值皆精準至微秒,不是奈秒。此外,所有定義現在都能準確反映屬性值是時間戳記。

    2015 年 10 月 8 日

    這次更新的修改如下:

    • YouTube Analytics API sharingService 維度的說明文件已更新,內容包含可能的維度值清單。這份清單包含一些新支援的服務。

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

    2015 年 9 月 24 日

    這次更新的修改如下:

    • 全新的 YouTube Reporting API 可用來擷取大量資料報表,當中包含頻道或內容擁有者的 YouTube 數據分析資料。這個 API 專為可匯入大型資料集的應用程式所設計,並提供篩選、排序及挖掘資料的工具。

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

      您可以使用 API 來安排報表工作,每個工作都識別 YouTube 要產生的報表。設定工作後,YouTube 就會產生每日報表,供您以非同步方式下載。每份報表都包含不重複的 24 小時資料。

    • 雖然兩者是不同的 API,但 YouTube Analytics API 和 YouTube Reporting 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 現在支援兩個影片報表的新指標:videosAddedToPlaylistsvideosRemovedFromPlaylists頻道內容擁有者的影片報表清單皆已更新,以識別支援新指標的報表。

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

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

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

    2015 年 3 月 31 日

    這次更新的修改如下:

    2015 年 3 月 16 日

    這次更新的修改如下:

    • 新的 currency 參數可讓您以美元 (USD) 以外的貨幣擷取收益指標。如果已設定參數,API 會將 earningsgrossRevenueplaybackBasedCpmimpressionBasedCpm 指標的值轉換成指定貨幣。傳回的值是根據每日匯率變化的匯率計算而得。

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

    2015 年 2 月 25 日

    這次更新的修改如下:

    • 您現在可以透過這個 API 建立及管理 YouTube 數據分析群組,也能夠擷取這些群組的報表資料。

      • 建立及管理群組

        這項更新介紹了 groupgroupItem 的資源,用來建立及管理群組。

        • group 資源代表一個 Analytics (分析) 群組,也就是最多可包含 200 個頻道、影片、播放清單或資產的自訂集合。這個 API 支援這項資源的 listinsertupdatedelete 方法。
        • groupItem 資源代表 Analytics (分析) 群組中的一個項目。這個 API 支援這項資源的 listinsertdelete 方法。

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

      • 擷取群組的報表資料

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

      如要進一步瞭解 YouTube 數據分析群組,請參閱 YouTube 說明中心

    2015 年 2 月 13 日

    這次更新的修改如下:

    • API 不再支援 show 維度。

    2014 年 8 月 28 日

    這次更新的修改如下:

    • 現在,當這些維度做為篩選器使用時,API 現在支援為 videoplaylistchannelshow 維度指定多個值。如要指定多個值,請將 filters 參數值設為以半形逗號分隔的影片、播放清單、頻道或顯示 ID,用來篩選 API 回應。參數值最多可指定 200 個 ID。

      如果您針對同一個篩選器指定多個值,也可以將該篩選器新增至您為請求指定的維度清單。即使特定報表並未將該篩選器列為支援的維度,情況也是如此。如果將篩選器加入維度清單,API 也會使用這些篩選器值將結果分組。

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

    2014 年 7 月 16 日

    這次更新的修改如下:

    • 擷取管道報表時,您可以將 ids 參數的值設為 channel==MINE,藉此擷取已驗證使用者管道的資料。(您也可以將 ids 參數設為 channel==CHANNEL_ID,即可擷取指定管道的資料)。

    • 這個 API 現在支援播放清單報表,其中包含影片觀看次數的相關統計資料。頻道內容擁有者可使用播放清單報表。

      所有播放清單報表均支援「views」和「estimatedMinutesWatched」指標,部分報表也支援「averageViewDuration」指標。

      此外,所有播放清單報表都支援下列新指標。請注意,上述指標都只反映網路上的播放清單觀看次數。

      • playlistStarts:觀眾啟動播放播放清單的次數。
      • viewsPerPlaylistStart:每次播放清單開始播放時,觀眾的平均影片觀看次數。
      • averageTimeInPlaylist:播放清單開始播放後,觀眾觀看播放清單中影片的預估平均時間 (以分鐘為單位)。

      凡是擷取播放清單報表的要求,都必須使用 isCurated 篩選器,因此必須設為 1 (isCurated==1)。

    • 這個 API 現在支援觀眾續看率報表。這份報表用於評估影片留住觀眾的能力。報表會推出新的 elapsedVideoTimeRatio 維度,用於衡量相應的指標值目前呈現的影片數量:

      • audienceWatchRatio 指標代表的是影片中特定時間點觀看影片的觀眾的絕對比例。計算方式是將影片中特定片段的觀看次數與影片的總觀看次數進行比較。

        請注意,在特定影片觀看次數中,觀眾可能會多次觀看影片的特定片段,或是根本不會觀看。例如,如果使用者倒轉影片重複觀看同一段影片,該影片的絕對比例可能會大於 1

      • relativeRetentionPerformance 指標會顯示影片與所有長度相近的 YouTube 影片相比,影片在播放期間留住觀眾的成效。如果值為 0,表示相較於其他長度相近的影片,影片留住觀眾的時間比其他長度相近的影片更佳。中位數值為 0.5 表示長度相近的影片中,有半數能留住觀眾,而一半則留住觀眾。

      您也可以使用 audienceType 篩選器,讓報表只傳回與自然觀看、TrueView 串流內廣告的觀看次數或 TrueView 多媒體廣告觀看次數相關的資料。(自然觀看次數是使用者動作 (例如搜尋影片或點選建議的影片) 的直接結果)。

    • 這個 API 支援幾個與註解相關的新指標。凡是先前支援 annotationClickThroughRateannotationCloseRate 指標的報表,都可以擷取下列指標。

      所有新指標都是核心指標,並適用於廢止政策。不過請注意,系統提供自 2013 年 7 月 16 日起的新指標資料。(系統可提供 2012 年 6 月 10 日的 annotationClickThroughRateannotationCloseRate 指標資料)。

    • GOOGLE_SEARCH」不再是「insightTrafficSourceType」維度的個別值。系統現在會將 Google 搜尋結果的參照連結網址歸因於 EXT_URL 流量來源類型。因此,也無法再擷取將 insightTrafficSourceType 篩選器設為 GOOGLE_SEARCHinsightTrafficSourceDetail 報表。

    2014 年 1 月 31 日

    這次更新的修改如下:

    2014 年 1 月 16 日

    這次更新的修改如下:

    • 範例要求文件經過重新設計,可將各種類別的範例分組,採用與最近發布的頻道和內容擁有者報告類似的分頁格式。新版設計會將範例分成以下類別:

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

    • 要求範例文件現在提供新範例,可讓您在頻道報表或內容擁有者報表中擷取各省專屬資料。

      • 美國各州和華盛頓特區特有的各州專屬指標:這份報表會分別擷取頻道影片的觀看次數各州/省的詳細資料和其他統計資料。資料涵蓋美國各州和華盛頓特區。本範例使用 province 維度,並使用了 filters 參數,限制回應只包含美國的結果。

      • 加州的觀眾客層 (年齡層和性別):這份報表會擷取收看頻道影片的加州觀眾年齡層和性別統計資料;如果內容擁有者報表,則會擷取內容擁有者已聲明版權的內容等統計資料。這個範例使用 filters 參數,確保回應只包含特定省分的資料。

    • province」維度的定義已更新為:當 dimensions 參數值包含 province 時,該要求也必須在 filters 參數值中加入 country==US,藉此限制只向美國顯示資料。

    2014 年 1 月 6 日

    這次更新的修改如下:

    • 我們重新設計支援的頻道內容擁有者報告的文件。各文件並不會提供列出所有可能報表的表格,而是將這些文件分為以下類別:

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

      每份文件都會以分頁清單形式顯示這些類別,只要按一下任一分頁標籤,即可查看該類別支援的報表。

    • 這個 API 現在支援三個新的地理區域維度:provincecontinentsubContinent

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

        • 此 API 支援按狀態細分統計資料的兩份報表。這兩種報表可供頻道內容擁有者使用。

          • 核心統計資料報告提供多項統計資料,包括觀看次數和預估觀看時間 (分鐘)。
          • 時間報表提供的統計資料相同,但每日、7 天、30 天或每月匯總資料。

        • 您可以使用 filters 查詢參數,限制報表只包含特定狀態的統計資料。部分報表支援這種篩選方式,包括地理區域報表、播放位置報表、流量來源報表、裝置報表、作業系統報表、客層報表和熱門影片報表。

      • continent」維度會指定代表大陸的聯合國 (UN) 統計區碼。這個維度只能做為篩選器使用。

      • subContinent」維度會指定聯合國 (UN) 統計區碼,用來識別某一洲的某個子區域。這個維度也只能當做篩選器使用。

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

    • 說明文件已修正,因此「insightTrafficSourceDetail」維度不會將 insightTrafficSourceTypePROMOTED 加入為有效的篩選器值。

    2013 年 9 月 30 日

    這次更新的修改如下:

    • YouTube Analytics API 目前受到《服務條款》中所述的廢止政策規範。不過,API 的非核心維度和非核心指標不受《廢止政策》約束。「維度」和「metrics」頁面已更新,列出核心維度和指標。此外,這些網頁上的定義也已更新,以明確識別核心維度和指標。

    • API 現在支援以 EXTERNAL_APP 做為 insightPlaybackLocationType 維度的值。在本次更新中,自 2013 年 9 月 10 日起,播放次數將不再歸類為 MOBILE 次播放,但在此之前發生的行動播放次數仍會歸類為這個值。

      本次更新後,視播放位置的應用程式類型而定,行動播放次數現已歸類為 WATCHEMBEDDEDEXTERNAL_APP 播放。

    • API 現在支援以 PLAYLIST 做為 insightTrafficSourceType 維度的值。這個值代表影片觀看次數來自播放清單。這些資料檢視先前都是以維度的 YT_OTHER_PAGE 類別加以分類,

    2013 年 7 月 16 日

    這次更新的修改如下:

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

    • 這個 API 現在支援 deviceTypeoperatingSystem 這兩個新維度,可用於擷取觀眾用來觀看影片的裝置相關資料。API 支援使用一或兩種維度的報表。

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

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

      新的裝置類型和作業系統報表適用於頻道內容擁有者

    • 範例要求文件已更新,納入了三份頻道裝置報告,以及內容擁有者的三份裝置報告。

    • insightPlaybackLocationType 維度可能會傳回 YT_OTHER 值,找出未以其中一個維度的其他值分類的資料檢視。

    2013 年 5 月 23 日

    這次更新的修改如下:

    • 內容擁有者報表文件經過更新,現在你可以依收益遞減排序顯示熱門影片報表,找出收益最高的影片。這份報表是「使用者活動和收益報表」部分第二個表格的第一份表格。

    2013 年 5 月 10 日

    這次更新的修改如下:

    2013 年 5 月 6 日

    這次更新的修改如下:

    • 現在您可以擷取觀看時間指標 (estimatedMinutesWatchedaverageViewDurationaverageViewPercentage) 與其他指標,包括觀看指標、參與度指標、收益指標和廣告成效指標。

      為反映這項異動,我們已更新可用的頻道報表內容擁有者報表清單。(目前清單更加精簡,因為觀看時間指標已列在其他列出的報表中)。

      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 支援頻道和內容擁有者的多種新報表,如下所述。每份報表都會以頻道報表內容擁有者報表的形式提供。維度metrics頁面也已隨之更新。

      • 「播放位置」報表會顯示不同類型網頁或應用程式上發生的影片觀看次數。

      • 「播放位置詳細資料」報表會指出為指定影片帶來最多觀看次數的嵌入式播放器。比起播放位置報表,它能提供更詳盡的資料檢視,找出與熱門嵌入式播放器相關聯的網址。

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

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

      • 觀看時間報表會顯示觀眾收看你內容的時間長度。這種報表能夠彙整特定時間範圍 (日、過去 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 擷取內容擁有者報表的請求時,必須使用這些維度 (videochannelshow),或是支援的 claimedStatusuploaderType 維度組合來篩選資料。

    • 這個 API 現在支援兩種熱門影片報表的排序選項。這類報表以頻道報表或內容擁有者報表的形式提供,提供依國家/地區細分的指標 (觀看次數、留言數、喜歡次數等),並會按影片細分這些指標。你現在可依據影片觀賞頁面訂閱或取消訂閱頻道的使用者人數排序這些報表。

    • 更新subscribersGainedsubscribersLost metrics的定義,說明頻道在不同地方可能會增加或流失訂閱者,包括影片觀賞頁面、頻道頁面,以及 YouTube 首頁上的指南。當這些指標顯示在影片專用報表中時,只會包含指定影片觀賞頁面的統計資料。