修訂記錄

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

2024 年 11 月 15 日

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

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

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

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

2024 年 5 月 6 日

YouTube Analytics (指定查詢) API 支援三種新的頻道報表：

  • 「使用者活動 (按指定行銷區域劃分)」報表是一項地理報表，可依指定行銷區域 (DMA) 提供使用者活動統計資料。針對這份報表，您必須將 filters 參數值設為 country==US。

  • 「同時線上觀眾人數」報表會顯示單一直播影片的不同部分，同時觀看人數的數量。

  • 「會員取消」報表會提供統計資料，說明使用者取消頻道會籍的原因。

    這份報表採用新的 membershipsCancellationSurveyReason 維度，可指出使用者取消訂閱頻道會員的原因。這項指標也使用新的 membershipsCancellationSurveyResponses 指標，可顯示因該原因而取消的頻道會員數量。

此外，我們也強化了觀眾續看率報表，以支援三項新指標：

2024 年 4 月 7 日

YouTube Analytics (指定查詢) 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 Analytics (指定查詢) 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 Analytics (指定查詢) 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 Analytics (指定查詢) API 中，gender 維度目前支援兩個值：female 和 male。2022 年 8 月 11 日當天或之後，這個維度將支援三個值：female、male 和 user_specified。
  • 在 YouTube Reporting (Bulk Reports) 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 Analytics (指定查詢) 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 數據分析資料時，應套用的篩選器清單。這個參數可支援為 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 日 (2020-01-13) 開始的時間範圍傳回這些值。

提醒你，這些值並非代表通知本身，而是驅動特定 YouTube 觀看次數的流量來源。舉例來說，如果報表列顯示 views=3、traffic_source_type=17 (NOTIFICATION) 和 traffic_source_detail=uploaded_push，表示有三次觀看次數是因為觀眾點按上傳影片時傳送的推播通知而產生。

2019 年 10 月 15 日

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

  • 注意：這是一則淘汰功能的公告。

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

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

    • 只要將該週內的每日觀看次數加總，即可計算出七天內的觀看次數。
    • 如要計算七天期間的觀眾百分比，請將每天的觀看次數乘以當天的觀眾百分比，即可得出當天登入觀看影片的觀眾人數。接著，您可以將整個期間內登入的觀眾人數相加，再除以該期間的總觀看次數，即可取得整個期間的觀眾百分比。
    • 系統無法計算七天期間的不重複觀眾人數，因為同一位觀眾可能會在不同天計算為不重複觀眾。不過，您可以使用 month 維度 (而非 30DayTotals 維度) 推估 30 天內的不重複觀眾人數。請注意，month 維度是指日曆月，而 30DayTotals 維度會根據指定的開始和結束日期計算 30 天期間。

2019 年 6 月 27 日

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

  • 由於 API 的 1.0 版已完全淘汰，因此我們已更新說明文件，移除對該版本的參照，包括淘汰通知和遷移指南，說明如何更新至 2.0 版。

2018 年 11 月 1 日

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

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

    請注意，這項服務的停用時間表最初是在 2018 年 4 月 26 日公布。

2018 年 9 月 17 日

本次更新包含下列與 YouTube Analytics (指定查詢) 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 Analytics (指定查詢) 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) 會在 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 中淘汰通用批次端點。
    • API 2 版不支援 JSON-RPC 通訊協定，但 API 1 版支援這項通訊協定。再次提醒，這項淘汰作業並非 YouTube Analytics API 專屬。

  • 注意：這是一則淘汰功能的公告。

    API 的 1 版 (v1) 現已淘汰，並將在 2018 年 10 月 31 日停止支援。屆時，所有對第 1 版 API 提出的要求都會停止運作。因此，請務必在 2018 年 10 月 31 日前升級至 v2 API，以免無法透過 API 存取 YouTube Analytics 資料。

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 值，這代表以預訂方式銷售的 Bumper 廣告。串場廣告是不可略過的影片廣告，最長 6 秒。觀眾必須先看完這段廣告，才能觀賞影片。請注意，這個維度的值 19 也指透過競價而非預訂方式銷售的 Bumper 廣告。

    • 下列 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 小時期間，而太平洋時間一律為 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:00 到 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 創作者工作室的「報表」專區，系統就會自動產生一組由系統管理的廣告收益報表。新的系統管理 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 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。與舊版報表 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 天。

      這些變更都會在報表 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 訊息服務
    • 在 YouTube Analytics API 中，sharingService 維度支援下列新值：
      • ANDROID_MESSENGER：Android 訊息服務
      • 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 擷取資訊卡指標，該 API 支援多個頻道和內容擁有者報表的這些指標。

    2016 年 1 月 6 日

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

    • 在 YouTube 報表 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 個以上 觀看次數、estimatedMinutesWatched
      篩選器：
      使用 0 或 1 country、province、continent、subContinent
      使用 0 或 1 video、group
      使用 0 或更多 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct

      頻道和內容擁有者報表的說明文件中，說明瞭描述必要和選用欄位的術語。

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

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

    • 如果您要求空白 YouTube Analytics 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 點開始的 24 小時期間。先前說明文件指出，日期的開始時間為格林威治標準時間凌晨 12 點。

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

    • 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 數據分析資料。此 API 適用於可匯入大型資料集的應用程式，並提供篩選、排序及挖掘資料的工具。

      每份 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 售出廣告來源的預估總收益 (淨收益)。這不是核心指標。這個 API 支援 adEarnings 指標，適用於任何已支援 earnings 指標的報表。

      此外，我們也修正了 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 個頻道、影片、播放清單或資產的自訂集合。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 日

    這次更新的修改如下：

    • API 現在支援在 video、playlist、channel 和 show 維度中，將這些維度用作篩選器時，指定多個值的功能。如要指定多個值，請將 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 支援頻道和內容擁有者可用的多項新報表，如下所述。每份報表都會以頻道報表或內容擁有者報表的形式提供。維度和指標頁面也已相應更新。

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

      • 播放位置詳細報表會指出哪些嵌入式播放器為特定影片帶來最多觀看次數。這份報表會比播放位置報表提供更精細的視圖，並找出與前幾大嵌入式播放器相關聯的網址。

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

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

      • 觀看時間報表會顯示觀眾觀看頻道內容的時間長度。報表可匯總特定時間範圍 (例如一天、過去七天、過去 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 首頁上的導覽。當這些指標出現在影片專屬報表中時，只會包含指定影片觀賞頁面的統計資料。