Introduction

このドキュメントでは、YouTube Analytics API と YouTube Reporting API で YouTube アナリティクス データにアクセスする方法の類似点と相違点について説明します。このドキュメントの目的は、アプリケーションに適した API を選択できるようにすることです。

どちらの API でも、YouTube アナリティクス データを取得できます。また、どちらの API も YouTube チャンネルの所有者と YouTube コンテンツ所有者をサポートし、それぞれが特定のレポートセットにアクセスできます。

  • チャンネル レポート: 指定したチャンネルについて、ユーザー アクティビティの指標が表示されます。

  • コンテンツ所有者レポート: 指定した YouTube コンテンツ所有者にリンクされているすべてのチャンネルの指標が集計されます。たとえば、レコード レーベルは、レーベルの全アーティストの YouTube チャンネルについて合算した統計情報を含むレポートを取得できます。ユーザー アクティビティの指標を含むコンテンツや、収益や広告のパフォーマンスに関連する指標を含むコンテンツ所有者レポートがあります。

Reporting API を使用すると、一部のコンテンツ所有者はシステム管理の広告収益レポートにアクセスできます。システム管理レポートのデータは、Reporting API を使用してのみ取得できます。

YouTube アナリティクスと YouTube Reporting API へのすべてのリクエストは、リクエストされたデータを所有するチャンネルまたはコンテンツ所有者の承認を得る必要があります。

レポートの内容

API が取得するレポートには、次の 2 種類のデータが含まれます。

  • ディメンションとは、ユーザー アクティビティが発生した日付やユーザーがいる国など、データの集計に使用される一般的な条件です。

    レポートでは、データの各行にディメンション値の一意の組み合わせがあります。そのため、各行のディメンション値の組み合わせは、その行の主キーとして機能します。

  • 指標とは、ユーザーのアクティビティ、広告のパフォーマンス、推定収益などの個々の測定値のことです。ユーザー アクティビティの指標には、動画の再生回数や評価(高評価と低評価)などがあります。

アプリケーションに適した API を選択する

YouTube Analytics API
YouTube Analytics API は、リアルタイムのターゲット クエリに対応しており、カスタム YouTube アナリティクス レポートを生成できます。API にはフィルタリングと並べ替えのパラメータが提供されるため、呼び出し元のアプリケーションでこれらの関数をネイティブにサポートする必要はありません。

各 API リクエストでは、データが返される期間を指定します。また、API を使用して週次と月次のデータ セットを取得することもできます。そのため、呼び出し元のアプリケーションでは、取得したデータセットを保存したり、期間をまたいで統計情報を集計したりする必要はありません。
YouTube Reporting API
YouTube Reporting API は、チャンネルまたはコンテンツ所有者の YouTube アナリティクスのデータを含む一括レポートを取得します。大規模なデータセットをインポートでき、そのデータのフィルタリング、並べ替え、マイニングを行うツールを提供するアプリケーション向けに設計されています。

各レポートには事前定義された一連のフィールドが含まれています。デベロッパーは、API を使用してレポート作成ジョブのスケジュールを設定します。各レポートは、YouTube が生成するレポートを識別します。その後、非同期でダウンロード可能な日次レポートが生成されます。各レポートには、固有の 24 時間分のデータが含まれます。

また、YouTube クリエイター ツール内の対応するレポートにアクセスできるコンテンツ所有者に対しては、システム管理レポート一式が自動的に生成されます。これらのレポートでは、広告収益データにプログラムでアクセスできます。

サポートされるレポート

次の表に、API を使用して取得できるレポートの種類を示します。ターゲット設定したクエリは YouTube Analytics API で、一括レポートは YouTube Reporting API で取得できます。

一方の API で利用できるデータが、もう一方の API では利用できない場合があります。たとえば、YouTube Analytics API ではユーザー アクティビティの指標を週単位または月単位で取得できますが、YouTube Reporting API ではそのデータを自身で集計する必要があります。一方、YouTube Reporting API はコンテンツ所有者向けのアセット レポートをサポートしていますが、そのデータを YouTube Analytics API から取得することはできません。

レポートの種類
動画レポート チャンネル(クエリまたは一括)とコンテンツ所有者(クエリまたは一括)でサポートされています。

動画レポートは、チャンネルの動画またはコンテンツ所有者の動画に関するすべてのユーザー アクティビティの統計情報を提供します。たとえば、これらのレポートには動画の視聴回数が含まれています。YouTube Analytics API の一部のコンテンツ所有者の動画レポートには、推定収益や広告のパフォーマンス指標も含まれます。
再生リストレポート チャンネル(クエリまたは一括)とコンテンツ所有者(クエリまたは一括)でサポートされています。

再生リストレポートには、再生リストのコンテキスト内で発生した動画再生回数に関する統計情報が表示されます。YouTube Reporting API は再生リストの視聴者維持率レポートをサポートしていますが、YouTube Analytics API は同様のレポートをサポートしていません。
広告のパフォーマンス レポート コンテンツ所有者向けの機能です(クエリまたは一括)。

広告の掲載結果レポートでは、動画の再生中に配信された広告について、インプレッション ベースの指標が提供されます。この指標では広告のインプレッションごとにインプレッションが考慮され、動画再生ごとに複数のインプレッションがカウントされる場合があります。
推定収益レポート コンテンツ所有者にサポートされています(一括)。

推定収益レポートには、Google の販売元と広告以外のソースからの動画の合計推定収益額が表示されます。これらのレポートには、広告のパフォーマンス指標も含まれています。なお、システム管理レポートには実際の収益が含まれます。
アセット レポート コンテンツ所有者にサポートされています(一括)。

アセット レポートには、コンテンツ所有者のアセットにリンクされている動画に関するユーザー アクティビティの指標が表示されます。コンテンツ所有者が動画をコンテンツ所有者のアセットのいずれかの一致として申し立てた場合、その動画はコンテンツ所有者のレポートに含まれます。コンテンツ所有者または別の YouTube ユーザーがアップロードした動画です。
システム管理レポート YouTube クリエイター ツールの [レポート] セクションの対応するレポートにアクセスできるコンテンツ所有者が使用できます。

システム管理レポートでは、アセットと動画で得られた実際の収益データを確認できます。追加レポートには、申し立てを行った動画と、それらの動画と一致するアセットが一覧表示されます。なお、現時点ではすべてのクリエイター ツール レポートを API で利用できるわけではありません。

注: YouTube は、クリエイター ツール内の対応するレポートへのアクセス権を持つコンテンツ所有者のために、システム管理レポートを自動的に生成します。そのため、これらのレポートを取得するプロセスは、このリストの他の種類のレポートと異なります。詳しくは、システム管理レポートのドキュメントをご覧ください。

主な違い

次の表は、YouTube アナリティクスと Reporting API の重要な違いをまとめたものです。

機能 YouTube Analytics API YouTube Reporting API
データを取得するプロセス 各 API リクエストでは、取得するディメンションと指標、データが返される期間を指定します。 アプリケーションは、レポート作成ジョブをスケジュールします。ジョブごとに YouTube が日次レポートを生成し、非同期でダウンロードできます。
期間 一部の API レポートでは、ユーザー アクティビティが発生した日付が指定されています。一部のレポートでは、ユーザー アクション指標を月ごとに集計するためのディメンションがサポートされています。 すべての API レポートには、ユーザー アクティビティが発生した日付が指定されています。API を使用するアプリケーションは、データを定期的に集計する機能を実装できます。
データのフィルタリング レポートをフィルタして、ディメンションに特定の値を持つ行のみを含めることができます。API では、フィルタとしてのみ使用されるディメンション(大陸subContinent など)もサポートされています。 API では、完全なデータセットの一括ダウンロードがサポートされます。フィルタのみのディメンションの場合、フィルタはサポートされず、データを返すこともできません。クライアント アプリケーションはダウンロードしたデータを保存し、データをフィルタするための独自の機能を実装します。
並べ替え レポートは、返された指標値に基づいて並べ替えることができます。レポートによっては、一部の結果しかサポートされないことがあります。たとえば、チャンネルで最も視聴回数の多い動画を一覧表示するレポートでは、最大 200 行が返されます。 この API は、完全なデータセットの一括ダウンロードをサポートしています。クライアント アプリケーションは、ダウンロードしたデータを並べ替える独自の機能を実装できます。
列挙型 API レポートには、「ANDROID」や「CHANNEL」などのテキスト値が含まれ、列挙型のディメンション値を示します。 API レポートには、テキスト値にマッピングできる整数が含まれます。
割り当て API サーバーは各クエリを評価して、その割り当てコストを決定します。方法については、割り当て使用量のセクションで詳しく説明しています。 データは一度取得された後、アプリケーション内でフィルタリング、並べ替え、クエリが実行されるため、割り当て使用量が問題になることはありません。
ユニーク レポート
  • 字幕に関するユーザー アクティビティ
  • 再生リストの視聴者維持率データ
  • コンテンツ所有者の推定収益レポート(2 種類のレポートを利用可能)
  • コンテンツ所有者向けのアセット レポート(11 種類のレポートを利用可能)
固有のサイズ group(フィルタ専用ディメンション)
Continent(フィルタ専用ディメンション)
subContinent(フィルタ専用ディメンション)
month
isCurated==1(フィルタ専用ディメンション)
viewsPerPlaylistStart
averageTimeInPlaylist
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
独自の指標 uniques
relativeRetentionPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
estimated_partner_adsense_revenue
estimated_saved161 google_playlists

API の命名の違い

2 つの API では現在、ディメンションと指標の識別に異なる命名規則が使用されています。現時点では、YouTube Analytics API 名ではキャメルケースが使用されますが、YouTube Reporting API 名ではアンダースコア区切りの名前が使用されます。

次の表は、2 つの API で同じ指標とディメンションを識別するために使用する名称をまとめたものです。場合によっては、2 つの名前の違いが、キャメルケースからアンダースコアへの変換後よりも大きくなります。たとえば、YouTube Analytics API の video ディメンションは、YouTube Reporting API では video_id という名前になります。

ディメンション

YouTube Analytics API 名 YouTube Reporting API 名
adType ad_type
年齢層 age_group
アセット asset_id
オーディエンスの種類 audience_retention_type
channel チャンネル ID
claimedStatus claimed_status(申請済みステータス)
コンテンツ所有者 content_owner_id
country country_code(国コード)
date
デバイスの種類 device_type
elapsedVideoTimeRatio elapsed_video_time_percentage
性別 [gender] 性別 [gender]
insightPlaybackLocationDetail playback_location_detail
insightPlaybackLocationType playback_location_type
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType traffic_source_type
liveOrOnDemand live_or_on_demand
オペレーティング システム オペレーティング システム
再生リスト playlist_id
province regional_code(都道府県コード)
sharingService sharing_service
subscribedStatus(登録ステータス) subscribed_status
subtitleLanguage subtitle_language
アップロードしたユーザーの種類 uploader_type
動画 video_id

指標

YouTube Analytics API 名 YouTube Reporting API 名
広告収益 estimated_partner_ad_revenue
annotationImpression annotation_impressions
annotationClickableImpression annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpression annotation_closable_impressions
annotationCloses annotation_closes
annotationCloseRate annotation_close_rate
audienceWatchRatio audience_retention_percentage
averageViewDuration average_view_duration_seconds
averageViewPercentage average_view_duration_percentage
cardClickRate card_click_rate
cardClicks card_clicks
cardImpression card_impressions
cardTeaserClickRate カード ティーザーのクリックレート
cardTeaserClicks カード ティーザー クリック
cardTeaser インプレッション数 card_teaser_impressions(カードティーザー インプレッション)
comments comments
低評価 低評価
収益 estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
売上総収益 estimated_youtube_ad_revenue
impressionBasedCpm estimated_cpm
表示回数 ad_impressions
高評価 高評価
monetizedPlaybacks estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_added
savesRemoved playlist_saves_removed
共有 共有
チャンネル登録者数の増加 subscribers_gained
チャンネル登録者の損失 subscribers_lost
videosAddedToplaylist videos_added_to_playlists
videosRemovedFromPlayback videos_removed_from_playlist
viewerPercentage views_percentage
視聴回数 視聴回数