本頁面列出 YouTube Reporting API 和 YouTube Analytics API 的 API 異動與說明文件更新內容。這兩種 API 都可讓開發人員以不同的方式存取 YouTube 數據分析資料。訂閱這份變更記錄。
2024 年 5 月 6 日
YouTube 數據分析 (指定查詢) API 支援三種頻道的新報表:
-
「使用者活動 (依指定行銷區域)」報表是一種地理區域報表,可依據指定行銷區域 (DMA) 提供使用者活動統計資料。在這個報表中,您必須將
filters
參數值設為country==US
。 -
「同時線上觀眾人數」報表會顯示單一直播影片中不同部分的同時觀眾人數。
-
這份報表採用新的「
membershipsCancellationSurveyReason
」維度,指出使用者取消頻道會籍的原因。同時也使用新的membershipsCancellationSurveyResponses
指標,顯示因該原因而取消的頻道會員人數。
此外,「觀眾續看率」報表也經過強化,以支援三項新指標:
2024 年 4 月 7 日
YouTube 數據分析 (目標查詢) API 有多項與內容擁有者播放清單報表相關的更新。更新內容與我們在 2024 年 1 月 19 日公告的頻道播放清單報表相關更新內容相同。
下列修訂版本記錄項目提供的資訊與 2024 年 1 月 19 日的項目幾乎相同。請注意,內容擁有者播放清單報表在 2024 年 12 月 31 日前仍可使用「isCurated
」維度,而頻道播放清單報表在 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 功能與工作室應用程式提供的功能一致。
- 新的頻道播放清單報表不支援
-
內容擁有者報告說明文件的播放清單報表一節已更新,以詳細說明播放清單報表支援的指標類型:
-
內容擁有者的播放清單報表支援下列新的播放清單內指標。請注意,只有在擷取報表的 API 要求「並未」使用
isCurated
維度時,系統才支援這些指標。如需每個指標的定義,請參閱metrics說明文件: -
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 功能與工作室應用程式提供的功能一致。
- 新的頻道播放清單報表不支援
-
我們更新了頻道報表說明文件的播放清單報表一節,更詳細地說明播放清單報表支援的指標類型:
-
頻道的播放清單報表支援下列新的播放清單中指標。內容擁有者報表目前尚不支援這些指標。請注意,只有在擷取報表的 API 要求「並未」使用
isCurated
維度時,系統才支援這些指標。如需每個指標的定義,請參閱metrics說明文件: -
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 數據分析 (目標查詢) API 和 YouTube Reporting (大量報表) API 都支援新的流量來源詳細資料值:
- 在 YouTube Analytics API (目標查詢) API 中,如果
insightTrafficSourceType
維度的值為SUBSCRIBER
,則可將insightTrafficSourceDetail
值設為podcasts
,表示流量來自 Podcast 到達網頁。 - 在 YouTube Reporting (大量報表) API 中,如果
traffic_source_type
維度的值為3
,則可將traffic_source_detail
值設為podcasts
,表示流量來自 Podcast 到達網頁頁面。
2022 年 2 月 11 日
「gender
」維度的有效值組合將於 2022 年 8 月 11 日當天或之後變更。這可能會導致您的 API 實作變更無法回溯相容。為遵循《YouTube API 服務條款》的回溯不相容異動一節,我們會在異動生效的六個月前公告。請在 2022 年 8 月 11 日前更新 API 實作方式,確保能順暢改用新值組合。
具體變更如下:
- 在 YouTube 數據分析 (目標查詢) API 中,
gender
維度目前支援兩個值:female
和male
。2022 年 8 月 11 日起,該維度將支援三個值:female
、male
和user_specified
。 - 在 YouTube Reporting (大量報表) API 中,
gender
維度目前支援三個值:FEMALE
、MALE
和GENDER_OTHER
。2022 年 8 月 11 日當天或之後,支援的值組合將變更為FEMALE
、MALE
和USER_SPECIFIED
。
2022 年 2 月 9 日
截至 2021 年 12 月 13 日,我們更新了兩項指標,排除循環片段流量。這項異動會影響 YouTube 數據分析 (目標查詢) API 和 YouTube Reporting (大量報表) API。
- 自 2021 年 12 月 13 日起,在 YouTube 數據分析 (目標查詢) API 中,
averageViewDuration
和averageViewPercentage
指標都會排除循環播放片段的流量。 - 自 2021 年 12 月 13 日起,在 YouTube Reporting (大量報表) API 中,
average_view_duration_seconds
和average_view_duration_percentage
指標都會排除循環播放片段的流量。
2022 年 2 月 2 日
這個 YouTube Reporting (大量報表) API 支援新的流量來源維度值,能指出觀看次數來自直播重新導向:
- 在 YouTube Reporting (大量報表) API 中,
traffic_source_type
維度支援28
值。
以這個流量來源類型來說,traffic_source_detail
維度會指定觀眾招攬到的頻道 ID。
2020 年 9 月 23 日
這個 YouTube 數據分析 (目標查詢) API 和 YouTube Reporting (大量報表) API 都支援新的流量來源維度值,指出觀眾在 YouTube Shorts 觀看體驗中以垂直滑動的方式找到觀眾:
- 在 YouTube Analytics API (目標查詢) API 中,
insightTrafficSourceType
維度支援SHORTS
值。 - 在 YouTube Reporting (大量報表) API 中,
traffic_source_type
維度支援24
值。
系統不會針對這個新的流量來源類型填入流量來源詳細資料維度 (YouTube Analytics API 中的 insightTrafficSourceDetail
),或是 YouTube Reporting API 中的 traffic_source_detail
。
2020 年 7 月 20 日
本次更新涵蓋兩項會影響 YouTube 數據分析 (目標查詢) API 的異動:
- YouTube 數據分析報表群組的大小上限已從 200 個實體增加至 500 個。
reports.query
方法的filters
參數會識別擷取 YouTube 數據分析資料時應套用的篩選器清單。這個參數支援為video
、playlist
和channel
篩選器指定多個值,且可為這些篩選器指定的 ID 數量上限從 200 個增加到 500 個。
2020 年 2 月 13 日
本次更新包含下列與 YouTube 數據分析 (目標查詢) API 和 YouTube Reporting (大量報表) API 相關的異動。如要進一步瞭解相關異動,請造訪 YouTube 說明中心。
這兩個 API 中的通知可能流量來源詳細資料值都即將變更。在指定查詢中,通知會回報為 insightTrafficSourceType=NOTIFICATION
。在大量報表中,通知會回報為 traffic_source_type=17
。
新的值會將與上傳的影片和直播相關的通知 (先前回報為 uploaded
) 分成兩類:
uploaded_push
- 來自影片上傳時傳送給訂閱者的推播通知的觀看次數uploaded_other
- 來自非推播通知 (例如電子郵件或收件匣通知) 在影片上傳時傳送給訂閱者的觀看次數。
系統會針對 2020 年 1 月 13 日 (2020 年 1 月 13 日) 起的時段傳回這些值。
此外提醒您,這些值並非通知本身,而是帶來特定 YouTube 觀看次數的流量來源,不代表通知。舉例來說,如果報表列顯示 views=3
、traffic_source_type=17
(NOTIFICATION
) 和 traffic_source_detail=uploaded_push
,該列代表觀眾在影片上傳時點選傳送的推播通知,而產生了三次觀看。
2019 年 10 月 15 日
本次更新包含下列與 YouTube 數據分析 (Targeted Lookup) API 相關的異動:
-
注意:這是淘汰公告。
YouTube 即將停止支援「
7DayTotals
」和「30DayTotals
」維度。在 2020 年 4 月 15 日前,你還是可以使用這些維度擷取資料。在該日期當天或之後,如果您嘗試使用7DayTotals
或30DayTotals
維度擷取報表,系統將傳回錯誤。請注意,使用者可以查詢
day
維度,並匯總或取得七天或 30 天期間的資料,重現這些維度的部分資料。例如:- 將這段時間內每天的觀看次數加總,即可算出該期間內七天的觀看次數。
- 將七天內觀眾百分比乘以該日觀看次數,乘以觀眾百分比,即可算出當天觀看影片的不重複觀眾人數。接著,您可以將整個時間範圍內已登入的觀眾人數,除以該時段的總觀看次數,算出整個期間內的觀看者百分比。
- 系統無法計算某七天的不重複觀眾人數,因為系統可能會將同一位觀眾計為不同天的不重複觀眾人數。不過,您可以使用「
month
」維度而非30DayTotals
維度,推斷 30 天內的不重複觀眾人數資料。請注意,month
維度是指日曆月份,30DayTotals
維度則是根據指定的開始和結束日期來計算 30 天的期間。
2019 年 6 月 27 日
本次更新包含下列與 YouTube 數據分析 (Targeted Lookup) API 相關的異動:
-
自第 1 版 API 現已完全淘汰,說明文件已更新,並移除對該版本參照的內容,包括淘汰通知和說明如何更新至第 2 版的遷移指南。
2018 年 11 月 1 日
本次更新包含下列與 YouTube 數據分析 (Targeted Lookup) API 相關的異動:
-
API 第 1 版現已淘汰。如果您尚未更新 API 用戶端,請盡快改用第二版 API,盡量避免服務中斷。詳情請參閱遷移指南。
請注意,淘汰時間表原定於 2018 年 4 月 26 日宣布。
2018 年 9 月 17 日
本次更新包含下列與 YouTube 數據分析 (Targeted Lookup) API 相關的異動:
-
在「資料模型」總覽文件中,新推出的「資料去識別化」一節將說明如果指標未達特定門檻,部分 YouTube 數據分析資料會受到限制。很多情況下都會發生這種情況。這表示在實際執行時,如果符合下列條件,報表可能不會包含全部 (或任何) 資料:
-
影片或頻道在特定時間範圍內的流量有限
或
-
選取的篩選器或維度 (例如流量來源或國家/地區) 的值未達特定門檻。
以及 YouTube 數據分析報表可能限制的資料類型。
-
-
頻道報表和內容擁有者報表文件已更新,以反映播放位置、流量來源和裝置類型/作業系統報表不再支援
redViews
和estimatedRedMinutesWatched
指標。
2018 年 6 月 18 日
本次更新包含以下 YouTube 數據分析 (Targeted Query) 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 數據分析 (Targeted Query) 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 天才會顯示。
2018 年 4 月 26 日
YouTube 數據分析 (目標查詢) API (v2) 第 2 版現已公開推出。以下清單列出與新版 API 相關的產品和說明文件異動:
-
第 2 版 API 與 v1 API 幾乎相同,不過,您可能需要更新程式碼來反映下列變更。如要進一步瞭解上述所有異動,請參閱新的遷移指南。
- API 的版本已從
v1
變更為v2
。 - API 要求的基準網址已從
https://www.googleapis.com/youtube/analytics/v1
變更為https://youtubeanalytics.googleapis.com/v2
。 reports.query
方法的幾個參數已更新名稱。具體來說,包含連字號的參數名稱,例如 v1 API 使用駝峰式大小寫 (endDate
) 中的end-date
,而非 v2 API 中的連字號。這項變更讓整個 API 的參數名稱保持一致,因為 API 用來建立和管理群組的方法已使用駝峰式大小寫。- v2 API 不支援傳送至 Google 全球 HTTP 批次端點 (
www.googleapis.com/batch
) 的批次要求。如果您要透過 v2 API 傳送批次要求,就必須改用端點https://youtubeanalytics.googleapis.com/v2
。
此外,第 2 版 API 不支援部分 v1 功能:
reports.query
方法不再支援alt
、quotaUser
和userIp
要求參數。- v2 API 不提供批次端點,這類端點支援批次對不同 API 的要求。(然而,一個批次可由對相同 API 不同方法提出的要求組成)。這項異動並非只針對 YouTube Analytics API,因為 Google 將全面淘汰旗下所有 API 的全球批次端點。
- v2 API 不支援 API v1 支援的 JSON-RPC 通訊協定。再次強調,這並非 YouTube Analytics API 特有的淘汰。
- API 的版本已從
-
注意:這是淘汰公告。
API 第 1 版 (v1) 現已淘汰,將於 2018 年 10 月 31 日前持續提供支援。自該日起,所有傳送至 v1 API 的要求都會停止運作。因此,請務必在 2018 年 10 月 31 日前升級至 2018 版,以免無法透過 API 存取 YouTube 數據分析資料。
2018 年 2 月 21 日
本次更新包含以下 YouTube 數據分析 (Targeted Query) API 異動:
- 觀眾客層報表 (根據觀眾的年齡層和性別匯總觀看統計資料) 不再支援
youtubeProduct
維度 (用於識別使用者活動的 YouTube 服務)。
2018 年 1 月 18 日
這次更新的修改如下:
-
YouTube Reporting API (大量報表)
operating_system
維度可識別發生檢視畫面的裝置軟體系統,現在支援下列值:25
:KaiOS
-
YouTube Analytics API (指定查詢)
operatingSystem
維度支援維度值KAIOS
。
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 回應包含要求日期範圍內最後一天的資料,您可以取得查詢的所有指標。
舉例來說,如果要求指定的結束日期為 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 Music86
:YouTube Gaming87
:YouTube Kids88
: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 存取收益資料:
-
這個 API 支援下列收益相關指標:
adImpressions
cpm
estimatedAdRevenue
estimatedRedPartnerRevenue
estimatedRevenue
grossRevenue
monetizedPlaybacks
playbackBasedCpm
下列報表支援這些指標:
2017 年 3 月 17 日
這次更新的修改如下:
-
YouTube Analytics API 支援
redViews
和estimatedRedMinutesWatched
指標,這兩項指標與 YouTube Red 觀眾人數相關。事實上,這個 API 已實際支援這些指標一段時間,而 YouTube Reporting API 已按照 2016 年 9 月 15 日公告的內容支援這兩項指標。redViews
指標代表 YouTube Red 會員觀看影片的次數。estimatedRedMinutesWatched
指標代表 YouTube Red 會員觀看影片的分鐘數。
頻道報表和內容擁有者報表說明文件已更新,為指出哪些報表支援這兩項新指標。凡是已支援
views
和estimatedMinutesWatched
指標的報表,都能使用這類 ID。
2017 年 3 月 3 日
這次更新的修改如下:
-
YouTube Reporting API (大量報表)
-
已修正
date
維度的定義,請注意,維度值是指從太平洋時間凌晨 12 點開始的期間,結束於太平洋時間的指定日期、月份和年份下午 11 點 59 分。視當地時間而定,太平洋時間為 UTC-7 或 UTC-8。雖然日期通常代表 24 小時,但向前調整時鐘的日期代表 23 小時,而時鐘往後調整的日期則代表 25 小時。(先前說明文件指出,每個日期都代表不同的 24 小時制,且太平洋時間一律為 UTC-8)。
請注意,這項修正並不代表實際的 API 行為改變。
operating_system
維度可識別發生檢視畫面的裝置軟體系統,現在支援下列值:22
:Tizen23
:Firefox24
: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 日發布)。
-
管道報表
channel_basic_a1
- 已由channel_basic_a2
報表取代。channel_province_a1
- 已由channel_province_a2
報表取代。channel_playback_location_a1
- 已由channel_playback_location_a2
報表取代。channel_traffic_source_a1
- 已由channel_traffic_source_a2
報表取代。channel_device_os_a1
- 已由channel_device_os_a2
報表取代。channel_subtitles_a1
- 已由channel_subtitles_a2
報表取代。channel_combined_a1
- 已由channel_combined_a2
報表取代。
-
內容擁有者報告
content_owner_basic_a2
- 已由content_owner_basic_a3
報表取代。content_owner_province_a1
- 已由content_owner_province_a2
報表取代。content_owner_playback_location_a1
- 已由content_owner_playback_location_a2
報表取代。content_owner_traffic_source_a1
- 已由content_owner_traffic_source_a2
報表取代。content_owner_device_os_a1
- 已由content_owner_device_os_a2
報表取代。content_owner_subtitles_a1
- 已由content_owner_subtitles_a2
報表取代。content_owner_combined_a1
- 已由content_owner_combined_a2
報表取代。content_owner_asset_basic_a1
- 已由content_owner_asset_basic_a2
報表取代。content_owner_asset_province_a1
- 已由content_owner_asset_province_a2
報表取代。content_owner_asset_playback_location_a1
- 已由content_owner_asset_playback_location_a2
報表取代。content_owner_asset_traffic_source_a1
- 已由content_owner_asset_traffic_source_a2
報表取代。content_owner_asset_device_os_a1
- 已由content_owner_asset_device_os_a2
報表取代。content_owner_asset_combined_a1
- 已由content_owner_asset_combined_a2
報表取代。
此外,API 參考說明文件中的目前報表類型清單也已更新。
2016 年 11 月 11 日
這次更新的修改如下:
-
片尾報表
-
片尾尺寸
end_screen_element_type
:與統計資料相關聯的片尾元素類型。end_screen_element_id
:YouTube 用來識別片尾元素的 ID。
片尾指標
注意:結束畫面指標資料自 2016 年 5 月 1 日起提供。
end_screen_element_impressions
:片尾元素的總曝光次數。系統會為顯示的每個片尾元素記錄一次曝光。end_screen_element_clicks
:片尾元素點擊次數。end_screen_element_click_rate
:片尾元素的點閱率。
-
系統已不再支援以下報表,並已從說明文件中移除。每份報表都已推出新版本。(這些報表的淘汰公告已於 2016 年 6 月 22 日發布)。
content_owner_ad_performance_a1
- 已由content_owner_ad_rates_a1
報表取代。content_owner_estimated_earnings_a1
- 已由content_owner_estimated_revenue_a1
報表取代。content_owner_asset_estimated_earnings_a1
- 已由content_owner_asset_estimated_revenue_a1
報表取代。
-
以下清單中的指標已完全淘汰,不再受支援。如 2016 年 8 月 10 日的公告所述,我們已支援參照相同資料的新指標。下表列出已淘汰的指標名稱和新指標名稱:
已淘汰的指標 新指標 adEarnings
estimatedAdRevenue
impressionBasedCpm
cpm
impressions
adImpressions
redPartnerRevenue
estimatedRedPartnerRevenue
- 每部影片的每月全球廣告收益
- 每部影片的每日廣告收益 (按國家/地區劃分)
- 每項資產的每月全球廣告收益
- 每項資產的每日廣告收益 (按國家/地區劃分)
- 版權聲明 (這份報表不含收益資料)
-
這個 API 支援兩項與 YouTube Red 觀眾人數相關的新指標:
red_views
:YouTube Red 會員觀看影片的次數。red_watch_time_minutes
:YouTube Red 會員觀看影片的分鐘數。
-
這個 API 支援 20 份報告的新版本。所有新版本都支援新的
red_views
和red_watch_time_minutes
指標。針對每個報表,新報表類型 ID 中的數字比舊版報表類型 ID 高出一個。(舊版報告現已於此修訂版本記錄中後續說明淘汰)。舉例來說,
channel_basic_a1
報表現已淘汰,並由channel_basic_a2
報表取代。以下清單列出新報表類型的 ID:
頻道影片報表
內容擁有者影片報表
內容擁有者資產報表
-
注意:這是淘汰公告。
請注意,如果您先前已有建立上述任一舊版報表的工作,就需要為重新命名的報表建立新工作。與新版報表版本一起淘汰,下列報表版本已經淘汰:
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
如有任何報表工作,YouTube 將不會在 2016 年 12 月 15 日後為這些工作產生新的報表。產生的報表在產生後的 180 天內,仍可存取。
-
content_owner_basic_a1
報表已完全淘汰,並從說明文件中移除。YouTube 不會再產生該類型的新報表,但對於產生的報表,在報表產生後的 180 天內,您還是可以存取。如同 2016 年 5 月 19 日的修訂版本記錄項目所述,
content_owner_basic_a1
報告將取代content_owner_basic_a2
報告。 -
YouTube 工程與開發人員網誌近期發布的新版《YouTube API 服務條款》(以下簡稱「新版條款」),內容將針對目前的《服務條款》內容提供一系列更新內容。除了將於 2017 年 2 月 10 日生效的《新版條款》外,本次更新還包含幾項佐證文件,可說明開發人員必須遵守的政策。
如需完整的新文件清單,請參閱新版條款的修訂版本記錄。此外,「新版條款」或相關佐證文件如有變更,我們也會在修訂記錄中註明。您可以透過文件中的連結,訂閱 RSS 動態消息清單,列出該修訂版本記錄的變更。
-
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 秒,觀眾必須先看完廣告,才能繼續觀看影片。
-
YouTube Analytics API (指定查詢)
- 我們更新了下列管道報表的支援指標清單,以納入資訊卡指標。這類報表中的資訊卡指標已於 2016 年 6 月 28 日開始支援,當天的修訂版本記錄項目詳細說明瞭變更內容。報告如下:
- 美國各州的基本使用者活動
- 特定時間範圍內,美國境內的使用者活動
- 使用者活動 (依省分組)
- 使用者活動 (依訂閱狀態區分)
- 使用者活動 (依州/省的訂閱狀態劃分)
- 按州/省劃分的熱門影片
- 訂閱或未訂閱觀眾的熱門影片
-
頻道觀眾續看率和內容擁有者觀眾續看率報表的篩選器清單已經過修正,表示必須使用
video
篩選器,但不支援「group
」篩選器。先前這兩份報表的說明文件都指出,報表可以只用這兩種篩選器之一或兩者都沒有篩選器來擷取。
- 我們更新了下列管道報表的支援指標清單,以納入資訊卡指標。這類報表中的資訊卡指標已於 2016 年 6 月 28 日開始支援,當天的修訂版本記錄項目詳細說明瞭變更內容。報告如下:
-
YouTube Reporting API (大量報表)
- 在 API 總覽中,說明如何擷取報表的下載網址一節已更正,指出 YouTube 會在沒有可用資料的日期產生可下載報表。這些報表包含標題列,但沒有包含其他資料。我們已在同一份文件的 2016 年 4 月 12 日更新報表特性一節中的相關資訊。
- 「
content_owner_asset_cards_a1
」報表中的維度清單已經過修正,反映該報表使用「card_id
」維度。先前說明文件誤將維度名稱列為card_title
。
-
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
。
這兩個新重新命名的報表與前身有以下不同:
- 並新增
estimated_partner_red_revenue
指標,用於預估來自 YouTube Red 訂閱項目的總收益。 - 他們加入了
estimated_partner_transaction_revenue
指標,用來估算來自付費內容和粉絲贊助等交易的收益,並扣掉任何合作夥伴收取的退款。 - 他們將
estimated_partner_ad_sense_revenue
指標重新命名為estimated_partner_ad_auction_revenue
。 - 他們將
estimated_partner_double_click_revenue
指標重新命名為estimated_partner_ad_reserved_revenue
。
- 新版「
請注意,如果已執行過建立舊版報表的工作,則需要替重新命名的報表建立新工作。與新版報表版本一起淘汰,我們已淘汰
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 提供的任何報表都不支援這些維度。 -
這個 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
報表已淘汰。如果有一份工作報表,你應該在 2016 年 8 月 19 日之後,應該不會預期 YouTube 為該工作產生新的報表。產生的報表在產生後的 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 要求失敗的原因。 -
YouTube 現在會產生相關資料,範圍涵蓋初次排定報表工作前的 180 天。Reporting API 先前不會提供任何歷來資料。這項變更會影響所有工作,包括在這項公告之前建立的工作。
歷來資料報表一推出就會立即發布,但要為工作發布所有歷來資料約需一個月的時間。因此,在排定報表工作一個月之後,您就能夠存取大約 7 個月的資料。(凡是在這項公告前建立的工作,所有的歷來資料都應在公告後的一個月內發布)。
請注意,歷來資料只提供 2015 年 7 月 1 日。因此,在 2015 年 12 月 28 日前建立的工作,歷來資料將少於 180 天。
-
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
。
-
- 在 YouTube Reporting API 中,
sharing_service
維度支援下列新值:82
:iOS 系統活動對話方塊83
:Google 收件匣84
:Android Messenger
- 在 YouTube Analytics API 中,
sharingService
維度支援下列新值:ANDROID_MESSENGER
:Android MessengerINBOX
:Google 收件匣IOS_SYSTEM_ACTIVITY_DIALOG
:iOS 系統活動對話方塊
playback_location_type
維度支援兩個新維度值:7
:這類觀看次數資料來自 YouTube 首頁或主畫面、使用者的訂閱動態消息,或其他 YouTube 瀏覽功能的觀看次數。8
:這項資料代表直接觀眾在 YouTube 搜尋結果網頁上觀看的次數。
traffic_source_type
維度現在支援使用18
做為維度值。這個值代表影片觀看次數來自列出播放清單中所有影片的頁面。這個來源與14
來源類型不同,後者代表影片播放時,觀眾觀看是播放清單中的影片。insightPlaybackLocationType
維度支援兩個新維度值:BROWSE
:這類觀看次數資料來自 YouTube 首頁或主畫面、使用者的訂閱動態消息,或其他 YouTube 瀏覽功能的觀看次數。SEARCH
:這項資料代表直接觀眾在 YouTube 搜尋結果網頁上觀看的次數。
insightTrafficSourceType
維度現在支援使用YT_PLAYLIST_PAGE
做為維度值。這個值代表影片觀看次數來自列出播放清單中所有影片的頁面。這個來源與PLAYLIST
來源類型不同,後者代表影片是以播放清單的形式播放時的觀看次數。- 在 YouTube Reporting API 中,
operating_system
維度使用21
值,識別透過 Chromecast 發生的觀看次數。 - 在 YouTube Analytics API 中,
operatingSystem
維度使用CHROMECAST
值,識別透過 Chromecast 發生的觀看次數。 -
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、大陸、subContinent 請使用 0 或 1 video、group 使用 0 以上的數字 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct -
對於 API 使用者無法從支援多個值 (
video
、playlist
和channel
) 的篩選器中擷取資料的實體,YouTube Analytics API 現在會自動捨棄這些實體。以前,如果 API 使用者無法存取至少一個指定項目的資料,API 伺服器只會傳回錯誤。舉例來說,假設使用者提交的 API 要求中,
video
篩選器列出 20 個影片 ID。該使用者擁有其中 18 部影片。不過,一個影片 ID 代表了其他頻道擁有的影片,另一個 ID 則代表已刪除的影片,因此該影片不再存在。在這種情況下,API 伺服器現在會捨棄使用者無法存取的兩部影片,而非傳回錯誤,API 回應會包含 API 使用者所擁有 18 部影片的資料。 -
如果您要求的資料包含空白的 YouTube 數據分析
group
,API 現在會傳回空白的資料集,而非錯誤。 -
如果你嘗試將實體新增至群組,但不具備該實體的存取權,YouTube Analytics API 的
groupItems.insert
方法現在會傳回未獲授權 (403
HTTP 回應代碼) 的錯誤。過去,API 可讓您將實體加到群組,但之後嘗試擷取該群組的報表資料時,傳回未經授權的錯誤。 -
YouTube Analytics API 的
groups.list
方法現在支援分頁功能。如果 API 回應不含所有可用的群組,則回應的nextPageToken
參數會指定可用於擷取下一頁結果的權杖。請將方法的pageToken
參數設為該值,以擷取其他結果。 -
YouTube Analytics API 現已支援
redPartnerRevenue
指標,可記錄所選的報表維度透過 YouTube Red 訂閱賺取的總收益。這項指標的值代表來自音樂和非音樂內容的收益,系統會在月底調整。我們更新了 YouTube Analytics API 的內容擁有者報表清單,以找出支援
redPartnerRevenue
指標的影片報表: -
現在 YouTube Analytics API 的熱門影片報表定義顯示,這份報表也支援下列收益指標:
earnings
、adEarnings
、grossRevenue
、monetizedPlaybacks
、playbackBasedCpm
、impressions
和impressionBasedCpm
。 -
我們已修正 YouTube Reporting API
date
維度的說明文件,以反映從太平洋時間凌晨 12 點 (UTC-8) 開始的 24 小時期間。先前的說明文件指出此日期是從上午 12 點 (GMT) 開始。此外,YouTube Analytics API 說明文件也已更新,請注意,所有日期相關維度 (
day
、7DayTotals
、30DayTotals
和month
) 都是指從太平洋時間凌晨 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
資源的startTime
、endTime
和createTime
屬性定義全部已修正,請注意屬性值的準確度是毫秒,而非奈秒。此外,所有定義現在都準確反映屬性值為時間戳記。 -
YouTube Analytics API
sharingService
維度的說明文件已更新,加入可能的維度值清單。這份清單中列出許多新支援的服務,YouTube Reporting API
sharing_service
維度的定義也已更新,以列出新支援的值。大於59
的列舉值是清單中的新值。 -
新版 YouTube Reporting API 可擷取大量資料報表,當中含有頻道或內容擁有者的 YouTube 數據分析資料。這種設計適用於能夠匯入大型資料集的應用程式,並且提供篩選、排序及挖掘資料的工具。
每份 YouTube Reporting API 報表都包含一組預先定義的維度和指標。(YouTube Analytics API 報表也會使用指標和維度)。在報表中,每一列的資料都有不重複的維度值組合。您可以根據維度值匯總不同資料列的資料,計算個別影片、國家/地區、直播影片、訂閱使用者等指標的指標。
您可以使用 API 安排報表工作,每個工作都能指明 YouTube 應產生的報表。設定好工作後,YouTube 就會產生每日可非同步下載的報表。每份報表包含不重複 24 小時期間的資料。
-
雖然這兩種 API 各不相同,但透過 YouTube Analytics API 和 YouTube Reporting API,開發人員都能擷取 YouTube 數據分析資料。由於這兩種 API 都提供了類似資料集的存取權,因此這兩個 API 的說明文件正以一組說明文件的形式發布。
-
我們將 API 說明文件重新編排,讓 API 更易於理解。因此,這些變更並未描述新功能:
-
說明文件現在會包含一個頁面,列出所有可用的頻道報表,以及一份列出所有適用的內容擁有者報表。舊版說明文件分為頻道影片報表、頻道播放清單報表等各頁面,
-
新的資料模型總覽旨在更清楚說明 API 的運作方式。具體而言,本文會詳細說明 YouTube 如何使用指標、維度和篩選器來計算報表值。
-
API 用來擷取報表的
reports.query
方法現在會分開記錄。該網頁的資訊原本出現在其他網頁上。方便您更輕鬆地識別擷取報表時所需的資訊。
-
-
新的「
adEarnings
」指標包含 Google 售出的所有廣告來源預估總收益 (淨收益)。這不是核心指標。這個 API 支援任何已支援earnings
指標的報表,以使用adEarnings
指標。此外,我們已修正
earnings
指標的定義,以反映該指標的值包含所有 Google 售出及非廣告來源的預估總收益。先前的定義無法正確指出該指標只納入來自廣告來源的收益。 -
「
primaryAdGrossRevenue
」指標已淘汰。請改用grossRevenue
指標擷取收益資料。 -
除了已淘汰的
primaryAdGrossRevenue
指標外,廣告成效報表也不再支援monetizedPlaybacks
和playbackBasedCpm
指標。不過,部分影片報表仍會支援這些指標。 -
API 現在支援
videosAddedToPlaylists
和videosRemovedFromPlaylists
這兩種影片報表的新指標。頻道和內容擁有者的影片報表清單也已更新,以找出支援新指標的報表。videosAddedToPlaylists
:符合查詢範圍內的影片加入任何 YouTube 播放清單的次數。這些影片可能會新增至影片擁有者的播放清單,或是其他頻道的播放清單。videosRemovedFromPlaylists
:符合查詢範圍內的影片從任何 YouTube 播放清單移除的次數。這些影片可能從影片擁有者的播放清單或其他頻道的播放清單中移除。
這兩種指標都有預設播放清單,例如「稍後觀看」播放清單。但不會計入影片自動加入的播放清單,例如頻道的上傳內容播放清單,或是使用者的觀看記錄。同時請注意,這些指標反映的是新增和刪除的絕對次數。因此,如果使用者將影片加入播放清單,之後又將影片加入播放清單,接著再又將該影片加入播放清單,則指標會顯示該影片已新增至兩個播放清單,並從一個播放清單中移除。
這些指標的資料涵蓋 2014 年 10 月 1 日。
-
自這項公告起,
favoritesAdded
和favoritesRemoved
指標現已淘汰。這些都是核心指標,並受到服務條款中列載的《廢止政策》規範。 -
新的
currency
參數可讓您以美元 (USD
) 以外的貨幣擷取收益指標。如果設定參數,API 會將earnings
、grossRevenue
、playbackBasedCpm
和impressionBasedCpm
指標的值轉換為指定貨幣。傳回的值是根據每日變動的匯率計算而得。參數值是由 3 個字母組成的 ISO 4217 貨幣代碼,預設值為
USD
。 參數定義內含支援貨幣代碼的清單。 -
API 現在支援建立及管理 YouTube 數據分析群組,以及擷取這些群組的報表資料。
-
建立及管理群組
本次更新推出了用來建立及管理群組的
group
和groupItem
資源。group
資源代表 Analytics (分析) 群組,這是內含多達 200 個頻道、影片、播放清單或資產的自訂集合。API 支援這項資源的list
、insert
、update
和delete
方法。groupItem
資源代表 Analytics (分析) 群組中的一個項目。API 支援這項資源的list
、insert
和delete
方法。
舉例來說,您可以使用
groups.insert
方法建立一個群組,然後使用groupItems.insert
方法將商品新增至該群組。 -
擷取群組的報表資料
維度說明文件已更新,加入「
group
」維度,可用於篩選許多頻道報表和內容擁有者報表。使用group
篩選器時,API 會傳回該群組中所有項目的資料。請注意,這個 API 目前不支援建立素材資源群組報表。
如要進一步瞭解 YouTube 數據分析群組,請參閱 YouTube 說明中心。
-
-
API 不再支援
show
維度。 -
如果將
video
、playlist
、channel
和show
維度當做篩選器使用,API 現在可以支援為這些維度指定多個值。若要指定多個值,請將filters
參數值設為以半形逗號分隔的清單,列出應篩選 API 回應的影片、播放清單、頻道或節目 ID。參數值最多可指定 200 個 ID。如果為同一個篩選器指定多個值,也可以將該篩選器加入您為要求指定的維度清單。即使該篩選器未列為特定報表支援的維度也是如此。如果您在維度清單中加入篩選器,API 也會使用該篩選器值將結果分組。
如需這項功能的完整詳細資料,請參閱
filters
參數定義。 -
擷取管道報表時,您可以將
ids
參數的值設為channel==MINE
,藉此擷取已驗證使用者的管道資料。(您也可以將ids
參數設為channel==CHANNEL_ID
,即可擷取指定管道的資料)。 -
API 現已支援播放清單報表,其中包含播放清單內影片觀看次數的相關統計資料。頻道和內容擁有者皆可使用播放清單報表。
所有播放清單報表均支援
views
和estimatedMinutesWatched
指標,有些報表也支援averageViewDuration
指標。此外,所有播放清單報表均支援下列新指標。請注意,這些指標只會反映網路上的播放清單觀看次數。
playlistStarts
:觀眾主動播放某個播放清單的次數。viewsPerPlaylistStart
:播放清單開始播放時的平均影片觀看次數。averageTimeInPlaylist
:播放清單開始播放後,觀眾觀看播放清單中影片的預估平均時間 (以分鐘為單位)。
要求擷取播放清單報表的任何要求都必須使用
isCurated
篩選器,且必須設為1
(isCurated==1
)。 -
這個 API 現在支援觀眾續看率報表。這份報表會評估影片留住觀眾的能力。報表的新「
elapsedVideoTimeRatio
」維度可用於評估對應指標值完成的影片長度:-
audienceWatchRatio
指標會識別影片中指定時間點觀看影片的觀眾絕對比率。這個比例的計算方式是比較影片中特定片段的觀看次數與影片的總觀看次數。請注意,如果影片中的片段在特定影片觀看次數中重複播放 (也可能完全不觀看),舉例來說,如果使用者倒轉和觀看某部影片的相同片段,該影片的絕對比例可能會大於
1
。 -
與所有片長相近的 YouTube 影片相比,「
relativeRetentionPerformance
」指標會顯示影片在播放期間,觀眾的留存率。如果這個值為 0,代表影片留住觀眾的成效低於其他長度相近的影片,而值 1 表示與其他長度類似的影片相比,影片留住觀眾的成效較佳。中位數值為 0.5 代表長度相近的影片中,有半數的影片留住觀眾成效較佳,而另一半則留住觀眾。
您也可以使用
audienceType
篩選器,讓報表只傳回自然觀看次數、TrueView 串流內廣告觀看次數或 TrueView 多媒體廣告的觀看次數相關的資料。(自然觀看是指使用者採取動作的直接結果,例如搜尋影片或點選推薦影片)。 -
-
API 支援數種與註解相關的新指標。只要是先前支援
annotationClickThroughRate
和annotationCloseRate
指標的報表,都可以擷取下列指標。annotationImpressions
:註解曝光總數。annotationClickableImpressions
:已顯示且可點擊的註解數量。annotationClosableImpressions
:已顯示且可關閉的註解數量。annotationClicks
:點選的註解總數。annotationCloses
:關閉註解的總數。
所有新指標都是核心指標,受廢止政策的規範。不過請注意,新版指標的資料將從 2013 年 7 月 16 日起提供。(系統提供 2012 年 6 月 10 日起的
annotationClickThroughRate
和annotationCloseRate
指標資料)。 -
「
GOOGLE_SEARCH
」的insightTrafficSourceType
維度不再回報為獨立值。系統現在會將 Google 搜尋結果的參照連結網址歸給EXT_URL
流量來源類型。因此,您無法再擷取將insightTrafficSourceType
篩選器設為GOOGLE_SEARCH
的insightTrafficSourceDetail
報表。 -
內容擁有者報告文件已更新,說明現在內容擁有者可針對內容擁有者聲明版權或上傳的內容,擷取
subscribersGained
和subscribersLost
指標。這項異動會顯示在內容擁有者的第一份基本統計資料報表中,現在支援
claimedStatus
和uploaderType
篩選器。 -
申請範例文件經過重新設計,將範例分門別類,採用與頻道和內容擁有者報告相同的分頁格式。在新版設計中,範例會分為以下幾個類別:
- 基本統計資料
- 根據時間
- 地理區域
- 播放位置
- 流量來源
- 裝置/作業系統
- 客層
- 社群媒體
- 收益/廣告 (僅適用於內容擁有者報表)
-
申請範例文件現在提供在頻道報表或內容擁有者報表中擷取州/省專屬資料的新示例。
-
美國各州和華盛頓特區的州專屬指標:這份報表會擷取各州/省的細分資料,包括頻道影片的觀看次數和其他統計資料。這些資料涵蓋美國各州和華盛頓特區。此範例使用
province
維度,並使用filters
參數限制回應中只包含美國的結果。 -
加州觀眾客層 (年齡層和性別):這份報表會擷取美國加州觀眾年齡層與性別的統計資料。如果是內容擁有者已聲明版權的內容,這份報表也會擷取這類觀眾的統計資料。此範例使用
filters
參數,確保回應僅包含特定省份的資料。
-
-
我們已更新
province
維度的定義,請注意,如果dimensions
參數值包含province
,要求也必須在filters
參數值中加入country==US
,將資料限制為美國。 -
我們重新設計了支援頻道和內容擁有者報表的文件,每份文件不會提供列出所有可用報表的表格,而是將報表分類成不同類別:
- 基本統計資料
- 根據時間
- 地理區域
- 播放位置
- 流量來源
- 裝置/作業系統
- 客層
- 社群媒體
- 熱門影片
每份文件會以分頁清單的形式顯示這些類別,只要按一下任一分頁標籤,即可查看該類別支援的報表。
-
API 現在支援三種新的地理區域維度:
province
、continent
和subContinent
。-
province
維度可讓您擷取美國各州和哥倫比亞特區的統計資料。這個 API 支援兩種維度用途: -
subContinent
維度會指定聯合國 (UN) 統計區碼,用來識別洲別的子區域。這個維度也只能當做篩選器使用。由於每個子區域都只與一個洲別相關聯,因此在使用
subContinent
篩選器時不必同時使用continent
篩選器。(事實上,如果請求同時使用兩個維度,API 就會傳回錯誤)。
-
-
說明文件已經修正,因此
insightTrafficSourceDetail
維度不會將insightTrafficSourceType
值PROMOTED
當做有效的篩選器值。 -
現在起,使用 YouTube Analytics API 時,必須遵守《服務條款》中所述的廢止政策。不過,此 API 的非核心維度和非核心指標不適用「廢止政策」。維度和metrics頁面已更新,以列出核心維度和指標。此外,這些網頁的定義也已更新,可明確識別核心維度和指標。
-
API 現在支援使用
EXTERNAL_APP
做為insightPlaybackLocationType
維度的值。為配合這項更新,自 2013 年 9 月 10 日起,播放次數將不再歸類為MOBILE
播放次數,不過在該日期前透過行動裝置播放的次數仍會歸類到這個值。本次更新後,行動播放次數現已分為
WATCH
、EMBEDDED
或EXTERNAL_APP
播放,視播放的應用程式類型而定。 -
API 現在支援使用
PLAYLIST
做為insightTrafficSourceType
維度的值。這個值代表影片觀看次數來自播放清單。這些資料檢視先前會使用維度的YT_OTHER_PAGE
類別進行分類。 -
API 現在可以按照多種維度和指標排序報表。範例請求文件包含「按多個維度/指標排序要求」這個新範例,以便示範這項功能。該要求會擷取流量來源資料,且
sort
參數值為day,-views
。結果會按照時間順序排序,但在每天的結果集中,第一列包含產生最多觀看次數的流量來源資料,第二列則包含產生觀看次數次高的來源資料,依此類推。 -
API 現已支援兩個新維度:
deviceType
和operatingSystem
,可用於擷取觀眾觀看影片的裝置相關資料。API 支援使用一或兩種維度的報表。-
deviceType
報表可讓您擷取不同裝置 (電腦、手機和平板電腦) 的觀看次數和預估觀看時間。您也可以使用operatingSystem
篩選器,限制裝置類型報表,僅顯示搭載特定作業系統 (例如 Android 或 iOS) 的裝置的統計資料。 -
operatingSystem
報表可讓您擷取不同作業系統 (例如 Android、iOS、Linux 等) 的觀看次數和預估觀看時間。您也可以使用deviceType
篩選器,限製作業系統報表,僅列出特定裝置類型 (例如行動裝置或平板電腦) 的統計資料。
-
-
要求範例文件已更新,提供三種頻道裝置的三種裝置報表,以及內容擁有者適用的 3 部裝置報告。
-
insightPlaybackLocationType
維度可能會傳回YT_OTHER
值,該值可識別未使用該維度其他值進行分類的檢視畫面。 -
內容擁有者報表文件已更新,現在您可依收益遞減排序成效最佳的影片報表,找出收益最高的影片。這份報表是「使用者活動和收益報表」部分的第二個表格。
-
YouTube 不會再識別實驗性 API 功能和服務。不過,我們現在提供一份清單,列出受廢止政策的 YouTube API 清單。
-
這個 API 現在可以擷取觀看時間指標 (
estimatedMinutesWatched
、averageViewDuration
和averageViewPercentage
) 搭配其他指標的功能,包括觀看指標、參與度指標、收益指標和廣告成效指標。我們更新了可用的頻道報表和內容擁有者報表清單,以反映這項異動。(由於系統會擷取觀看時間指標來當做其他報表的一部分,因此上述清單現在已變短了)。
範例 API 要求文件也已更新。
-
使用
insightPlaybackLocationDetail
和insightTrafficSourceDetail
維度的報表已透過下列方式強化:-
這些 API 現在支援選用的
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
-
-
-
新的「API 要求範例」文件提供範例,示範如何使用 YouTube Analytics API 擷取多種不同類型的報表。每個範例均包含要求擷取的報表簡短說明,然後顯示該要求的維度、指標、篩選器和排序參數。
-
insightTrafficSourceType
維度現在支援SUBSCRIBER
為有效值。這個值代表來自 YouTube 首頁動態消息或 YouTube 訂閱功能的影片觀看次數。如果根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位會指定首頁動態消息,或是其他引人瀏覽的網頁。 -
這個 API 目前支援
annotationClickThroughRate
和annotationCloseRate
兩項新指標,這些指標與觀眾在影片中播放註解的互動情形有關。頻道報表和內容擁有者報表清單也已更新,以找出支援新指標的報表。annotationClickThroughRate
:觀眾點按註解與可點擊註解曝光總數的比例。annotationCloseRate
:觀眾關閉註解的次數與註解曝光總數的比率。
-
API 現在支援收益、廣告成效指標,以及新的廣告成效報表。只有參與 YouTube 合作夥伴計畫的 YouTube 內容合作夥伴才能存取這些指標和報表。
-
YouTube 新支援的報表支援廣告成效指標和曝光次數相關成效指標。如要進一步瞭解廣告成效報表,請參閱內容擁有者報表說明文件。
-
以下列出最新支援的指標。我們更新了內容擁有者報表清單,以便識別支援這些指標的報表,其中包括支援這些指標的兩份新報表。
earnings
- 所有 Google 銷售廣告來源的預估總收益。grossRevenue
- 來自 Google 或 DoubleClick 合作夥伴的預估總收益。primaryAdGrossRevenue
- Google 或 DoubleClick 合作夥伴針對報表涵蓋的影片,在主要廣告類型下方顯示預估收益,並按主要廣告類型分類。monetizedPlaybacks
:顯示至少一次廣告曝光的播放次數。playbackBasedCpm
- 每千次播放次數的預估總收益。impressions
- 已驗證的廣告曝光次數。impressionBasedCpm
- 每千次廣告曝光的預估總收益。
注意:詳情請參閱指標定義。
-
凡是擷取收益或廣告成效指標的請求,都必須傳送使用新的
https://www.googleapis.com/auth/yt-analytics-monetary.readonly
範圍授予存取權的授權權杖。
-
-
API 的參考指南現在有範例章節,其中包含程式碼範例,示範如何使用 Java、JavaScript、Python 和 Ruby 用戶端程式庫呼叫 API。JavaScript 程式碼範例與範例應用程式說明文件中提及的範例相同。
-
API 參考指南現在包含 APIs Explorer,可讓您呼叫 API、查看 API 要求,以及擷取回應中的實際資料。
-
這個 API 支援多種適用於頻道和內容擁有者的新報告,說明如下。每份報表均可做為頻道報表或內容擁有者報表使用。維度和metrics頁面也隨之更新。
-
播放位置報表會顯示不同類型網頁或應用程式的影片觀看次數。
-
播放位置詳細報表會列出為指定影片產生最多觀看次數的嵌入式播放器。與播放位置報表相比,這個模式可找出熱門嵌入式播放器的相關網址,提供更精細的檢視畫面。
-
流量來源報表會指出來自不同類型參照網址的影片觀看次數。
-
「流量來源詳細資料」報表會找出為特定影片和指定流量來源類型產生最多觀看次數的參照網址。舉例來說,這份報表會列出為特定影片帶來最多流量的相關影片。這份報表支援多個流量來源。
-
「觀看時間」報表會顯示觀眾收看內容的時間。這項功能可以彙整特定時間範圍 (一天、過去 7 天、過去 30 天等) 或國家/地區的資料。如果報表根據日期或國家/地區匯總資料,也可以指出每次觀看影片的平均長度,以及使用者觀看影片的平均百分比。
-
-
YouTube Analytics API 現已開放所有開發人員使用。您可以在 APIs console 的「Services」面板中為專案啟用 API,而不必先要求存取權。
-
新的「瞭解配額用量」一節提供最佳化 API 配額用量的指南。API 伺服器會計算每項要求的查詢費用,並從您的 API 用量配額中扣除這筆費用。由於不同類型的報表可能會有極大的差異,因此建議您規劃有效使用配額的規劃,且應用程式僅應要求自己實際需要的指標和資料。
-
「暫時維度」部分已更新,說明這些維度代表 Analytics (分析) 報表應根據時間範圍匯總資料。API 目前支援下列額外的時間維度:
7DayTotals
- 系統會匯總報表中的資料,讓每列包含七天的資料。30DayTotals
- 系統會匯總報表中的資料,讓每一列包含 30 天的資料。month
– 報表中的資料會按日曆月份匯總。
同樣地,可用報表一節也已更新,以反映 API 對使用這些維度報表的支援。
-
我們更新了報表實體維度一節,請注意,擷取內容擁有者報表的 API 要求必須使用其中一個維度 (
video
、channel
或show
),或系統支援的claimedStatus
和uploaderType
維度組合來篩選資料。 -
API 現已支援兩種熱門影片報表排序選項。這些報表是以頻道報表或內容擁有者報表的形式提供,包含觀看次數、留言數和喜歡次數等以國家/地區為單位的指標,並且依影片細分這些指標。你現在可以根據影片的觀賞頁面訂閱或取消訂閱頻道的使用者人數,為這類報表排序。
-
我們更新了
subscribersGained
和subscribersLost
metrics的定義,說明頻道在多個位置的訂閱人數 (包括影片觀賞頁面、頻道頁面及 YouTube 首頁上的導覽指南) 的表現會有所更新。當這些指標出現在影片專屬報表中時,只會納入指定影片觀賞頁面的統計資料。
YouTube Reporting API 支援三種新的片尾報表,以及這類報表的新維度和指標。這些報表會針對影片停止播放後顯示的片尾,提供曝光次數和點閱率統計資料。
如要進一步瞭解如何為影片新增片尾,請參閱 YouTube 說明中心。
2016 年 11 月 8 日
本次更新對 YouTube Analytics API 進行了下列變更:
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 日
這次更新的修改如下:
2016 年 8 月 10 日
本次更新包含以下變更:
2016 年 7 月 18 日
本次更新包含以下變更:
2016 年 6 月 28 日
為了支援許多頻道和內容擁有者報表中的資訊卡指標,我們更新了 YouTube Analytics API 說明文件。新支援的指標如下:
以下類型的報表支援這些指標:
2016 年 6 月 22 日
本次更新內含下列 YouTube Reporting API 異動。第一項變更與 API 大致有關,其餘變更只會影響內容擁有者報表:
2016 年 5 月 19 日
本次更新內含以下 YouTube Reporting API 異動:
2016 年 4 月 12 日
本次更新包含以下變更,這些異動只會影響 YouTube Reporting API:
2016 年 3 月 28 日
YouTube Reporting API 和 YouTube Analytics API 現在會傳回多項額外分享服務的檢視統計資料。
2016 年 3 月 16 日
本次更新包含下列變更,會對 YouTube Reporting API 和 YouTube Analytics API 產生影響:
YouTube Reporting API
YouTube Analytics API
2016 年 2 月 8 日
我們更新了 YouTube Analytics API 支援的指標清單,因此資訊卡指標不再列為該 API 支援的指標。(該 API 的報表皆未記錄為任何資訊卡指標)。
請注意,您還是可以使用 YouTube Reporting API 擷取資訊卡指標。YouTube Reporting API 支援許多頻道和內容擁有者報表的這些指標。
2016 年 1 月 6 日
YouTube Reporting API 和 YouTube Analytics API 現在都能明確識別透過 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:
2015 年 11 月 10 日
這次更新的修改如下:
2015 年 10 月 29 日
這次更新的修改如下:
2015 年 10 月 8 日
這次更新的修改如下:
2015 年 9 月 24 日
這次更新的修改如下:
2015 年 8 月 20 日
這次更新的修改如下:
2015 年 7 月 22 日
本次更新包含幾項變更,且所有變更僅適用於內容擁有者:
2015 年 6 月 1 日
這次更新的修改如下:
2015 年 3 月 31 日
這次更新的修改如下:
2015 年 3 月 16 日
這次更新的修改如下:
2015 年 2 月 25 日
這次更新的修改如下:
2015 年 2 月 13 日
這次更新的修改如下:
2014 年 8 月 28 日
這次更新的修改如下:
2014 年 7 月 16 日
這次更新的修改如下:
2014 年 1 月 31 日
這次更新的修改如下:
2014 年 1 月 16 日
這次更新的修改如下:
2014 年 1 月 6 日
這次更新的修改如下:
2013 年 9 月 30 日
這次更新的修改如下:
2013 年 7 月 16 日
這次更新的修改如下:
2013 年 5 月 23 日
這次更新的修改如下:
2013 年 5 月 10 日
這次更新的修改如下:
2013 年 5 月 6 日
這次更新的修改如下:
2013 年 5 月 3 日
這次更新的修改如下:
2013 年 3 月 28 日
這次更新的修改如下:
2013 年 3 月 21 日
這次更新的修改如下:
2013 年 2 月 4 日
這次更新的修改如下:
2012 年 11 月 14 日
這次更新的修改如下:
2012 年 10 月 2 日
這次更新的修改如下:
2012 年 9 月 12 日
這次更新的修改如下: