API 要求範例

本頁面會顯示 YouTube Analytics API 要求範例。每個範例都會簡要說明要擷取的報表,然後顯示對應的 dimensionsmetricsfilterssort 參數值。(頻道報表內容擁有者報表文件會說明 API 支援的報表)。

每個範例都會連結至 Google APIs Explorer,並填入顯示的值。範例也會使用 2023-09-012024-03-31 的預設開始和結束日期 (YYYY-MM-DD)。

連結至 API Explorer 後,您仍必須指定要擷取報表的頻道或內容擁有者。視您點選的查詢而定,API Explorer 會將 channel==MINEcontentOwner==CONTENT_OWNER_ID 填入 ids 參數值。針對管道報表,您可以將 MINE 變更為已驗證使用者的頻道 ID。如要使用內容擁有者報表,請將 CONTENT_OWNER_ID 替換為內容擁有者 ID。

您也必須以指定的頻道或內容擁有者的身分進行驗證,讓 APIs Explorer 能夠使用 OAuth 2.0 授權您的 API 要求。

  1. 依據多個維度/指標排序要求
  2. 頻道報表
  3. 內容擁有者報告

依據多個維度/指標排序要求

這個 API 支援使用多個維度或指標排序回應資料。舉例來說,下列要求會擷取特定頻道影片的每日流量來源資料。結果集的每個資料列會指出特定類型的流量來源 (例如 EXT_URL) 在特定日期的觀看次數和預估觀看時間。

dimensions=day,insightTrafficSourceType
metrics=views,estimatedWatchTime
sort=day,-views

在回應中,結果會按照時間先後排序。在每天的結果集中,結果會依觀看次數遞減排序。因此,結果集的第一列會包含在要求日期範圍內的第一天產生最多次觀看次數的流量來源資料。第二列則包含第一天觀看次數次高的流量來源,

管道報表

基本統計資料

影片報表

頻道的總觀看次數、預估觀看時間等數據

這項查詢會擷取頻道內容的匯總指標。報表會傳回一列資料,其中包含指定日期範圍內各項要求指標的總計。

metrics=views,comments,likes,dislikes,estimatedMinutesWatched,averageViewDuration

頻道的觀看次數 (及其他資訊)

這項查詢會擷取頻道影片在特定國家/地區的相關指標。報表會傳回單一資料列,其中包含指定日期範圍內每個要求指標的總計。

metrics=views,comments,likes,dislikes,estimatedMinutesWatched
filters=country==US

熱門 10 名:頻道中觀看次數最多的影片

這項查詢會擷取頻道中觀看次數最多的 10 部影片,並以指定日期範圍內的預估觀看分鐘數做為評估標準。結果會依據估計觀看時間 (分鐘) 遞減排序。

注意:您必須為 sort 要求參數指定值,並將 maxResults 參數設為 10 以下的整數值。

dimensions=video
metrics=estimatedMinutesWatched,views,likes,subscribersGained
maxResults=10
sort=-estimatedMinutesWatched

前 10 名:頻道觀看次數最多的影片註解點閱率

這項要求會擷取頻道中觀看次數最多的 10 部影片的觀看次數、註解點閱率、註解關閉率和註解曝光次數。結果會按觀看次數以遞減方式排序,也就是觀看次數最多的影片會最先顯示。

注意:您必須為 sort 要求參數指定值,並將 maxResults 參數設為 10 以下的整數值。

dimensions=video
metrics=views,likes,annotationClickThroughRate,annotationCloseRate,annotationImpressions
maxResults=10
sort=-views

播放清單報表

頻道的播放清單總觀看次數

這項要求會擷取已驗證使用者頻道中播放清單的總播放次數、預估觀看分鐘數、觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標),以及每個播放清單播放次數。

metrics=views,estimatedMinutesWatched,playlistStarts,playlistViews,viewsPerPlaylistStart

特定播放清單的統計資料

這項要求會擷取播放清單的總啟動次數、預估觀看分鐘數、觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標),以及特定播放清單的每個播放清單啟動次數觀看次數。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 PLAYLIST_ID 替換為已驗證使用者頻道中播放清單的播放清單 ID。

metrics=views,estimatedMinutesWatched,playlistStarts,playlistViews,viewsPerPlaylistStart
filters=playlist==PLAYLIST_ID

如要擷取多個播放清單的匯總統計資料,您也可以將字串 PLAYLIST_ID 替換為以半形逗號分隔的清單,最多可納入 500 個已驗證使用者頻道中的播放清單 ID。

熱門 10 大:頻道觀看次數最多的播放清單

這項查詢會根據指定日期範圍內的播放清單觀看次數,擷取頻道中觀看次數最多的 10 個播放清單。並擷取其他幾項播放清單指標,例如觀眾開始播放每個播放清單的次數,以及觀眾開始播放播放清單後觀看影片的平均時間。結果是按照播放清單觀看次數遞減排序。

注意:由於這份報表使用 playlist 維度,因此您必須為 sort 要求參數指定值,並將 maxResults 參數設為 10 以下的整數值。

dimensions=playlist
metrics=playlistViews,playlistEstimatedMinutesWatched,playlistStarts,averageTimeInPlaylist,playlistSaves
maxResults=10
sort=-playlistViews
根據時間

影片報表

頻道影片的每日觀看時間指標

這項查詢會擷取頻道影片的每日觀看次數、觀看時間指標和新訂閱人數。報表會針對請求的日期範圍中的每一天傳回一列資料。資料列會依時間順序排序。

dimensions=day
metrics=views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained
sort=day

頻道影片的每日註解指標

這項要求會擷取頻道內容的每日觀看次數、註解點閱率、註解關閉率和註解曝光次數。結果會依時間順序排列。

dimensions=day
metrics=views,likes,annotationClickThroughRate,annotationCloseRate,annotationImpressions
sort=day

播放清單報表

頻道的每日播放清單觀看次數

這項要求會擷取已驗證使用者頻道的每日觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標)、播放清單啟動次數、預估觀看時間長度,以及每個播放清單啟動次數的觀看次數。結果會依時間先後順序排序。

dimensions=day
metrics=views,estimatedMinutesWatched,playlistStarts,playlistViews,viewsPerPlaylistStart
sort=day
地理位置

影片報表

頻道影片的國家/地區別觀看時間指標

這項查詢可擷取頻道影片的國家/地區觀看次數、觀看時間指標和訂閱人數。這份報表會針對每個觀看頻道影片的國家/地區傳回一列資料。資料列會依據觀看分鐘數,以遞減方式排序。

dimensions=country
metrics=views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained
sort=-estimatedMinutesWatched

頻道影片的國家/地區專屬註解指標

這項要求會擷取頻道影片的國家/地區觀看次數、註解點閱率、註解關閉率和註解曝光次數。結果是依註解點閱率以遞減方式排序,也就是說,註解點閱率最高的國家/地區會優先列出。

dimensions=country
metrics=views,likes,annotationClickThroughRate,annotationCloseRate,annotationImpressions
sort=-annotationClickThroughRate

美國各州和華盛頓特區的省別指標

這項要求會擷取各州/省的詳細分析資料,包括頻道影片的觀看次數、估計觀看時間 (分鐘) 和平均觀看時間。這些資料涵蓋美國各州和華盛頓特區。結果會依州/省的 ISO 3166-2 代碼字母順序排序。

dimensions=province
metrics=views,estimatedMinutesWatched,averageViewDuration
filters=claimedStatus==claimed;country==US
sort=province

前 10 名 - 在特定國家/地區觀看次數最多的影片

這項查詢會在指定國家/地區,根據指定日期範圍內的觀看次數,擷取頻道觀看次數前 10 名的影片。結果會依觀看次數遞減排序。

注意:這份報表會要求您指定 sort 要求參數的值,並將 maxResults 參數設為 10 以下的整數值。

dimensions=video
metrics=views,estimatedMinutesWatched,likes,subscribersGained
filters=country==US
maxResults=10
sort=-views

美國觀看次數最多的前 10 大城市

這項查詢會擷取美國 10 個城市的清單,這些城市的頻道內容觀看次數在指定日期範圍內最多。您可以修改查詢,選擇其他有效的篩選器值,以便要求其他國家/地區的資料。同樣地,您也可以使用「subContinent」篩選器和其中一個有效值,修改查詢,以便擷取某個次大陸 (例如西歐或東南亞洲) 的資料。系統也支援其他篩選器。結果會依觀看次數遞減排序。

    dimensions=city
metrics=views
filters=country==US
maxResults=10
sort=-views

美國各內容類型前 10 名城市的總觀看次數

這項查詢會針對所有支援的 creatorContentType,擷取指定日期範圍內的 10 個美國城市,頻道內容獲得最多觀看次數。結果會依觀看次數遞減排序。

    dimensions=city,creatorContentType
metrics=views
filters=country==US
maxResults=10
sort=-views

美國觀看時間最長的 10 大城市

這項查詢會擷取指定日期範圍內,美國各城市在頻道內容每日總觀看時間中所占比率最高的前 10 名清單。查詢結果會顯示總觀看時間、觀看時間發生的日期,以及內容的預估觀看城市。結果會依觀看總時數以遞減順序排列。

    dimensions=city,day
metrics=estimatedWatchTime
filters=country==US
maxResults=10
sort=-estimatedWatchTime

歐洲觀看次數最多的影片 (前 10 名)

這項查詢會根據指定日期範圍內的觀看次數,擷取頻道在歐洲地區觀看次數最多的 10 部影片。您可以修改查詢,選擇其他有效的篩選器值,以便要求其他大陸的資料。同樣地,您也可以運用 subContinent 篩選器和其中一個有效值,修改查詢以擷取子洲 (例如西歐或東南亞) 的資料。結果會按觀看次數遞減排序。

注意:這份報表會要求您指定 sort 要求參數的值,並將 maxResults 參數設為 10 以下的整數值。

dimensions=video
metrics=views,estimatedMinutesWatched,likes,subscribersGained
filters=continent==150
maxResults=10
sort=-views

播放清單報表

頻道播放清單的各國家/地區觀看時間指標

這項查詢會擷取特定國家/地區的觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標) 和頻道播放清單的觀看時間指標。這份報表會針對每個觀看頻道播放清單的國家/地區,傳回一列資料。資料列會依觀看時間長度遞減排序。

dimensions=country
metrics=views,estimatedMinutesWatched,playlistStarts,averageTimeInPlaylist
sort=-estimatedMinutesWatched

前 10 名:美國最多人開始播放的播放清單

這項查詢會擷取美國觀眾在指定日期範圍內最常開始觀看的 10 個播放清單。結果會依播放清單啟動次數以遞減方式排序。

注意:由於這份報表使用 playlist 維度,因此您必須為 sort 要求參數指定值,並將 maxResults 參數設為 10 以下的整數值。

dimensions=playlist
metrics=playlistStarts,views,estimatedMinutesWatched,averageViewDuration
filters=isCurated==1;country==US
maxResults=10
sort=-playlistStarts
播放位置

影片報表

來自不同播放位置的觀看次數和觀看時間

這項查詢會擷取特定頻道影片的觀看次數和預估觀看時間。系統會根據影片播放的網頁或應用程式類型匯總結果,並依觀看次數以遞減方式排序。

dimensions=insightPlaybackLocationType
metrics=estimatedMinutesWatched,views
sort=-views

每日觀看次數和觀看時間來自不同的播放位置

這項查詢會擷取特定頻道影片在美國的每日觀看次數和預估觀看時間。系統會按日分組,列出每個發生影片播放的網頁或應用程式類型。結果會依時間順序排列。

    dimensions=day,insightPlaybackLocationType
metrics=estimatedMinutesWatched,views
filters=country==US
sort=day

前 10 名:嵌入式影片的觀看次數最多的第三方網站

這項查詢會擷取特定影片或一組影片的觀看次數和預估觀看時間。結果會依據影片嵌入的第三方網站分組。結果會依觀看次數遞減排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的 VIDEO_ID 字串,替換成逗號分隔的一或多個影片 ID 清單。

dimensions=insightPlaybackLocationDetail
metrics=views,estimatedMinutesWatched
filters=video==VIDEO_ID;insightPlaybackLocationType==EMBEDDED
maxResults=10
sort=-views

播放清單報表

播放清單觀看次數和觀看時間 (來自不同播放位置)

這項查詢會擷取特定頻道播放清單的觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標)、預估觀看時間,以及播放清單開始播放的次數。系統會根據影片播放的網頁或應用程式類型匯總結果,並依播放清單開始時間以遞減順序排序。

dimensions=insightPlaybackLocationType
metrics=views,estimatedMinutesWatched,playlistStarts,playlistViews
sort=-playlistStarts

不同播放位置的每日播放清單觀看次數和觀看時間

這項查詢會擷取特定頻道播放清單在美國境內的每日播放清單開始播放次數、觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標) 和預估觀看時間。系統會依照發生播放清單觀看次數的網頁或應用程式類型,將結果按日分組。結果會依時間順序排列。

dimensions=day,insightPlaybackLocationType
metrics=views,estimatedMinutesWatched,playlistStarts,playlistViews
filters=country==US
sort=day
流量來源

影片報表

某國家/地區的觀看次數和觀看時間 (來自不同流量來源)

這項要求,就能擷取頻道影片在特定國家/地區的觀看次數和預估觀看時間。指標會依流量來源匯總,說明使用者觀看影片的方式。

dimensions=insightTrafficSourceType
metrics=views,estimatedMinutesWatched
filters=country==US

不同流量來源的每日觀看次數和觀看時間

這項要求會擷取頻道影片的每日觀看次數和每日預估觀看時間。系統會按流量來源每日彙整指標,並依時間順序排序。

dimensions=day,insightTrafficSourceType
metrics=views,estimatedMinutesWatched
sort=day

前 10 名:為影片帶來最多流量的 YouTube 搜尋字詞

這項查詢會擷取一或多部特定影片在 YouTube 搜尋結果中,產生最多觀看次數的 10 個搜尋字詞。結果會按觀看次數遞減排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 VIDEO_ID 替換為逗號分隔的清單,最多可包含 500 個影片 ID。

舉例來說,您可以針對單一影片執行查詢,或替換 VIDEO_ID,找出為該影片帶來最多流量的搜尋字詞。你也可以列出特定播放清單中的所有影片,找出哪些搜尋字詞可為該播放清單中的影片帶來最多流量。

dimensions=insightTrafficSourceDetail
metrics=views
filters=video==VIDEO_ID;insightTrafficSourceType==YT_SEARCH
maxResults=10
sort=-views

前 10 名:為影片帶來最多流量的外部網站

這項查詢會擷取為特定影片或一組影片帶來最多觀看次數的外部網站 10 個。結果會依預估觀看時間遞減排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 VIDEO_ID 替換為以半形逗號分隔的清單,最多可包含 500 個上傳影片的影片 ID。

dimensions=insightTrafficSourceDetail
metrics=estimatedMinutesWatched,views
filters=video==VIDEO_ID;insightTrafficSourceType==EXT_URL
maxResults=25
sort=-estimatedMinutesWatched

播放清單報表

某個國家/地區的不同流量來源所帶來的播放清單觀看次數和觀看時間

這項要求會擷取觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標)、播放清單啟動次數,以及特定國家/地區播放清單觀看次數的預估觀看時間。指標會依流量來源匯總,說明使用者如何找到播放清單。

dimensions=insightTrafficSourceType
metrics=views,estimatedMinutesWatchedplaylistStarts,playlistViews
filters=country==US

不同流量來源的每日播放清單觀看次數和觀看時間

這項要求會擷取頻道的每日播放清單觀看次數 (播放清單內指標)、播放清單開始播放次數和預估觀看時間。並擷取總觀看次數 (匯總影片指標)。系統會按流量來源每日彙整指標,並依時間順序排序。

dimensions=day,insightTrafficSourceType
metrics=views,estimatedMinutesWatched,playlistStarts,playlistViews
sort=day
裝置/OS

影片報表

Android 作業系統的每日裝置類型指標

這項查詢會擷取特定頻道影片在 Android 裝置上的每日觀看次數和預估觀看時間。結果會依照發生影片播放的裝置類型,按日分組。結果會依時間先後順序排序。

dimensions=day,deviceType
metrics=estimatedMinutesWatched,views
filters=operatingSystem==ANDROID
sort=day

行動裝置的每日作業系統指標

這項查詢會擷取特定頻道影片在行動裝置上的每日觀看次數和預估觀看時間。結果會依照播放影片的作業系統,按天分組。結果會依時間順序排列。

dimensions=day,operatingSystem
metrics=estimatedMinutesWatched,views
filters=deviceType==MOBILE
sort=day

每日作業系統和裝置類型指標

這項查詢會擷取頻道的每日觀看次數和預估觀看時間。統計資料會依作業系統和裝置類型分組。結果會依時間先後順序排序。

dimensions=day,operatingSystem,deviceType
metrics=estimatedMinutesWatched,views
sort=day

播放清單報表

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

這項查詢會擷取每日觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標),以及 Android 裝置上特定頻道播放清單的預估觀看時間。系統會依據播放清單收視次數的裝置類型,將結果分組為每日資料。結果會依時間先後順序排序。

dimensions=day,deviceType
metrics=views,estimatedMinutesWatched,playlistViews
filters=operatingSystem==ANDROID
sort=day

行動裝置上播放清單觀看次數的每日作業系統指標

這項查詢會擷取每日觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標),以及特定頻道播放清單在行動裝置上的預估觀看時間。結果會依照播放清單觀看次數的作業系統,按日分組。結果會依時間順序排列。

dimensions=day,operatingSystem
metrics=views,estimatedMinutesWatched
filters=deviceType==MOBILE
sort=day
客層

影片報表

加州觀眾客層 (年齡層和性別)

這份報表會擷取加州觀眾觀看頻道影片的年齡層和性別統計資料。結果會依性別和年齡層排序。只要調整 filters 參數值,就能修改這項查詢,為全球所有觀眾或某個國家/地區、大陸、次大陸或美國其他州的所有觀眾擷取相同的統計資料。

dimensions=ageGroup,gender
metrics=viewerPercentage
filters=province==US-CA
sort=gender,ageGroup

播放清單報表

加州的播放清單觀眾客層 (年齡層和性別)

這份報表會擷取加州觀眾觀看頻道播放清單時的年齡層和性別統計資料。結果會依性別和年齡層排序。只要調整 filters 參數值,即可修改這項查詢,為全球所有觀眾或某個國家/地區、大陸、次大陸或美國其他州的所有觀眾,擷取相同的統計資料。

dimensions=ageGroup,gender
metrics=viewerPercentage
filters=province==US-CA
sort=gender,ageGroup
社群媒體

分享指標 (依分享影片的服務匯總)

這個要求會擷取使用者使用 Share 按鈕分享頻道影片的次數。結果會依分享服務 (Google+、Twitter 等) 匯總,並依分享次數遞減排序。

dimensions=sharingService
metrics=shares
sort=-shares
觀眾續看率

影片的觀眾續看率指標

這份報表可評估影片吸引觀眾續看的能力。你一次只能擷取單一影片的報表。請注意,若要在 API Explorer 中執行此查詢,您必須將 filters 參數值中的 VIDEO_ID 字串取代為您其中一部影片的影片 ID。請注意,目標對象留存報表不支援為 video 篩選器指定多個值。

在這個範例中,報表會使用 audienceType 篩選器限制回應,只納入自然觀看次數的資料,也就是使用者直接採取的動作 (例如搜尋影片或點選建議影片) 所產生的結果。因此,報表不會納入 TrueView 串流內廣告或 TrueView 顯示廣告的觀看次數資料。你可以移除篩選器,從所有觀眾類型中擷取影片的觀眾續看率資料。

請注意,audienceType 篩選條件提供的資料可回溯至 2013 年 9 月 25 日。如果查詢使用篩選器嘗試擷取較早日期的資料,API 就不會傳回資料。不使用篩選器的查詢可查看 2008 年 7 月 1 日後的任何日期。

dimensions=elapsedVideoTimeRatio
metrics=audienceWatchRatio,relativeRetentionPerformance
filters=video==VIDEO_ID;audienceType==ORGANIC
收益/廣告

頻道收益和廣告成效指標

這項要求會擷取頻道的收益和廣告成效指標。報表會傳回單一資料列,其中包含指定日期範圍內每個要求指標的總計。

metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks

每日收益和廣告成效指標

這項要求會擷取頻道的每日收益和廣告成效指標,

dimensions=day
metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks

特定國家/地區的收益和廣告成效指標

這項要求會擷取頻道的國家/地區特定收益和廣告成效指標。結果會依收益金額遞減排序,也就是說,列出的首個國家/地區,是合作夥伴淨收益最高的國家/地區。

dimensions=country
metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks
sort=-estimatedRevenue

前 10 名 - 收益最高的影片

這項要求會擷取頻道收益最高的 10 部影片的收益和廣告成效指標。結果會依收益金額遞減排序,也就是說,第一部影片的預估收益最高。

dimensions=video
metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks
maxResults=10
sort=-estimatedRevenue

不同廣告類型的廣告成效指標

這項要求會擷取內容擁有者聲明擁有權的內容廣告成效指標。系統會依廣告類型分組結果,方便您比較不同廣告類型的收益和千次曝光出價。

dimensions=adType
metrics=grossRevenue,adImpressions,cpm
filters=claimedStatus==claimed
sort=-adType

內容擁有者報告

基本統計資料

影片報表

所有聲明版權的內容的總觀看次數、預估觀看時間等資訊

這項查詢會擷取內容擁有者聲明擁有權的內容匯總指標。報表會傳回單一資料列,其中包含指定日期範圍內每個要求指標的總計。

metrics=views,comments,likes,dislikes,estimatedMinutesWatched,averageViewDuration
filters=claimedStatus==claimed

所有自行上傳影片的國家/地區觀看次數 (以及其他資訊)

這項查詢會針對內容擁有者上傳的影片,擷取特定國家/地區的指標。報表會傳回單一資料列,其中包含指定日期範圍內每個要求指標的總計。

metrics=views,comments,likes,dislikes,shares
filters=uploaderType==self;country==FR

所有已聲明著作權的第三方內容總觀看次數 (以及其他資訊)

這項查詢會針對內容擁有者聲明版權但未上傳的影片,擷取匯總指標。報表會傳回單一資料列,其中包含指定日期範圍內每個要求指標的總計。

metrics=views,comments,likes,dislikes,shares
filters=uploaderType==thirdParty;claimedStatus==claimed

所有自行上傳內容的觀看次數總數 (以及更多資訊)

這項查詢會擷取內容擁有者所上傳影片的匯總指標。報表會傳回一列資料,其中包含指定日期範圍內各項要求指標的總計。

metrics=views,comments,likes,dislikes,estimatedMinutesWatched
filters=uploaderType==self

所有已聲明著作權且自行上傳的內容的總觀看次數 (及更多資料)

這項查詢會針對內容擁有者上傳並聲明擁有權的影片,擷取匯總指標。報表會傳回一列資料,其中包含指定日期範圍內各項要求指標的總計。

metrics=views,comments,likes,dislikes,estimatedMinutesWatched
filters=uploaderType==self;claimedStatus==claimed

前 10 名 - 內容擁有者觀看次數最多的影片

這項查詢會擷取內容擁有者上傳的 10 部觀看次數最多的影片 (以指定日期範圍內的觀看次數為準)。結果會依觀看次數遞減排序。

dimensions=video
metrics=views,estimatedMinutesWatched,estimatedRevenue,estimatedAdRevenue,monetizedPlaybacks,adImpressions
filters=uploaderType==self
maxResults=10
sort=-views

前 10 名 - 內容擁有者觀看次數最多的影片

這項查詢會擷取內容擁有者上傳的 10 部觀看次數最多的影片,以指定日期範圍內的預估觀看分鐘數為準。結果會依據預估觀看分鐘數以遞減順序排序。

dimensions=video
metrics=estimatedMinutesWatched,averageViewDuration,averageViewPercentage,views,subscribersGained
filters=uploaderType==self
maxResults=10
sort=-estimatedMinutesWatched

前 10 名:內容擁有者頻道中觀看次數最多的影片

這項查詢會擷取內容擁有者管理的特定頻道或一組頻道中,觀看次數最多的 10 部影片。結果會依觀看次數遞減排序。請注意,若要在 APIs Explorer 中執行這項查詢,您必須將 filters 參數值中的 CHANNEL_ID 字串替換成以半形逗號分隔的清單,當中包含您管道中最多 500 個管道 ID。

dimensions=video
metrics=views
filters=channel==CHANNEL_ID
maxResults=10
sort=-views

前 10 名:頻道觀看次數最多的影片註解點閱率

這項要求會針對指定頻道或群組中 10 名觀看次數最多的影片,擷取觀看次數、註解點閱率、註解關閉率和註解曝光次數。結果會按觀看次數以遞減方式排序,也就是觀看次數最多的影片會最先顯示。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 CHANNEL_ID 替換為逗號分隔的清單,最多可包含 500 個管道的管道 ID。

dimensions=video
metrics=views,likes,annotationClickThroughRate,annotationCloseRate,annotationImpressions
filters=channel==CHANNEL_ID
maxResults=10
sort=-views

播放清單報表

內容擁有者頻道的播放清單觀看次數

這項要求會擷取內容擁有者頻道中播放清單的總播放次數、播放清單預估觀看分鐘數、播放清單觀看次數,以及每個播放清單的觀看次數。playlistViews 指標只會計算播放清單中出現的影片觀看次數。由於所有要求的指標都是播放清單內的指標,因此要求不必同時包含播放清單群組篩選器。

metrics=playlistViews,playlistStarts,playlistEstimatedMinutesWatched,viewsPerPlaylistStart

特定播放清單的統計資料

這項要求會擷取播放清單的開始總次數、預估觀看時間 (分鐘)、觀看次數 (匯總影片指標)、播放清單觀看次數 (播放清單內指標),以及每個播放清單每次開始播放的觀看次數。請注意,如要在 API Explorer 中執行這項查詢,您必須使用其中一個內容擁有者頻道中播放清單的播放清單 ID,取代 filters 參數值中的 PLAYLIST_ID 字串。

metrics=views,estimatedMinutesWatched,playlistStarts,playlistViews,viewsPerPlaylistStart
filters=playlist==PLAYLIST_ID

如要擷取多個播放清單的匯總統計資料,也可以將字串 PLAYLIST_ID 替換成逗號分隔的清單 (最多 500 個) 適用於內容擁有者頻道的播放清單 ID。

根據時間

影片報表

自行上傳內容的每日觀看時間指標

這項查詢會擷取每日觀看時間指標、觀看次數、營利播放次數和內容擁有者所上傳影片的曝光次數。報表會針對要求日期範圍內的每一天傳回一列資料,且列會按時間順序排序。

dimensions=day
metrics=estimatedMinutesWatched,averageViewPercentage,views,monetizedPlaybacks,adImpressions
filters=uploaderType==self
sort=day

版權內容的註解指標

這項要求會針對內容擁有者已聲明著作權的內容,擷取每日觀看次數、註解點閱率、註解關閉率和註解曝光次數。結果會依時間順序排列。

dimensions=day
metrics=views,likes,annotationClickThroughRate,annotationCloseRate,annotationImpressions
filters=claimedStatus==claimed
sort=day

播放清單報表

內容擁有者的每日播放清單觀看次數

這項要求會擷取使用者每日與內容擁有者播放清單中影片互動的指標。報表中擷取的指標包括 playlistViewsplaylistStartsplaylistEstimatedMinutesWatchedviewsPerPlaylistStart。所有這些指標都是播放清單內的指標。由於所有要求的指標都是播放清單內指標,因此要求不需要一併包含 playlist群組篩選條件。

dimensions=day
metrics=playlistViews,playlistStarts,playlistEstimatedMinutesWatched,viewsPerPlaylistStart
sort=day
地理

影片報表

自有內容的觀看時間指標 (依國家/地區劃分)

這項查詢會擷取各國家/地區的觀看次數、觀看時間指標和預估廣告收益。指標適用於內容擁有者上傳的影片。這份報表會針對每個觀看影片的國家/地區傳回一列資料,且列會依觀看時間長度由高至低排序。

dimensions=country
metrics=views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,estimatedRevenue,estimatedAdRevenue,grossRevenue
filters=uploaderType==self
sort=-estimatedMinutesWatched

針對自行上傳內容的國家/地區專屬註解指標

這項要求可擷取內容擁有者上傳影片在特定國家/地區的觀看次數、註解點閱率、註解關閉率和註解曝光次數。結果會依註解點閱率遞減排序,也就是說,註解點閱率最高的國家會列在最前面。

dimensions=country
metrics=views,likes,annotationClickThroughRate,annotationCloseRate,annotationImpressions
filters=uploaderType==self
sort=-annotationClickThroughRate

美國各州和華盛頓特區的省別指標

這項要求會依省份列出內容擁有者聲明版權的影片觀看次數、預估觀看分鐘數和平均觀看時間。這些資料涵蓋美國各州和華盛頓特區。結果會依州/省的 ISO 3166-2 代碼字母順序排序。

dimensions=province
metrics=views,estimatedMinutesWatched,averageViewDuration
filters=claimedStatus==claimed;country==US
sort=province

美國觀看次數最多的前 10 大城市

這項查詢會擷取美國 10 個城市的清單,這些城市的內容擁有者在指定日期範圍內,擁有最多觀看次數的版權聲明影片。您可以修改查詢,選擇其他有效的篩選器值,以便要求其他國家/地區的資料。同樣地,您也可以使用「subContinent」篩選器和其中一個有效值,修改查詢,以便擷取次大陸 (例如西歐或東南亞洲) 的資料。系統也支援其他篩選器。結果會按觀看次數遞減排序。

    dimensions=city
metrics=views
filters=claimedStatus==claimed;country==US
maxResults=10
sort=-views

每種內容類型的美國前 10 大城市 (按觀看次數總和排序)

這項查詢會針對每個支援的 creatorContentType,在指定日期範圍內擷取 10 個美國城市的清單,這些城市的內容觀看次數,在內容擁有者聲明的內容中名列前茅。結果會依觀看次數遞減排序。

    dimensions=city,creatorContentType
metrics=views
filters=claimedStatus==claimed;country==US
maxResults=10
sort=-views

美國觀看時間最長的 10 大城市

這項查詢會擷取指定日期範圍內的 10 大熱門日期清單,當中列出美國任何城市在內容擁有者聲明擁有的內容中,每日觀看時間總和最高的城市。查詢結果會指出總觀看時間、觀看時間發生的日期,以及內容的預估觀看城市。結果會依總觀看時間遞減排序。

    dimensions=city,day
metrics=estimatedWatchTime
filters=claimedStatus==claimed;country==US
maxResults=10
sort=-estimatedWatchTime

前 10 名 - 歐洲觀看次數最多的影片

這項查詢會擷取指定日期範圍內觀看次數最多的歐洲前 10 部影片,以及內容擁有者已聲明版權的影片。為篩選器選擇其他有效值,即可修改查詢來要求另一個的資料。同樣地,您也可以使用「subContinent」篩選器和其中一個有效值,修改查詢,以便擷取次大陸 (例如西歐或東南亞洲) 的資料。結果會依觀看次數遞減排序。

dimensions=video
metrics=views,estimatedMinutesWatched,likes,subscribersGained
filters=claimedStatus==claimed;filters=continent==150
maxResults=10
sort=-estimatedMinutesWatched

播放清單報表

內容擁有者播放清單的國家/地區專屬觀看時間指標

這項查詢會針對內容擁有者頻道中的所有播放清單,擷取特定國家/地區的播放清單觀看次數和播放時間指標。這份報表會針對每個觀看播放清單的國家/地區傳回一列資料。資料列會依據觀看分鐘數,以遞減方式排序。

dimensions=country
metrics=playlistViews,playlistEstimatedMinutesWatched,playlistStarts,averageTimeInPlaylist
sort=-playlistEstimatedMinutesWatched

前 10 名:美國最多人開始播放的播放清單

這項查詢會從內容擁有者的頻道中擷取 10 個播放清單,這些播放清單是美國觀眾在指定日期範圍內最常開始觀看的。結果會依播放清單啟動次數以遞減方式排序。

注意:由於這份報表使用 playlist 維度,因此您必須為 sort 要求參數指定值,並將 maxResults 參數設為 10 以下的整數值。

dimensions=playlist
metrics=playlistStarts,playlistViews,playlistEstimatedMinutesWatched,playlistAverageViewDuration
filters=country==US
maxResults=10
sort=-playlistStarts
播放詳細資料

影片報表

依內容類型劃分喜歡與不喜歡

這項查詢會擷取特定頻道或一組頻道中,每種類型內容的按讚和按不喜歡次數。請注意,若要在 APIs Explorer 中執行這項查詢,您必須將 filters 參數值中的 CHANNEL_ID 字串替換成以半形逗號分隔的清單,當中包含您管道中最多 500 個管道 ID。

dimensions=creatorContentType
metrics=likes,dislikes
filters=channel==CHANNEL_ID
播放位置

影片報表

來自不同播放位置的觀看次數和觀看時間

這項查詢會擷取上傳至特定頻道或一組頻道的影片的觀看次數和預估觀看時間。系統會根據影片播放的網頁或應用程式類型匯總結果,並依觀看次數以遞減方式排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 CHANNEL_ID 替換為逗號分隔的清單,最多可包含 500 個管道的管道 ID。

dimensions=insightPlaybackLocationType
metrics=estimatedMinutesWatched,views
filters=channel==CHANNEL_ID
sort=-views

不同播放位置的每日觀看次數和觀看時間

這項查詢會擷取美國地區或某組頻道上傳影片的每日觀看次數和預估觀看時間。系統會按日分組,列出每個發生影片播放的網頁或應用程式類型。結果會按時間順序由新至舊排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 CHANNEL_ID 替換為逗號分隔的清單,最多可包含 500 個管道的管道 ID。

dimensions=day,insightPlaybackLocationType
metrics=estimatedMinutesWatched,views
filters=country==US;channel==CHANNEL_ID
sort=-day

前 10 名:嵌入式影片的觀看次數最多的第三方網站

這項查詢會擷取特定影片或一組影片的觀看次數和預估觀看時間。結果會依據影片嵌入的第三方網站分組。結果會依觀看次數遞減排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 VIDEO_ID 替換為以半形逗號分隔的清單,最多可包含 500 個上傳影片的影片 ID。

dimensions=insightPlaybackLocationDetail
metrics=views,estimatedMinutesWatched
filters=video==VIDEO_ID;insightPlaybackLocationType==EMBEDDED
maxResults=10
sort=-views

播放清單報表

來自不同播放位置的播放清單觀看次數和觀看時間

這項查詢會擷取內容擁有者頻道中所有播放清單的播放次數、預估觀看時間和播放次數。系統會根據影片播放的網頁或應用程式類型匯總結果,並依播放清單開始時間以遞減順序排序。

dimensions=insightPlaybackLocationType
metrics=playlistViews,playlistEstimatedMinutesWatched,playlistStarts
sort=-playlistStarts

播放清單觀看次數和觀看時間 (來自不同播放位置)

這項查詢會針對內容擁有者頻道中的所有播放清單,擷取美國的每日播放清單開始播放次數、播放清單觀看次數和播放清單預估觀看時間。系統會針對發生播放清單瀏覽次數的每種類型網頁或應用程式傳回結果。

dimensions=day,insightPlaybackLocationType
metrics=playlistStarts,playlistViews,playlistEstimatedMinutesWatched
filters=country==US
流量來源

影片報表

來自不同流量來源的觀看次數和觀看時間

這項要求會擷取內容擁有者影片的觀看次數和預估觀看時間。指標會依流量來源匯總,說明使用者觀看影片的方式。

dimensions=insightTrafficSourceType
metrics=views,estimatedMinutesWatched
filters=uploaderType==self

不同流量來源的每日觀看次數和觀看時間

這項要求會擷取內容擁有者影片的每日觀看次數和每日預估觀看時間。系統會每天依流量來源匯總指標,並以倒轉時間順序排序。

dimensions=day,insightTrafficSourceType
metrics=views,estimatedMinutesWatched
filters=uploaderType==self
sort=-day

注意:下列兩份範例報表僅適用於特定流量來源。不支援 VIDEO_REMIXESNOTIFICATIONEND_SCREENCAMPAIGN_CARDVIDEO_REMIXESNO_LINK_EMBEDDED 流量來源。

前 10 名 - 為影片產生最多流量的 YouTube 搜尋字詞

這項查詢會擷取特定影片或一組影片在 YouTube 搜尋結果中,產生最多觀看次數的 10 個搜尋字詞。結果會依觀看次數遞減排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 VIDEO_ID 替換成逗號分隔的清單 (最多 500 個) 已上傳的影片 ID,

dimensions=insightTrafficSourceDetail
metrics=views
filters=video==VIDEO_ID;insightTrafficSourceType==YT_SEARCH
maxResults=10
sort=-views

前 10 名:為影片帶來最多流量的外部網站

此查詢會擷取從 Google 搜尋結果中,針對特定影片或一組影片產生最多觀看次數的外部網站 10 個。結果會依預估觀看時間以遞減方式排序。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 VIDEO_ID 替換為以半形逗號分隔的清單,最多可包含 500 個上傳影片的影片 ID。

dimensions=insightTrafficSourceDetail
metrics=estimatedMinutesWatched,views
filters=video==VIDEO_ID;insightTrafficSourceType==EXT_URL
maxResults=25
sort=-estimatedMinutesWatched

播放清單報表

某個國家/地區的不同流量來源所帶來的播放清單觀看次數和觀看時間

這項要求會擷取特定國家/地區的播放清單觀看次數、播放清單開始播放次數,以及播放清單的預估觀看時間。指標會依流量來源匯總,說明使用者如何找到播放清單。

dimensions=insightTrafficSourceType
metrics=playlistViews,playlistStarts,playlistEstimatedMinutesWatched
filters=country==US

不同流量來源的播放清單觀看次數和觀看時間

這項要求會針對內容擁有者的一或多個頻道中的播放清單,擷取播放清單的觀看次數、播放清單開始播放次數,以及播放清單的預估觀看時間。指標會依流量來源匯總。請注意,如要在 APIs Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 CHANNEL_ID 替換成逗號分隔的清單,最多包含 500 個管道的管道 ID。

dimensions=day,insightTrafficSourceType
metrics=playlistViews,playlistStarts,playlistEstimatedMinutesWatched
filters=channel==CHANNEL_ID
裝置/作業系統

影片報表

已聲明著作權的影片每日裝置類型指標

這項查詢會針對特定內容擁有者聲明版權的影片,依裝置類型擷取每日觀看次數和預估觀看時間。結果會依照發生影片播放的裝置類型,按日分組。結果會依時間順序排列。

dimensions=day,deviceType
metrics=estimatedMinutesWatched,views
filters=claimedStatus==claimed
sort=day

在行動裝置上觀看已聲明版權的影片,每日作業系統指標

這項查詢會針對特定內容擁有者在行動裝置上聲明擁有權的影片,擷取每日觀看次數和系統估算的觀看時間。系統會根據使用者播放影片的作業系統,按照日期將結果分組。結果會依時間順序排列。

dimensions=day,operatingSystem
metrics=estimatedMinutesWatched,views
filters=claimedStatus==claimed;deviceType==MOBILE
sort=day

每日作業系統和裝置類型指標

這項查詢會擷取特定內容擁有者聲明版權的影片每日觀看次數和預估觀看時間。統計資料會依作業系統和裝置類型分組。結果會依時間順序排列。

dimensions=day,operatingSystem,deviceType
metrics=estimatedMinutesWatched,views
sort=day

播放清單報表

在 Android 作業系統上,針對播放清單觀看次數的裝置類型指標

這項查詢會針對內容擁有者的一或多個頻道中的播放清單,在 Android 裝置上擷取播放清單的觀看次數和預估觀看時間。系統會針對發生播放清單觀看次數的每種裝置類型傳回結果。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 CHANNEL_ID 替換為逗號分隔的清單,最多可包含 500 個管道的管道 ID。

dimensions=deviceType
metrics=playlistViews,playlistEstimatedMinutesWatched
filters=channel==CHANNEL_ID;operatingSystem==ANDROID

行動裝置播放清單觀看次數的作業系統指標

這項查詢會針對內容擁有者任何頻道的播放清單,擷取播放清單的觀看次數和行動裝置上的預估觀看時間。系統會針對每個發生播放清單觀看次數的作業系統傳回結果。

dimensions=operatingSystem
metrics=views,estimatedMinutesWatched
filters=deviceType==MOBILE
客層

影片報表

加州觀眾客層 (年齡層和性別)

這份報表會擷取加州觀眾觀看內容擁有者聲明擁有的內容時,觀眾的年齡層和性別統計資料。結果會依性別和年齡層排序。只要調整 filters 參數值,就能修改這項查詢,為全球所有觀眾或某個國家/地區、大陸、次大陸或美國其他州的所有觀眾擷取相同的統計資料。

dimensions=ageGroup,gender
metrics=viewerPercentage
filters=claimedStatus==claimed;province==US-CA
sort=gender,ageGroup
觀眾續看率

影片的觀眾續看率指標

這份報表可評估影片吸引觀眾續看的能力。你一次只能擷取單一影片的報表。請注意,如要在 API Explorer 中執行這項查詢,您必須將 filters 參數值中的字串 VIDEO_ID 替換為其中一個已上傳影片的影片 ID。請注意,目標對象留存報表不支援為 video 篩選器指定多個值。

在這個範例中,報表會使用 audienceType 篩選器限制回應,只納入自然觀看次數的資料,也就是使用者直接採取的動作 (例如搜尋影片或點選建議影片) 所產生的結果。因此,報表不會納入 TrueView 串流內廣告或 TrueView 顯示廣告的觀看次數資料。你可以移除篩選器,從所有觀眾類型擷取影片的觀眾續看率資料。

請注意,audienceType 篩選條件提供的資料可回溯至 2013 年 9 月 25 日。如果查詢使用篩選器嘗試擷取較早日期的資料,API 就不會傳回資料。不使用這個篩選器的查詢,則會在 2008 年 7 月 1 日後生效。

dimensions=elapsedVideoTimeRatio
metrics=audienceWatchRatio,relativeRetentionPerformance
filters=video==VIDEO_ID;audienceType==ORGANIC
收益/廣告

已聲明版權的內容收益和廣告成效指標

這項要求會擷取內容擁有者聲明版權的內容收益和廣告成效指標。報表會傳回單一資料列,其中包含指定日期範圍內每個要求指標的總計。

metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks
filters=claimedStatus==claimed

每日收益和廣告成效指標

這項要求會擷取內容擁有者聲明版權的內容每日收益和廣告成效指標。

dimensions=day
metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks
filters=claimedStatus==claimed

特定國家/地區的收益和廣告成效指標

這項要求會擷取內容擁有者聲明內容的國家/地區專屬收益和廣告成效指標。結果會依收益金額遞減排序,也就是說,列出的首個國家/地區,是合作夥伴預估收益最高的國家/地區。

dimensions=country
metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks
filters=claimedStatus==claimed
sort=-estimatedRevenue

前 10 名:收益最高的影片

針對由內容擁有者提出聲明且收益最高的 10 部影片,此要求會針對其中 10 部影片,擷取其收益和廣告成效指標。結果會依收益金額遞減排序,也就是說,第一部影片的預估收益最高。

dimensions=video
metrics=views,estimatedRevenue,estimatedAdRevenue,estimatedRedPartnerRevenue,grossRevenue,adImpressions,cpm,playbackBasedCpm,monetizedPlaybacks
filters=claimedStatus==claimed
maxResults=10
sort=-estimatedRevenue

不同廣告類型的廣告成效指標

這項要求會擷取內容擁有者聲明擁有權的內容廣告成效指標。系統會依廣告類型分組結果,方便您比較不同廣告類型的收益和千次曝光出價。

dimensions=adType
metrics=grossRevenue,adImpressions,cpm
filters=claimedStatus==claimed
sort=-adType