YouTube Analytics API を使用すると、YouTube アナリティクス データを含むカスタム レポートを生成できます。この API は、チャンネルとコンテンツ所有者向けのレポートをサポートしています。レポートのフィールドは、ディメンションまたは指標のいずれかとして特徴付けられます。
-
ディメンション は、アクションが発生した日付やユーザーが居住していた国など、データの集計に使用される一般的な条件です。
レポートでは、データの各行にディメンション値の一意の組み合わせが含まれます。そのため、レポートで選択するディメンションによって、YouTube がそのレポートの指標の値を計算する方法が決まります。
- 指標 は、ユーザー アクティビティ、広告のパフォーマンス、推定収益に関連する個々の測定値です。ユーザー アクティビティの指標には、動画の視聴回数や評価（高評価と低評価）などがあります。
Analytics API にはフィルタリング パラメータと並べ替えパラメータが用意されているため、呼び出し元のアプリケーションでこれらの機能をネイティブにサポートする必要はありません。この API を使用すると、YouTube アナリティクス グループのデータを取得することもできます。グループは、最大 500 個の動画、再生リスト、チャンネル、アセットのカスタム コレクションです。
レポート パラメータを選択する
API の reports.query メソッドを使用してレポートをリクエストすると、API リクエストにはレポート値の計算方法を決定する 5 つのパラメータが含まれます。
-
startDateパラメータとendDateパラメータは、レポートにデータが含まれる期間を指定します。実際には、API レスポンスには、クエリ内のすべての指標がクエリ時に利用可能な最終日までのデータが含まれます。 -
metricsパラメータは、レポートに含める測定値を指定します。チャンネル レポートでは、指標はユーザー アクティビティを測定し、視聴回数や高評価などの値が含まれます。一部の指標では、広告のパフォーマンスや推定収益も測定されます。 -
dimensionsパラメータは、指標をグループ化する方法を示します。 -
filtersパラメータは、レポートデータをフィルタリングする方法を示します。たとえば、チャンネルのすべてのデータを返すのではなく、特定の国、動画、または動画グループの指標のみを含むようにレポートをフィルタできます。注: この API を使用すると、動画、再生リスト、チャンネルのフィルタに複数の値を指定できます。その場合は、返される指標が動画、再生リスト、チャンネルでグループ化されるように、ディメンションのリストにそのフィルタを含めることもできます。
レポート オプションの例
たとえば、チャンネル所有者が動画デバイスタイプ レポートを取得して、チャンネルの動画の視聴回数がモバイル デバイス、ゲーム機、テレビなどでどれだけ発生したかを確認するとします。
-
チャンネル所有者は、
startDateパラメータを2015-06-01に、endDateパラメータを2015-07-31に設定します。これらの値に基づいて、レポートには 2 か月間のデータが含まれます。 -
デバイスタイプ レポートは views 指標と estimatedMinutesWatched 指標をサポートしているため、チャンネル所有者は
metricsパラメータをviews,estimatedMinutesWatchedに設定します。 -
dimensionsパラメータには、チャンネル所有者が選択できるオプションがいくつかあります。そのうちの 2 つを次のリストに示します。3 つ目は、このセクションの後半でfiltersパラメータ値の説明で説明します。-
パラメータ値を
deviceTypeに設定すると、レポートの対象期間全体の視聴回数と総再生時間がデバイスタイプ別にグループ化されます。この値を使用すると、レポートデータは次のような質問に答えます。- 2015 年 6 月 1 日から 2015 年 7 月 31 日までの間に、チャンネルの動画がモバイル デバイスで視聴された回数は何回ですか？
- 2015 年 6 月 1 日から 2015 年 7 月 31 日までの間に、チャンネルの動画がゲーム機で視聴された回数は何回ですか？
レポートには、デバイスタイプごとの合計視聴回数と総再生時間が含まれます。
-
パラメータ値を
day,deviceTypeに設定すると、レポート対象期間中の各日の視聴回数と総再生時間がデバイスタイプ別に計算されます。この値を使用すると、レポートデータは次のような質問に答えます。- 2015 年 6 月 1 日に、チャンネルの動画がモバイル デバイスで視聴された回数は何回ですか？
- 2015 年 7 月 14 日に、チャンネルの動画がテレビで視聴された回数は何回ですか？
-
-
最後に、
filtersパラメータを使用すると、チャンネル所有者は特定のフィルタ値に一致するデータのみを含むようにレポートを制限できます。レポートではフィルタリング オプションが多すぎてすべてを説明できないため、これらの例は生成できるレポートの一部にすぎません。-
チャンネル所有者は、リクエストをフィルタして、Android オペレーティング システムの値のみを返すことができます。（レポート対象期間中に Android モバイル デバイスで視聴された回数は何回ですか？）
-
チャンネル所有者は、リクエストをフィルタして、特定の国の値のみを返すことができます。（レポート対象期間中の各日にカナダで動画が視聴された回数は何回ですか？）
-
チャンネル所有者は、リクエストをフィルタして、特定の動画の値のみを返すことができます。ただし、動画フィルタは値のカンマ区切りのリストをサポートしているため、レポートには多くの動画のデータが含まれる可能性があります。
また、動画フィルタで複数の値を指定する場合は、動画をディメンションとして指定することもできます。つまり、
dimensionsパラメータはdeviceType,videoとday,deviceType,videoの値もサポートしています。
-
データの更新速度とレイテンシ
YouTube Analytics API はターゲット クエリをサポートしていますが、基盤となる分析データはリアルタイムではありません。通常、データ処理には 48 ～ 72 時間のレイテンシが発生します。そのため、API レスポンスには最新のデータは含まれません。レポートの endDate には、リクエストされたすべての指標が完全に処理された最終日までのデータのみが含まれます。
データのレイテンシを考慮すると、API から返されるデータと YouTube Studio に表示されるリアルタイム指標の間に差異が生じることがあります。現在の視聴回数、高評価数、コメント数など、個々の動画のリアルタイム統計情報が必要な場合は、YouTube Analytics API ではなく、YouTube Data API の
メソッドvideos.listを使用してください。
レポートを取得する
レポートを取得するには、取得するレポートを定義するパラメータを指定して、API の reports.query メソッドに承認済みの GET リクエストを送信します。
API がサポートするレポートのリストについては、チャンネル レポートとコンテンツ所有者レポートのドキュメントをご覧ください。各レポート定義では、レポートで metrics、dimensions、filters パラメータに使用できる値が示されています。
ベスト プラクティス
YouTube Analytics API を使用するアプリケーションは、常に次のプラクティスに従う必要があります。
- レスポンスのヘッダー行を使用して、レポートの列の順序を決定します。たとえば、レポートの説明に視聴回数が最初の指標として記載されているからといって、レスポンスで返される最初の指標が視聴回数であると想定しないでください。代わりに、レスポンスのヘッダー行を使用して、そのデータを含む列を特定します。
- YouTube Data API を使用して、YouTube Analytics API レスポンスで識別されたリソースの追加メタデータを取得します。YouTube API サービス デベロッパー ポリシー（セクション III.E.4.b ～ III.E.4.d）に記載されているように、API クライアントは 30 日後にその API から保存されたリソース メタデータを削除するか、更新する必要があります。
集計指標と削除されたアイテム
YouTube Analytics API レスポンスには、削除されたアイテムの指標の内訳は含まれません。たとえば、チャンネル所有者が動画を削除した場合、動画ごとの指標を返す API レスポンスにはその動画は表示されなくなります。ただし、一連のリソースの指標を集計するレポートには、削除されたアイテムに関連付けられた指標が引き続き含まれます。
たとえば、チャンネル所有者が 2 つのレポートを取得するとします。最初のレポートには、特定の期間におけるチャンネルのすべての動画の 1 日あたりの合計視聴回数が表示されます。2 つ目のレポートには、同じ期間の 1 日あたりの合計視聴回数が動画ごとに表示されます。
この場合、最初のレポートには、後で削除された動画の視聴回数が含まれます。これは、最初のレポートに 1 日ごとの集計が含まれているためです。ただし、2 つ目のレポートには、削除されたアイテムに関連付けられた視聴回数は含まれません。これは、2 つ目のレポートに動画ごとの視聴回数が表示されるためです。その結果、レポートの対象期間中にチャンネルが動画を削除した場合、最初のレポートに報告される 1 日あたりの合計視聴回数は、2 つ目のレポートの 1 日あたりの動画固有の視聴回数の合計よりも多くなる可能性があります。
データの匿名化
指標が一定のしきい値を満たしていない場合、一部の YouTube アナリティクス データは限定されます。これは、さまざまなレポートで発生する可能性があります。実際には、次の場合、レポートにすべてのデータ（または一部のデータ）が含まれない可能性があります。
-
指定した期間の動画またはチャンネルのトラフィックが少ない場合
または
-
値が一定のしきい値を満たしていないフィルタまたはディメンション（トラフィック ソースや国など）を選択した場合。
データが限定的である場合、レポートでのデータ集計方法によっては、各レポートで報告される合計値に差異が生じることがあります。
たとえば、チャンネル所有者が 2 つのレポートを取得するとします。最初のレポートには特定の動画の合計視聴回数が表示され、2 つ目のレポートにはその動画の合計視聴回数が国別に表示されます。 指定された期間中に動画が 1,000 回視聴されており、そのうち 500 回は米国、498 回はカナダ、2 回はフランスで視聴されたとします。
この例では、最初のレポートには動画が 1, 000 回視聴されたことが示されます。2 つ目のレポートには、米国で 500 回、カナダで 498 回視聴されたことのみが示されます。そのため、2 つのレポートの合計視聴回数には差異が生じます。2 つ目のレポートには、他の 2 回の視聴（またはフランスでの視聴）が発生したことは示されません。
データが限定的になる実際のしきい値は公開されておらず、YouTube の裁量で変更される可能性があります。
一部のデータ型
YouTube アナリティクス レポートでは、次のデータが限定される場合があります。
- 年齢や性別などのユーザー属性データ。
- 視聴者の国や地域など、視聴者の国や地域に関連する指標やディメンションを含む地理データ。ただし、レポートでは、収益指標に地理的しきい値は適用されません。
- 動画の視聴につながった検索語句や外部 URL など、特定のトラフィック ソースに関連する指標。たとえば、視聴回数が非常に少ない検索語句や URL はレポートに表示されませんが、多くの視聴者をコンテンツに誘導する語句や URL は引き続き表示されます。
YouTube アナリティクス レポートの限定的データについて詳しくは、YouTube ヘルプセンターをご覧ください。
割り当て使用量
API リクエストを行うたびに、API 使用量割り当ての 1 単位としてカウントされます。割り当て上限は、Google API Console の [割り当て] パネルで確認できます。