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 が生成するレポートが識別されます。その後、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 Studio の [レポート] メニュー内の対応するレポートにアクセスできるコンテンツ所有者が利用できます。

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

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

主な違い

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

機能 YouTube Analytics API YouTube Reporting API
データを取得するプロセス 各 API リクエストでは、取得するディメンションと指標、データが返される期間を指定します。 アプリケーションはレポートジョブのスケジュールを設定します。YouTube は、ジョブごとに非同期でダウンロード可能なレポートを毎日生成します。
期間 一部の API レポートでは、ユーザー アクティビティが発生した日付が指定されています。こうしたレポートの一部では、ユーザー アクション指標を月ごとに集計するためのディメンションがサポートされています。 すべての API レポートでは、ユーザー アクティビティが発生した日を指定します。この API を使用するアプリケーションでは、定期的にデータを集計する機能を実装できます。
データのフィルタリング レポートをフィルタして、ディメンションに特定の値を持つ行のみを表示できます。この API では、フィルタとしてのみ使用される一部のディメンション(consumesubContinent など)もサポートされています。 この API では、完全なデータセットの一括ダウンロードがサポートされています。フィルタリングはサポートされていません。また、フィルタ専用ディメンションのデータを返すこともできません。クライアント アプリは、ダウンロードしたデータを保存し、データをフィルタするための独自の機能を実装します。
並べ替え レポートは、返された指標値に基づいて並べ替えることができます。レポートによっては、表示できる結果が限られています。たとえば、チャンネルで最も再生回数の多い動画を一覧表示したレポートには、最大 200 行が返されます。 この API では、完全なデータセットの一括ダウンロードがサポートされます。クライアント アプリケーションは、ダウンロードしたデータを並べ替える独自の機能を実装できます。
列挙型 API レポートには、「ANDROID」や「CHANNEL」などのテキスト値が含まれ、列挙ディメンション値を表します。 API レポートには、テキスト値にマッピングできる整数が含まれます。
割り当て API サーバーは各クエリを評価し、クォータ コストを算出します。手法について詳しくは、割り当て使用量セクションをご覧ください。 データは 1 回取得されてから、アプリケーション内でフィルタリング、並べ替え、クエリが実行されるため、割り当て使用量は問題になりません。
ユニーク レポート
  • 字幕に関するユーザー アクティビティ
  • 再生リストの視聴者維持率データ
  • コンテンツ所有者向けの推定収益レポート(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
独自の指標 独自
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_revenue_purchased_playlists}
estimated_revenue_revenue
estimated_partner_doubleclick_revenueplaylist_saves_addedplaylist_saves_removed

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
ageGroup age_group
asset asset_id
audienceType audience_retention_type
channel channel_id
claimedStatus claimed_status
contentOwner content_owner_id
country country_code
date
deviceType 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
operatingSystem operating_system
再生リスト playlist_id
province province_code
sharingService sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
動画 video_id

指標

YouTube Analytics API 名 YouTube Reporting API 名
adEarnings estimated_partner_ad_revenue
annotationImpressions annotation_impressions
annotationClickableImpressions annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpressions 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
cardImpressions card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpressions card_teaser_impressions
comments comments
低評価 低評価
収益 estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
grossRevenue 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
共有 共有
subscribersGained subscribers_gained
subscribersLost subscribers_lost
videosAddedToPlaylists videos_added_to_playlists
videosRemovedFromPlaylists videos_removed_from_playlist
viewerPercentage views_percentage
視聴回数 視聴回数