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。

video(核心維度)
YouTube 影片 ID。在 YouTube Data API 中，這是 video 資源的 id 屬性值。This is a core dimension and is subject to the Deprecation Policy.
playlist
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 (德州)。省份代碼 US-ZZ 用於回報 YouTube 無法識別相關美國州別的指標。如果 API 要求在 dimensions 參數值中包含 province，則要求也必須在 filters 參數值中加入 country==US，將資料限制在美國。

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

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

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

範例

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

  • 管道範例

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

  • 內容擁有者範例

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

時間範圍

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

重要事項：所有日期均指指定日期、月份和年份的太平洋時間 (UTC-7 或 UTC-8) 凌晨 12 點開始，晚上 11 點 59 分結束的時間範圍。因此，如果時鐘調整為日光節約時間，日期代表 23 小時的時間範圍，如果時鐘調整為標準時間，則代表 25 小時的時間範圍。

「month」維度是指指定月份和年份第一天太平洋時間凌晨 12 點 (UTC-7 或 UTC-8) 開始的時間範圍。

day (核心維度)
使用這個維度時，報表中的資料會按天匯總，每列資料都包含一天的資料。您可以使用其他維度進一步細分資料。舉例來說，流量來源報表可根據使用者觀看影片的方式，匯總每日觀看統計資料。This is a core dimension and is subject to the Deprecation Policy.
month (核心維度)
報表中的資料會按日曆月份匯總。就像每日報表一樣，您可以使用其他篩選器進一步區隔資料。在報表中，日期會以 YYYY-MM 格式列出。

注意：如果 API 查詢使用 month 維度，則 start-date 和 end-date 參數都必須設為當月的第一天。This is a core dimension and is subject to the Deprecation Policy.

範例

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

  • 管道範例

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

  • 內容擁有者範例

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

播放位置

這些維度可提供使用者活動發生的網頁或應用程式相關洞察資料。

insightPlaybackLocationType
報表中的資料會根據影片播放的網頁或應用程式類型進行匯總。這項維度的可能值包括：

  • BROWSE：這項資料會說明 YouTube 首頁或主畫面、使用者的訂閱動態消息，或其他 YouTube 瀏覽功能的觀看次數。

  • CHANNEL：這項資料描述頻道頁面上的觀看次數。

  • EMBEDDED：這項資料描述使用 <iframe> 或 <object> 嵌入功能嵌入影片的其他網站或應用程式中，觀眾觀看影片的次數。

  • EXTERNAL_APP：這項資料會說明第三方應用程式中發生的觀看次數，這些應用程式使用 <iframe> 或 <object> 嵌入功能以外的方法播放影片。舉例來說，使用 YouTube Android 播放器 API 的應用程式會使用這個值來分類播放內容。

  • MOBILE：這項資料描述在 YouTube 行動網站或已核准的 YouTube API 用戶端 (包括行動裝置) 上發生的觀看次數。

    自 2013 年 9 月 10 日起，YouTube 數據分析報表中的播放次數不再歸類為 MOBILE 播放次數。由於舊版資料仍屬於該類別，因此報表中可能會保留該值。不過，在該日期之後，行動裝置播放內容會根據播放內容所在應用程式的類型，歸類為 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，另一個觀看次數的 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：來自 VOD 主題標籤頁面或 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

範例

以下範例要求使用裝置維度：

  • 管道範例

    • 裝置/作業系統
      • Android 作業系統的每日裝置類型指標
      • 行動裝置的每日作業系統指標
      • 每日作業系統和裝置類型指標
      • Android 作業系統上播放清單觀看次數的每日裝置類型指標
      • 行動裝置上播放清單觀看次數的每日作業系統指標

  • 內容擁有者範例

    • 裝置/作業系統
      • 已聲明著作權的影片每日裝置類型指標
      • 在行動裝置上觀看已聲明版權的影片，每日作業系統指標
      • 每日作業系統和裝置類型指標
      • 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 CYWORLD
Digg DIGG
Dropbox DROPBOX
嵌入 EMBED
電子郵件 MAIL
Facebook FACEBOOK
Facebook Messenger FACEBOOK_MESSENGER
Facebook 粉絲專頁 FACEBOOK_PAGES
Fotka FOTKA
Gmail GMAIL
goo GOO
Google+ GOOGLEPLUS
Go SMS GO_SMS
GroupMe GROUPME
Hangouts HANGOUTS
hi5 HI5
HTC 簡訊 HTC_MMS
Google 信箱 INBOX
iOS 系統活動對話方塊 IOS_SYSTEM_ACTIVITY_DIALOG
KAKAO Story KAKAO_STORY
Kakao (Kakao Talk) KAKAO
Kik KIK
LGE 電子郵件 LGE_EMAIL
折線圖 LINE
LinkedIn LINKEDIN
LiveJournal LIVEJOURNAL
menéame MENEAME
mixi MIXI
Motorola Messaging MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
鄰近分享 NEARBY_SHARE
NUjij NUJIJ
Odnoklassniki (Одноклассники) ODNOKLASSNIKI
其他 OTHER
Pinterest PINTEREST
Rakuten (樂天市場) RAKUTEN
reddit REDDIT
Skype SKYPE
Skyrock SKYBLOG
Sony Conversations SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
簡訊 TEXT_MESSAGE
Tuenti TUENTI
tumblr。 TUMBLR
Twitter TWITTER
不明 UNKNOWN
Verizon 訊息 VERIZON_MMS
Viber VIBER
VKontakte (ВКонтакте) 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% 後的留存資料。

每部影片的比例值範圍為 0.01 到 1.0，API 會為每部影片傳回 100 個資料點。影片播放期間的資料評估時間點，每部影片的間隔時間相同。也就是說，如果影片長度為 2 分鐘，資料點之間的間隔為 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 名：收益最高的影片
      • 不同廣告類型的廣告成效指標

內容擁有者維度

下列維度僅適用於內容擁有者報表。

重要事項：如要擷取內容擁有者報表，API 要求必須使用下列其中一個維度篩選資料：
  • video
  • channel
  • 如以下定義，claimedStatus 和 uploaderType 維度的支援組合。
claimedStatus (僅用於內容擁有者報告)
這個維度可讓您指出 API 回應只應包含已聲明內容的指標。這項維度的唯一有效值為 claimed。如果 filters 參數將查詢限制為 claimedStatus==claimed，API 只會擷取已宣告內容的資料。uploaderType 維度的定義中提供的資料表，可進一步說明如何使用這個維度。
uploaderType (核心維度) (僅用於內容擁有者報表)
您可以透過這個維度，指出 API 回應是否應包含特定內容擁有者上傳的內容和/或第三方上傳的內容 (例如使用者上傳的影片) 的指標。有效值為 self 和 thirdParty。這是核心維度，並受停用政策的規範。

下表列出 claimedStatus 和 uploaderType 維度支援的組合，這兩個維度都會用於 filters 參數：

claimedStatus值 uploaderType值 說明
[未設定] self 擷取內容擁有者上傳的已聲明版權和未聲明版權內容的 YouTube 數據分析資料。
已聲明版權 [未設定] 擷取內容擁有者或第三方上傳的已聲明著作權內容資料。
已聲明版權 self 擷取內容擁有者上傳的已聲明版權內容資料。
已聲明版權 thirdParty 擷取第三方上傳的版權聲明內容資料。

範例

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