Dimensions

本文件定義 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 頻道和內容擁有者管理的資源相對應：

注意：這個 API 可讓您在使用 video、playlist 和 channel 維度時，指定多個值做為篩選器。方法是將 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」維度經常用於內容擁有者報表，因為這類報表通常會匯總多個頻道的資料。
group (僅限篩選器)
YouTube 數據分析群組的 ID。您可以使用 YouTube Analytics API 的 groups.list 方法擷取這個值。使用 group 篩選器時，API 回應會包含該群組中所有影片、播放清單或頻道的資料。

範例

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

  • 頻道範例

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

  • 內容擁有者範例

    • 基本數據
      • 前 10 名 - 內容擁有者觀看次數最多的影片
      • 前 10 名 - 內容擁有者觀看次數最多的影片
      • 前 10 名 - 內容擁有者頻道觀看次數最多的影片
      • 10 大 – 註解點閱率，頻道觀看次數最多的影片
      • 前 10 名 - 內容擁有者觀看次數最多的播放清單
    • 地理位置
      • 前 10 名 - 內容擁有者在歐洲觀看次數最多的影片
      • 前 10 名 - 美國最受歡迎的播放清單

地理區域

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

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 (德州)。如果 YouTube 無法辨識相關美國州別，系統會使用州/省代碼 US-ZZ 來回報相關指標。 如果 API 要求在 dimensions 參數值中加入 province，該要求也必須在 filters 參數值中加入 country==US，將資料限制為美國。

注意：這個維度不支援用於識別美國外界區域的 ISO 3166-2 值，因為這些地區也有自己的 ISO 3166-1 國家/地區代碼。而且不支援美國以外的國家/地區的子行政區。

dma
Nielsen 用來識別指定行銷區域 (DMA) 的 3 位數 ID 與資料列描述的觀看事件相關聯。
city
與報表列中的指標相關聯的預估城市。這個維度的資料可提供 2022 年 1 月 1 日之後的資料。
洲(僅限篩選器)
聯合國 (UN) 統計區碼。這個 API 支援下列值：
值
002 非洲
019 美洲 (北美、拉丁美洲、南美洲和加勒比海)
142 亞洲
150 歐洲
009 大洋洲
這項維度只能用於篩選資料。如要使用這個維度，請將 filters 參數加到 continent==REGION_CODE，指定資料表中的 REGION_CODE 值。
subContinent(僅限篩選器)
識別地理區域子區域的聯合國統計區代碼。聯合國統計處 (United Nations Stats Division) 列出子區域，以及其與各區域相關聯的國家/地區。

這項維度只能用於篩選資料。如要使用這個維度，請將 filters 參數的值設為 subContinent==REGION_CODE，並指定聯合國清單中的 REGION_CODE 值。

範例

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

  • 頻道範例

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

  • 內容擁有者範例

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

時間範圍

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

重要事項：所有日期均以太平洋時間 (UTC-7 或 UTC-8) 凌晨 12:00 開始，並於指定日、月及年的晚上 11 點 59 分 (太平洋時間) 結束。因此，依照日光節約時間調整時鐘的日期代表 23 小時，而時鐘倒數時間則是以 25 小時為前調。

「月」維度是指太平洋時間在指定月分和首日凌晨 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.

範例

以下要求範例使用時間維度或篩選器：

  • 頻道範例

    • 根據時間
      • 頻道影片的每日觀看時間指標
      • 頻道影片的每日註解指標
      • 頻道的每日播放清單觀看次數
    • 播放位置：不同播放位置的每日觀看次數和觀看時間
    • 流量來源：不同流量來源的每日觀看次數和觀看時間
    • 裝置/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播放次數。舊版資料仍屬於該類別，因此報表可能會保留這個值。不過，在 2014 年 6 月 1 日之後，行動裝置播放次數會歸類為 WATCH、EMBEDDED 或 EXTERNAL_APP 播放次數 (視發生播放的應用程式類型而定)。

  • SEARCH – 資料是指直接在 YouTube 搜尋結果網頁上獲得的觀看次數。

  • WATCH - 這項資料反映了來自影片 YouTube 觀賞頁面或官方 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，而 1 次觀看的 subscribedStatus 值為 UNSUBSCRIBED。
youtubeProduct
這個維度會指出使用者活動發生在哪個 YouTube 服務。這個維度的資料最早可回溯至 2015 年 7 月 18 日。

下表列出維度值：
值
CORE 非使用特定 YouTube 專門應用程式 (YouTube Gaming、YouTube Kids 或 YouTube Music) 的使用者活動。例外狀況：2021 年 3 月 1 日之前在 YouTube Music 中發生的使用者活動，包含在「CORE」中。
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：源自播客到達網頁項目的觀看次數。
    • 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 說明中心提供了 YouTube Analytics 報表的其他客層資料相關資訊。

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
Blackberry Messenger BBM
Blogger BLOGGER
複製到剪貼簿 COPY_PASTE
熱帶風情 CYWORLD
挖掘 DIGG
Dropbox DROPBOX
嵌入 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
其他 OTHER
Pinterest PINTEREST
樂天 (院空區) RAKUTEN
reddit REDDIT
Skype SKYPE
Skyrock SKYBLOG
Sony 對話 SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
簡訊 TEXT_MESSAGE
Tuenti TUENTI
tumblr。 TUMBLR
Twitter TWITTER
不明 UNKNOWN
Verizon 訊息 VERIZON_MMS
Viber VIBER
VKontakte (hijackонтакте) VKONTAKTE
WeChat WECHAT
微博 WEIBO
WhatsApp WHATS_APP
Wykop 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 日後生效。

範例

以下要求範例使用的是觀眾續看率維度：

直播

livestreamPosition
這個維度可用來指定即時影片串流中特定分鐘數。報表指標 會顯示當時有多少使用者觀看直播。

取消會員方案

membershipsCancellationSurveyReason
取消頻道會員資格的 YouTube 使用者所完成的問卷調查數量 指定的管道下表列出有效的維度值：
API 值 說明
UNKNOWN 使用者未填寫問卷調查。
DISLIKE_PERKS 使用者對會員福利不滿意。
PERKS_NOT_DELIVERED 使用者表示自己未領取承諾的會員福利。
CANNOT_ACCESS_PERKS 因此使用者無法存取福利。
NO_LONGER_INTERESTED 使用者已不感興趣。
FEEL_UNAPPRECIATED 使用者對頻道會員感到不滿意。
FINANCIAL_REASONS 使用者因財務因素而取消。
JOIN_LIMITED_TIME 使用者限時加入，
OTHER 使用者有其他取消訂閱的原因。

廣告成效

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 - YouTube 無法分類這個廣告類型。

範例

以下報表範例會擷取廣告成效或收益指標：

  • 頻道範例

    • 收益/廣告
      • 頻道收益和廣告成效指標
      • 每日收益和廣告成效指標
      • 特定國家/地區的收益和廣告成效指標
      • 前 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 維度組合來篩選資料。