本文說明 YouTube Analytics API 支援的維度。這個 API 可支援即時目標查詢產生 YouTube 數據分析自訂報表。
維度是彙整資料的常見條件,例如使用者活動發生的日期或使用者所在的國家/地區。
每份查詢報表都會列出支援的維度。舉例來說,當您按時間擷取使用者活動時,您可以選擇要回報資料的時間範圍:天或月。在任何報表中,每列資料都有一組不重複的維度值組合。
如要擷取查詢報表,請呼叫 YouTube Analytics API 的 reports.query
方法。在要求中使用 dimensions
參數,指定 YouTube 在報表中計算指標值的維度。
核心維度
雖然 YouTube Analytics API 受《服務條款》中定義的「廢止政策」規範,但非核心維度 (和非核心指標) 則不受政策規範。在此網頁的定義中,任何以核心維度為主的維度都會明確辨識,
以下清單列出 API 的核心維度。
詳情請參閱受到廢止政策影響的 YouTube API 清單。
篩選器
所有查詢報表都支援篩選器。篩選器會識別擷取資料集中必須存在的維度值。因此,這些參數會限制 API 回應,僅納入符合特定值或一組值的資料。舉例來說,您可以使用篩選器只擷取特定國家/地區的資料,而不要擷取所有國家/地區的使用者活動指標。
在擷取查詢報表的要求中,選用的 filters
請求參數會指定您要篩選資料的維度值。舉例來說,如要擷取歐洲的使用者活動指標,請將 filters
參數值設為 continent==150
。
重要事項:擷取內容擁有者報表的 API 要求時,必須使用其中一個報表實體維度或支援的 claimedStatus
和 uploaderType
維度組合篩選資料。
尺寸
以下各節將定義 YouTube Analytics API 查詢報表中使用的維度。除非另有註明,否則這些維度會同時用於「頻道」和「內容擁有者」報表。此外,系統也會找出只能當做篩選器使用的維度。
資源
這些維度與頻道和內容擁有者在 YouTube 上管理的資源相對應:
注意:當 video
、playlist
和 channel
維度做為篩選器使用時,API 可讓您指定多個值。方法是將 filters
參數值設為要篩選 API 回應的影片、播放清單或頻道 ID 清單 (以半形逗號分隔)。參數值最多可以指定 500 個 ID。
- 影片 (核心尺寸)
- YouTube 影片 ID。在 YouTube Data API 中,這是
video
資源的id
屬性值。This is a core dimension and is subject to the Deprecation Policy. - 播放清單
- YouTube 播放清單的 ID。在 YouTube Data API 中,這是
playlist
資源的id
屬性值。 - 頻道 (核心維度) (僅適用於內容擁有者報表)
- YouTube 頻道 ID。在 YouTube Data API 中,這是
channel
資源的id
屬性值。This is a core dimension and is subject to the Deprecation Policy.
內容擁有者報表經常使用「channel
」維度,因為這類報表通常會匯總多個頻道的資料。 - 群組 (僅限篩選器)
- YouTube 數據分析群組的 ID。你可以使用 YouTube Analytics API 的
groups.list
方法擷取這個值。使用group
篩選器時,API 回應會包含該群組中所有影片、播放清單或頻道的資料。
範例
以下範例要求使用報表實體維度或篩選器:
頻道示例
內容擁有者範例
地理區域
這些維度會找出與使用者活動、廣告成效或預估收益指標相關聯的地理區域。
- country(核心維度)
- 與報表列中的指標相關聯的國家/地區。維度值是雙字母的 ISO-3166-1 國家/地區代碼,例如
US
、CN
(中國) 或FR
(法國)。國家/地區代碼ZZ
代表 YouTube 無法找出相關國家/地區的指標。This is a core dimension and is subject to the Deprecation Policy. - province
- 與報表列中的指標相關聯的美國州別或地域。維度值是 ISO 3166-2 代碼,用來識別美國各州或哥倫比亞特區,例如
US-MI
(密西根州) 或US-TX
(德州)。州/省代碼US-ZZ
代表 YouTube 無法識別相關美國州名的指標。 如果 API 要求在dimensions
參數值中加入province
,該要求也必須將資料限制為美國,方法是在filters
參數值中加入country==US
。注意:這個維度不支援用於識別美國外區域的 ISO 3166-2 值,因為這些地域也有專屬的 ISO 3166-1 國家/地區代碼。也不支援美國以外國家/地區的細分區域。
- city
- 與報表列中的指標相關聯的預估城市。這個維度的資料提供自 2022 年 1 月 1 日起的資料。
- 洲別 (僅限篩選器)
-
聯合國 (UN) 統計區碼。這個 API 支援下列值:
值 002
非洲 019
美洲 (北美、拉丁美洲、南美洲和加勒比海) 142
亞洲 150
歐洲 009
大洋洲 filters
參數的值設為continent==REGION_CODE
,並在上方清單中指定REGION_CODE
值。 - subContinent(僅限篩選器)
-
用來識別地理區域子區域的聯合國統計區碼。「聯合國統計資料部門」會列出子區域,以及與各個地區相關聯的國家/地區。
這個維度只能用於篩選資料。如要使用這個維度,請將
filters
參數的值設為subContinent==REGION_CODE
,指定聯合國清單中的REGION_CODE
值。
範例
以下範例請求使用地理區域維度或篩選器:
頻道示例
內容擁有者範例
時間範圍
這些維度指示報表應根據時間範圍 (例如一天、一週或一個月) 匯總資料。startDate
和 endDate
要求參數可指定報表資料的時間範圍。請注意,報表實際傳回的資料是截至查詢提出時,請求中指定的所有指標為止。報表中的日期會以 YYYY-MM-DD
格式列出。
重要事項:所有日期是指從太平洋時間 (UTC-7 或 UTC-8) 開始到太平洋時間 (UTC-7 或 UTC-8) 開始及結束於太平洋時間晚上 11:59 的時間範圍。因此,日光節約時間將時鐘調前的日期為 23 小時,而時鐘回溯的日期則為 25 小時的期間。
「月」維度是指太平洋時間 (UTC-7 或 UTC-8) 自指定月份和年度第一天凌晨 12 點開始 (UTC-7 或 UTC-8) 開始的時間範圍。
- 天 (核心維度)
- 使用這個維度時,系統會每天匯總報表中的資料,且每一列都包含一天的資料。您可以使用其他維度進一步細分資料,舉例來說,流量來源報表可根據使用者觸及影片的方式,匯總每日觀看統計資料。This is a core dimension and is subject to the Deprecation Policy.
- 月 (核心維度)
- 報表中的資料會按月匯總。與每日報表一樣,您可以使用其他篩選器進一步區隔資料。報表中的日期會以
YYYY-MM
格式列出。
注意:如果您的 API 查詢使用month
維度,則start-date
和end-date
參數都必須設為當月第一天。This is a core dimension and is subject to the Deprecation Policy.
範例
以下範例要求使用時間維度或篩選器:
頻道示例
內容擁有者範例
播放位置
這些維度提供使用者活動發生的網頁或應用程式深入分析。
- insightPlaybackLocationType
-
報表中的資料是根據影片播放的網頁或應用程式類型匯總。這個維度可能的值包括:
-
BROWSE
:這類資料描述的觀看次數是在 YouTube 首頁/主畫面、使用者的訂閱內容動態消息或其他 YouTube 瀏覽功能中。 -
CHANNEL
- 資料說明頻道頁面的觀看次數。 -
EMBEDDED
:這是指透過嵌入<iframe>
或<object>
嵌入影片的其他網站或應用程式中,累積的觀看次數。 -
EXTERNAL_APP
- 此資料會針對使用<iframe>
或<object>
嵌入以外方法播放影片的第三方應用程式中所產生的觀看次數。舉例來說,在使用 YouTube Android Player API 的應用程式中,播放內容會按照這個值分類。 -
MOBILE
:這項資料是針對在 YouTube 行動版網站或已核准的 YouTube API 用戶端 (包括行動裝置) 上產生的觀看次數。2013 年 9 月 10 日起,YouTube 數據分析報表不再將播放歸類為
MOBILE
播放次數。舊資料仍屬於該類別,因此還是可能在報表中保留該值。不過,自該日起,行動播放次數可分為WATCH
、EMBEDDED
或EXTERNAL_APP
播放,具體取決於播放內容的應用程式類型。 -
SEARCH
:這類資料描述的是直接在 YouTube 搜尋結果網頁上獲得的觀看次數。 -
WATCH
:這類數據呈現的是在影片的 YouTube 觀賞頁面或 YouTube 官方應用程式 (例如 Android 版) 中累積的觀看次數。 -
YT_OTHER
:資料說明未以其他方式分類的檢視畫面。
-
- insightPlaybackLocationDetail
- 系統會根據玩家所在的網頁匯總資料。請注意,這份報表僅支援嵌入播放器所產生的觀看次數,而且可識別特定影片獲得最多觀看次數的嵌入式播放器。因此,它可以比播放位置報表提供更精細的資料檢視,找出與熱門嵌入式播放器相關聯的網址或應用程式。
範例
以下範例請求使用播放位置維度:
頻道示例
-
播放位置
- 不同播放位置的觀看次數和觀看時間
- 每日觀看次數和不同播放位置的觀看時間
- 前 10 名:為內嵌影片帶來最多觀看次數的第三方網站
- 來自不同播放位置的播放清單觀看次數和觀看時間
- 每日播放清單觀看次數,以及不同播放位置的觀看時間
-
播放位置
內容擁有者範例
-
播放位置
- 不同播放位置的觀看次數和觀看時間
- 每日觀看次數和不同播放位置的觀看時間
- 前 10 名:為內嵌影片帶來最多觀看次數的第三方網站
- 來自不同播放位置的播放清單觀看次數和觀看時間
- 每日播放清單觀看次數,以及不同播放位置的觀看時間
-
播放位置
播放詳細資料
- creatorContentType
- 這個維度找出與資料列中的使用者活動指標相關聯的內容類型。這項維度的資料提供 2019 年 1 月 1 日起的資料。
下表列出維度值:
值 LIVE_STREAM
觀看的內容是 YouTube 直播。 SHORTS
觀看的內容為 YouTube Shorts。 STORY
觀看的內容屬於 YouTube 短片故事。 VIDEO_ON_DEMAND
觀看的內容是不屬於其他維度值的 YouTube 影片。 UNSPECIFIED
瀏覽過的內容類型不明。 - liveOrOnDemand
- 這個維度代表資料列中的使用者活動指標是否與現場直播的觀看次數建立關聯。這項維度的資料提供 2014 年 4 月 1 日起的資料。
下表列出維度值:
值 LIVE
列的資料描述了現場直播期間的使用者活動。 ON_DEMAND
此列的資料描述了現場直播期間不發生的使用者活動。 - subscribedStatus
- 這個維度指出資料列中的使用者活動指標是否與訂閱影片或播放清單頻道的觀眾相關聯。
可能的值為
SUBSCRIBED
和UNSUBSCRIBED
。
請注意,維度值是使用者活動發生當下的準確資料。舉例來說,假設使用者尚未訂閱某個頻道,在觀看該頻道的影片後,又訂閱了該頻道,並觀看了另一部影片,且全都在同一天內完成。 管道報表指出有一項資料檢視的subscribedStatus
值為SUBSCRIBED
,而一項資料檢視的subscribedStatus
值為UNSUBSCRIBED
。 - youtubeProduct
- 這個維度會指出使用者活動發生在哪個 YouTube 服務,這個維度的資料可自 2015 年 7 月 18 日起提供。
下表列出維度值:
值 CORE
不在任何特殊 YouTube 應用程式 (YouTube Gaming、YouTube Kids 或 YouTube Music) 中的使用者活動。例外狀況: CORE
會包含 2021 年 3 月 1 日前在 YouTube Music 中發生的使用者活動。GAMING
使用者的活動發生在 YouTube Gaming 中。 KIDS
使用者活動發生在 YouTube Kids。 MUSIC
2021 年 3 月 1 日當天或之後,YouTube Music 中的使用者活動。2021 年 3 月 1 日前的資料會納入「 CORE
」。系統不會記錄即時資料。UNKNOWN
使用者活動發生在 2015 年 7 月 18 日之前。
流量來源
- insightTrafficSourceType
- 這份報表中的資料是根據參照網址類型匯總,可說明使用者觸及影片的方式。這個維度可能的值包括:
ADVERTISING
:觀眾透過廣告得知影片。如果您根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位會指出廣告類型。ANNOTATION
:觀眾點擊其他影片中的註解即可觀看影片。CAMPAIGN_CARD
- 這些觀看次數,來自已聲明版權的使用者上傳影片,可由內容擁有者宣傳已觀看的內容。這個流量來源僅適用於內容擁有者報表。END_SCREEN
:來自其他影片的片尾帶來的觀看次數。EXT_URL
- 影片觀看次數來自其他網站上的連結。如果您是根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位就會指出網頁。這個流量來源包括來自 Google 搜尋結果的參照連結網址。HASHTAGS
- 來自隨選影片主題標記頁面或 Shorts 主題標記探索頁面的觀看次數。LIVE_REDIRECT
- 影片觀看次數來自直播重新導向。NO_LINK_EMBEDDED
- 影片內嵌於其他網站。NO_LINK_OTHER
:YouTube 無法辨識流量的參照網址。這個類別涵蓋影片的直接流量和行動應用程式流量。NOTIFICATION
:影片觀看次數來自電子郵件或 YouTube 通知。PLAYLIST
:影片觀看次數來自播放清單,包括來自播放清單頁面的流量。PRODUCT_PAGE
- 影片觀看次數來自產品網頁。PROMOTED
:影片觀看次數來自非付費的 YouTube 宣傳活動,例如 YouTube「焦點影片」網頁。RELATED_VIDEO
:影片觀看次數來自其他影片觀賞頁面上的相關影片資訊。如果您根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位就會指定該影片的影片 ID。SHORTS
:在 Shorts 觀看體驗中,觀眾可以從上一部影片垂直滑動,藉此推薦觀眾。SOUND_PAGE
- 來自 Shorts 音效使用透視頁面的觀看次數。SUBSCRIBER
:影片觀看次數來自 YouTube 首頁的動態消息或 YouTube 訂閱功能。如果你是依據這個流量來源進行篩選,insightTrafficSourceDetail
欄位就會指定首頁動態消息項目或其他帶來觀看次數的網頁。YT_CHANNEL
:影片觀看次數來自頻道頁面。如果你根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位就會指定該頻道的頻道 ID。YT_OTHER_PAGE
:影片觀看次數是觀眾透過搜尋結果或 YouTube 網頁上的相關影片連結以外的連結而來。如果您是根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位就會指出該網頁。YT_SEARCH
:影片觀看次數來自 YouTube 搜尋結果。如果您是根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位就會指定搜尋字詞。VIDEO_REMIXES
:影片觀看次數來自 Shorts 播放器中的重混影片連結。如果您根據這個流量來源進行篩選,insightTrafficSourceDetail
欄位可指定觀眾是來自哪個影片。
- insightTrafficSourceDetail
- 這份報表的資料是依據為指定影片帶來最多觀看次數的參照網址和指定的流量來源類型彙整。以下清單列出可查看這份報表的流量來源。每個流量來源都會列出
insightTrafficSourceDetail
維度提供的資訊。ADVERTISING
:引導觀眾觀看的廣告類型。可能的值包括:- 隨點即播參與式廣告
- 參與式廣告
- Google 搜尋廣告
- 首頁影片廣告
- 保留的可略過的串流內廣告
- TrueView 搜尋結果廣告和多媒體廣告
- TrueView 串流內廣告
- 未分類的 YouTube 廣告
- 影片牆
CAMPAIGN_CARD
:引導觀眾前往報表中所指明影片的已聲明版權影片。END_SCREEN
:引導觀眾找到報表所指明影片的影片。EXT_URL
:引導觀眾找到影片的網站。HASHTAGS
:帶動觀看次數的主題標記。NOTIFICATION
:推薦流量的電子郵件或通知。RELATED_VIDEO
:引導觀眾前往報表中所涵蓋影片的相關影片。SOUND_PAGE
:帶來觀看次數的影片。SUBSCRIBER
:引導觀眾前往報表所涵蓋影片的首頁動態消息項目或 YouTube 訂閱功能。有效值如下:activity
- 首頁訂閱動態消息中的項目,來自非上傳與非社交的頻道活動,包括喜歡數、加入收藏、發布公告,以及加入播放清單。blogged
- 來自熱門網誌的連結在首頁訂閱動態消息中的項目所獲得的觀看次數。mychannel
:來自首頁所列其他動態消息項目的觀看次數,例如「喜歡的影片」、「觀看記錄」和「稍後觀看」等。podcasts
:源自 Podcast 到達網頁商品的觀看次數。sdig
- 來自訂閱更新電子郵件的觀看次數。uploaded
:來自首頁訂閱動態消息中的uploaded
項目觀看次數。/
:其他來自 YouTube 首頁的觀看次數。/my_subscriptions
:來自使用者在 YouTube 上我的訂閱內容頁面的觀看次數。
YT_CHANNEL
:觀眾觀看影片的頻道頁面。YT_OTHER_PAGE
:觀眾是透過管道找到影片的 YouTube 網頁。YT_SEARCH
:引導觀眾找到影片的搜尋字詞。VIDEO_REMIXES
:帶來觀看次數的影片。
範例
以下範例要求使用流量來源維度:
頻道示例
-
流量來源
- 所在國家/地區不同流量來源的觀看次數和觀看時間
- 不同流量來源的每日觀看次數和觀看時間
- 前 10 名:為影片帶來最多流量的 YouTube 搜尋字詞
- 前 10 名:為影片帶來最多流量的 Google 搜尋字詞
- 同一國家/地區不同流量來源的播放清單觀看次數和觀看時間
- 來自不同流量來源的每日播放清單觀看次數和觀看時間
-
流量來源
內容擁有者範例
-
流量來源
- 不同流量來源的觀看次數和觀看時間
- 不同流量來源的每日觀看次數和觀看時間
- 前 10 名:為影片帶來最多流量的 YouTube 搜尋字詞
- 前 10 名:為影片帶來最多流量的 Google 搜尋字詞
- 同一國家/地區不同流量來源的播放清單觀看次數和觀看時間
- 來自不同流量來源的每日播放清單觀看次數和觀看時間
-
流量來源
裝置
- deviceType
- 這個維度可指出觀看次數發生的裝置實體板型規格。
以下清單列出 API 會傳回資料的裝置類型。您也可以使用
deviceType
維度做為篩選條件,限製作業系統報表只包含特定裝置類型的資料。DESKTOP
GAME_CONSOLE
MOBILE
TABLET
TV
UNKNOWN_PLATFORM
- operatingSystem
- 這個維度可指出觀看次數發生的裝置軟體系統。
以下清單列出 API 傳回資料的作業系統。您也可以使用
operatingSystem
做為篩選條件,限制裝置類型報表只顯示特定作業系統的資料。ANDROID
BADA
BLACKBERRY
CHROMECAST
DOCOMO
FIREFOX
HIPTOP
IOS
KAIOS
LINUX
MACINTOSH
MEEGO
NINTENDO_3DS
OTHER
PLAYSTATION
PLAYSTATION_VITA
REALMEDIA
SMART_TV
SYMBIAN
TIZEN
VIDAA
WEBOS
WII
WINDOWS
WINDOWS_MOBILE
XBOX
範例
以下範例要求使用裝置尺寸:
頻道示例
-
裝置/OS
- Android 作業系統的每日裝置類型指標
- 行動裝置的每日作業系統指標
- 每日作業系統和裝置類型指標
- Android 作業系統中播放清單觀看次數的每日裝置類型指標
- 行動裝置上播放清單觀看次數的每日作業系統指標
-
裝置/OS
內容擁有者範例
-
裝置/OS
- 已聲明版權影片的每日裝置類型指標
- 已聲明版權影片在行動裝置上播放的每日作業系統指標
- 每日作業系統和裝置類型指標
- Android 作業系統中播放清單觀看次數的每日裝置類型指標
- 行動裝置上播放清單觀看次數的每日作業系統指標
-
裝置/OS
客層
客層維度可協助您瞭解目標對象的年齡層和性別分佈情形。YouTube 說明中心提供「YouTube Analytics」報表中的客層資料額外資訊。
- ageGroup (核心維度)
- 這個維度可找出與報表資料相關聯的已登入使用者年齡層。該 API 使用的年齡層如下:
- age13-17
- age18-24
- age25-34
- age35-44
- age45-54
- age55-64
- age65-
- gender(核心維度)
- 這個維度可識別與報表資料相關聯的登入使用者的性別。
有效值為
female
、male
和user_specified
。 This is a core dimension and is subject to the Deprecation Policy.
範例
以下範例請求使用客層維度:
參與和內容分享
- sharingService(核心維度)
- 這個維度代表用於分享影片的服務。你可以使用「分享」按鈕,在 YouTube (或透過 YouTube 播放器) 分享影片。This is a core dimension and is subject to the Deprecation Policy.
下表列出有效的維度值:
分享服務 API 值 Ameba AMEBA
Android 電子郵件 ANDROID_EMAIL
Android Messenger ANDROID_MESSENGER
Android 訊息功能 ANDROID_MMS
Blackberry Messenger BBM
Blogger BLOGGER
複製到剪貼簿 COPY_PASTE
天世界 CYWORLD
迪格 DIGG
Dropbox DROPBOX
Embed EMBED
傳送電子郵件 MAIL
Facebook FACEBOOK
Facebook Messenger FACEBOOK_MESSENGER
Facebook 專頁 FACEBOOK_PAGES
福特卡 FOTKA
Gmail GMAIL
goo GOO
Google+ GOOGLEPLUS
傳送簡訊 GO_SMS
GroupMe GROUPME
Hangouts HANGOUTS
hi5 HI5
HTC 簡訊 HTC_MMS
Google 收件匣 INBOX
iOS 系統活動對話方塊 IOS_SYSTEM_ACTIVITY_DIALOG
KAKAO 的故事 KAKAO_STORY
Kakao (Kakao Talk) KAKAO
Kik KIK
LGE 電子郵件 LGE_EMAIL
折線圖 LINE
Linkedin LINKEDIN
LiveJournal LIVEJOURNAL
Menéame MENEAME
mixi MIXI
Motorola 訊息 MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
鄰近分享 NEARBY_SHARE
NUjij NUJIJ
Odnoklassniki (クдноклассники) ODNOKLASSNIKI
其他 OTHER
Pinterest PINTEREST
樂天 (市場匯率) RAKUTEN
reddit REDDIT
Skype SKYPE
摩洛哥 SKYBLOG
Sony Conversations SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
簡訊 TEXT_MESSAGE
Tuenti (Tuenti) TUENTI
tumblr. TUMBLR
Twitter TWITTER
不明 UNKNOWN
Verizon 訊息 VERIZON_MMS
Viber VIBER
VKontakte (がонтакте) VKONTAKTE
WeChat WECHAT
微博 WEIBO
WhatsApp WHATS_APP
威科普 WYKOP
Yahoo! 日本 YAHOO
YouTube Gaming YOUTUBE_GAMING
YouTube Kids YOUTUBE_KIDS
YouTube Music YOUTUBE_MUSIC
YouTube TV YOUTUBE_TV
詳情請參閱說明文件。
範例
以下範例請求使用社交維度:
觀眾續看率
- elapsedVideoTimeRatio
- 這個維度代表影片的已播放部分與影片長度的比率。留存率維度和指標是用於評估長期觀眾續看率,「
elapsedVideoTimeRatio
」維度則是時間測量結果。舉例來說,如果值為0.4
,表示對應的報表資料會在影片播放了 40% 後顯示續看率資料。
API 會為每支影片傳回 100 個資料點,比率值介於0.01
到1.0
之間。系統在影片播放期間,會以相同空間計算每個影片的資料。也就是說,如果是兩分鐘的影片,各資料點之間的間隔為 1.2 秒。不過,如果是兩小時的影片,則資料點之間的間隔為 72 秒。維度的值代表間隔的不含結尾。 - audienceType (僅限篩選器)
- 維度值會指出與報表資料相關聯的流量類型。
支援的值為
ORGANIC
、AD_INSTREAM
和AD_INDISPLAY
。 如需這些流量來源類型的說明,請參閱 YouTube 說明中心。
請注意,audienceType
篩選器的資料可於 2013 年 9 月 25 日開始提供。如果查詢是透過篩選器嘗試擷取較早日期的資料,API 不會傳回其資料。凡是未使用篩選器的查詢,在 2008 年 7 月 1 日後才會開始運作。
範例
以下範例要求使用觀眾續看率維度:
廣告成效
- adType
- 廣告成效報表會使用
adType
維度,並根據影片播放期間放送的廣告類型匯總要求的指標。以下清單說明可能的維度值。如要進一步瞭解 YouTube 廣告格式,請參閱 YouTube 說明中心。
-
auctionBumperInstream
- 不可略過的影片廣告,透過競價刊登,最長 6 秒。觀眾必須先看完這段廣告,才能觀賞影片。 -
auctionDisplay
:顯示在影片播放器底部的重疊廣告、影片觀賞頁面中的 300x250 廣告單元,或兩者並用。疊加層執行時,會在顯示一段時間後自動關閉,而使用者也可以關閉疊加層。如果同時顯示重疊廣告和橫幅廣告,系統會將每則廣告計為一次曝光。 -
auctionInstream
- 在主要影片開始前、播放中或結束後放送的不可略過影片廣告。 -
auctionTrueviewInslate
- 觀眾從影片開始前的一系列影片廣告中挑選一則影片廣告。See the TrueView documentation for more information. -
auctionTrueviewInstream
- 在主要影片開始前或播放期間放送的可略過影片廣告。 詳情請參閱 TrueView 說明文件。 -
auctionUnknown
– 透過 AdWords 競價購買,但尚未分類為其他廣告類型的廣告。 -
reservedBumperInstream
- 不可略過的影片廣告,以保留方式販售,最長 6 秒。觀眾必須先看完這段廣告,才能觀賞影片。 -
reservedClickToPlay
:使用者必須按一下才能開始播放的影片廣告。只要廣告單元顯示隨點即播廣告單元,無論使用者是否啟動播放,系統都會記錄一次廣告曝光。這類廣告空間採預留方式出售。 -
reservedDisplay
:顯示在影片播放器底部的重疊廣告、影片觀賞頁面中的 300x250 廣告單元,或兩者並用。疊加層執行時,會在顯示一段時間後自動關閉,而使用者也可以關閉疊加層。如果同時顯示重疊廣告和橫幅廣告,系統會將每則廣告計為一次曝光。 -
reservedInstream
- 不可略過的影片廣告,將於主要影片開始前、播放中或結束後插播。 -
reservedInstreamSelect
-
reservedMasthead
- 首頁上的大型廣告,可含有影片和圖形元素。 -
reservedUnknown
:以預留方式銷售的廣告,且無法歸類到其他廣告類型。 -
unknown
– 我們無法分類這個廣告類型。
-
範例
以下報表範例報表會擷取廣告成效或收益指標:
頻道示例
-
收益/廣告
- 頻道收益和廣告成效指標
- 每日收益和廣告成效指標
- 特定國家/地區的收益和廣告成效指標
- 前 10 名:收益最高的影片
- 各種廣告類型的廣告成效指標
-
收益/廣告
內容擁有者範例
-
收益/廣告
- 已聲明版權內容的收益和廣告成效指標
- 每日收益和廣告成效指標
- 特定國家/地區的收益和廣告成效指標
- 前 10 名:收益最高的影片
- 各種廣告類型的廣告成效指標
-
收益/廣告
播放清單
- isCurated(僅限篩選器)
- 這個篩選器表示該要求會擷取播放清單中有關影片觀看次數的資料。所有播放清單報表都必須要有這個篩選器,且值必須設為
1
。
範例
所有擷取播放清單報表的要求範例都會使用 isCurated
篩選器。
內容擁有者維度
下列維度僅適用於內容擁有者報表。
- ClaimStatus(僅適用於內容擁有者報表)
- 這個維度可讓你指出 API 回應只能包含已聲明版權內容的指標。這個維度的唯一有效值是
claimed
。如果filters
參數將查詢限制為claimedStatus==claimed
,API 只會擷取已聲明版權內容的資料。「uploaderType
」維度定義中的表格詳述如何使用這個維度。
- 上傳工具類型 (核心維度)(僅適用於內容擁有者報表)
- 這個維度可讓你指明 API 回應是否應包含指定內容擁有者和/或第三方上傳內容的指標 (例如使用者上傳的影片)。有效值為
self
和thirdParty
。此為核心維度,受《廢止政策》規範。
下表列出claimedStatus
和uploaderType
維度支援的組合,這些組合皆用於filters
參數:
claimedStatus
值uploaderType
值說明 [未設定] 自己 針對內容擁有者上傳且未聲明版權的內容,擷取 YouTube 數據分析資料。 已聲明版權 [未設定] 針對內容擁有者或第三方上傳的已聲明版權內容,擷取相關資料。 已聲明版權 自己 針對內容擁有者上傳的已聲明版權內容擷取資料。 已聲明版權 thirdParty 針對第三方上傳的版權聲明內容擷取相關資料。
範例
許多內容擁有者報表範例 API 要求是搭配使用 claimedStatus
和 uploaderType
維度支援的組合來篩選資料。