Dimensions

本文件說明 YouTube Analytics API 支援的維度。這個 API 支援即時指定查詢，以產生自訂 YouTube 數據分析報表。

維度是常見的資料匯總條件，例如使用者活動發生的日期或使用者所在的國家/地區。

每份查詢報表都會指出支援的維度。舉例來說，如果您依據時間擷取使用者活動，可以選擇回報資料的時間範圍：天或月。在任何報表中，每列資料都有專屬的維度值組合。

如要擷取查詢報表，請呼叫 YouTube Analytics API 的 reports.query 方法。請在要求中使用 dimensions 參數來指定 YouTube 用於計算報表中的指標值的維度。

核心維度

雖然 YouTube Analytics API 適用於《服務條款》中定義的「淘汰政策」，但非核心維度 (和非核心指標) 不受政策影響。本頁定義會明確指明任何屬於核心維度的維度。

以下清單列出 API 的核心維度。

詳情請參閱受廢止政策適用的 YouTube API 清單。

濾鏡

所有查詢報表都支援篩選器。篩選器會找出擷取資料集必須含有的維度值。因此，這些 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 回應會包含該群組中所有影片、播放清單或頻道的資料。

示例

以下請求範例使用報表實體維度或篩選器：

  • 管道範例

    • 基本統計資料
      • 前 10 大 - 頻道觀看次數最多的影片
      • 10 大熱門 - 頻道觀看次數最多影片的註解點閱率
      • 特定播放清單的統計資料
      • 前 10 大 - 頻道觀看次數最多的播放清單
    • 地理位置
      • 前 10 大 - 特定國家/地區觀看次數最多的影片
      • 前 10 名 - 歐洲觀看次數最多的影片

  • 內容擁有者示例

    • 基本統計資料
      • 前 10 大 - 內容擁有者觀看次數最多的影片
      • 前 10 大 - 觀看次數最多的內容擁有者影片
      • 前 10 大 - 內容擁有者頻道觀看次數最多的影片
      • 10 大熱門 - 頻道觀看次數最多影片的註解點閱率
      • 前 10 大熱門 - 內容擁有者最常觀看的播放清單
    • 地理位置
      • 內容擁有者在歐洲境內觀看次數最多的 10 部 - 觀看次數最多的影片
      • 前 10 大熱門 - 美國觀看次數最多的播放清單

地理區域

這些維度會識別與使用者活動、廣告成效或預估收益指標相關的地理區域。

國家/地區 (核心維度)
與報表列中的指標相關聯的國家/地區。維度值是兩個字母的 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，指定 UN 清單中的 REGION_CODE 值。

示例

以下請求範例使用地理區域維度或篩選器：

  • 管道範例

    • 基本統計資料：頻道在特定國家/地區的觀看次數 (及更多)
    • 地理位置
      • 頻道影片在各國家/地區的觀看時間指標
      • 頻道影片在特定國家/地區的註解指標
      • 美國各州和華盛頓特區的州專屬指標
      • 頻道播放清單在各國家/地區的觀看時間指標
      • 前 10 大熱門 - 美國觀看次數最多的播放清單
    • 播放位置：每日觀看次數和來自不同播放位置的觀看時間
    • 流量來源：特定國家/地區不同流量來源的觀看次數和觀看時間
    • 客層：加州的觀眾客層 (年齡層和性別)
    • 熱門影片
      • 前 10 大 - 特定國家/地區觀看次數最多的影片
      • 前 10 名 - 歐洲觀看次數最多的影片

  • 內容擁有者示例

    • 基本統計資料：所有自行上傳影片在特定國家/地區的觀看次數 (及其他資料)
    • 地理位置
      • 特定國家/地區的觀看時間指標 (適用於自上傳的內容)
      • 特定國家/地區的註解指標 (適用於自上傳的內容)
      • 美國各州和華盛頓特區的州專屬指標
      • 內容擁有者播放清單在特定國家/地區的觀看時間指標
      • 前 10 大熱門 - 美國觀看次數最多的播放清單
    • 播放位置：每日觀看次數和來自不同播放位置的觀看時間
    • 客層：加州的觀眾客層 (年齡層和性別)
    • 熱門影片：內容擁有者在歐洲最熱門的 10 部影片
    • 收益/廣告成效：特定國家/地區的收益和廣告成效指標

時間範圍

這些維度指出報表應根據時間範圍 (例如一天、一週或一個月) 匯總資料。startDate 和 endDate 請求參數會指定報表所含資料的時間範圍。請注意，報表實際上會傳回截至查詢為止，要求中指明的所有指標都可供使用的資料。報表會以 YYYY-MM-DD 格式列出日期。

重要事項：所有日期是指太平洋時間的指定日子、月分和年分凌晨 12 點 (UTC-7 或 UTC-8) 結束到凌晨 11:59 的時間範圍。因此，日光節約時間向前調整時鐘的日期代表 23 小時制，而向後調整時鐘的日期代表 25 小時制。

「月」維度是指從太平洋時間指定月份第一天 12:00 開始的時間範圍 (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.

示例

以下請求範例使用暫時維度或篩選器：

  • 管道範例

    • 根據時間
      • 頻道影片的每日觀看時間指標
      • 頻道影片的每日註解指標
      • 頻道的每日播放清單觀看次數
    • 播放位置：每日觀看次數和來自不同播放位置的觀看時間
    • 流量來源：不同流量來源的每日觀看次數和觀看時間
    • 裝置/OS
      • Android 作業系統的每日裝置類型指標
      • 行動裝置的每日作業系統指標
      • 每日作業系統和裝置類型指標

  • 內容擁有者示例

    • 根據時間
      • 自上傳內容的每日觀看時間指標
      • 已聲明版權內容的註解指標
      • 內容擁有者的每日播放清單觀看次數
    • 播放位置：每日觀看次數和來自不同播放位置的觀看時間
    • 流量來源：不同流量來源的每日觀看次數和觀看時間
    • 裝置/OS
      • 已聲明版權影片的每日裝置類型指標
      • 在行動裝置上觀看已聲明版權影片的每日作業系統指標
      • 每日作業系統和裝置類型指標
    • 收益/廣告成效：每日收益和廣告成效指標

播放位置

您可以透過這些維度深入瞭解使用者活動的網頁或應用程式。

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 應用程式等官方 YouTube 應用程式的觀看次數。

  • 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 中進行活動。CORE 則納入 2021 年 3 月 1 日前的資料。系統不會記錄即時資料。
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
      • 已聲明版權影片的每日裝置類型指標
      • 在行動裝置上觀看已聲明版權影片的每日作業系統指標
      • 每日作業系統和裝置類型指標
      • Android 作業系統中的播放清單觀看次數每日裝置類型指標
      • 行動裝置上的播放清單觀看次數的每日作業系統指標

客層

客層維度有助於瞭解觀眾的年齡層和性別分佈情形。如要進一步瞭解 YouTube Analytics 報表中的客層資料，請造訪 YouTube 說明中心。

ageGroup (核心維度)
這個維度可識別與報表資料相關聯的登入使用者年齡層。API 使用下列年齡層：
  • age13-17
  • age18-24
  • age25-34
  • age35-44
  • age45-54
  • age55-64
  • age65-
This is a core dimension and is subject to the Deprecation Policy.
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
黑莓傳訊器 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
男性 MENEAME
mixi MIXI
Motorola 訊息 MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
鄰近分享 NEARBY_SHARE
NUjij NUJIJ
Odnoklasniki (estдноклассники) ODNOKLASSNIKI
其他 OTHER
Pinterest PINTEREST
樂天 (天城) RAKUTEN
reddit REDDIT
Skype SKYPE
天空藍 SKYBLOG
Sony 會話 SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
簡訊 TEXT_MESSAGE
鐘乳石 TUENTI
tumblr. TUMBLR
Twitter TWITTER
不明 UNKNOWN
Verizon 訊息 VERIZON_MMS
Viber VIBER
VKontakte (hackerонтакте) 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 (僅限篩選器)
這個篩選器代表要求會擷取播放清單內發生的影片觀看次數相關資料。

示例

擷取播放清單報表的所有範例要求都會使用 isCurated 篩選器。

內容擁有者維度

只有內容擁有者報表支援以下維度。

重要事項：擷取內容擁有者報表的 API 要求必須使用下列其中一個維度來篩選資料：
  • video
  • channel
  • 支援 claimedStatus 和 uploaderType 維度組合，定義如下。
已聲明版權狀態 (僅適用於內容擁有者報表)
這個維度可讓你指明 API 回應只能包含已聲明版權內容的指標。這個維度的唯一有效值是 claimed。如果 filters 參數將查詢範圍限制為 claimedStatus==claimed，則 API 只會擷取已聲明內容的資料。透過「uploaderType」維度定義中的表格，進一步瞭解這個維度的使用方式。
上傳者類型 (核心維度) (僅適用於內容擁有者報表)
這個維度可讓你指明 API 回應是否應包含特定指標 (由指定內容擁有者和/或第三方上傳的內容) 的指標，例如使用者上傳的影片。有效值為 self 和 thirdParty。這是核心維度，必須遵守《廢止政策》。

下表顯示 claimedStatus 和 uploaderType 維度的支援組合，兩者皆用於 filters 參數：

claimedStatus 值 uploaderType 值 說明
[未設定] 自己 針對內容擁有者上傳且未聲明版權的內容擷取 YouTube 數據分析資料。
已聲明著作權 [未設定] 針對已聲明版權的內容 (由內容擁有者或第三方上傳) 擷取相關資料。
已聲明著作權 自己 針對內容擁有者上傳的版權內容擷取相關資料。
已聲明著作權 thirdParty 針對第三方上傳的版權內容擷取相關資料。

示例

內容擁有者報表的範例 API 要求中，有許多都使用支援的 claimedStatus 和 uploaderType 維度組合來篩選資料。