このページは Cloud Translation API によって翻訳されました。

YouTube Analytics API - Data Model

YouTube Analytics API を使用すると、YouTube アナリティクスのデータを含むカスタムレポートを生成できます。この API はチャンネルとコンテンツ所有者のレポートをサポートしています。レポートのフィールドは、ディメンションまたは指標のいずれかに分類されます。

ディメンションとは、データを集計するために使用される一般的な条件（アクションが発生した日付や、ユーザーが居住した国など）を指します。

レポートでは、データの各行にはディメンション値の組み合わせが一意になっています。そのため、レポートに選択したディメンションによって、そのレポート内の指標の値が YouTube でどのように計算されるかが決まります。
指標は、ユーザーアクティビティ、広告のパフォーマンス、推定収益に関連する個々の測定値です。ユーザーアクティビティの指標には、動画再生回数、評価（高評価と低評価）が含まれます。

アナリティクス API はフィルタリングと並べ替えのパラメータを提供しているので、呼び出し元アプリケーションはそれらの関数をネイティブにサポートする必要はありません。この API では、YouTube アナリティクスグループのデータを取得することもできます。このグループは、最大 500 個の動画、再生リスト、チャンネル、アセットのカスタムコレクションです。

レポートパラメータの選択

レポートをリクエストする場合、API の reports.query メソッドを使用して、レポート値の計算方法を決定する 5 つのパラメータが含まれます。

startDate パラメータと endDate パラメータでは、レポートにデータを含める期間を指定します。実際には、API レスポンスには、指定された日付まで、クエリの時点ですべての指標が使用可能になっているデータが含まれます。
metrics パラメータでは、レポートに含める測定値を指定します。チャネルレポートでは、指標がユーザーアクティビティを測定し、視聴回数や高評価などの値が含まれます。一部の指標では広告のパフォーマンスや推定収益も測定されます。
dimensions パラメータは、指標がどのようにグループ化されるかを示します。
filters パラメータでは、レポートデータをフィルタリングする方法を指定します。たとえば、チャネルのすべてのデータを返す代わりに、特定の国、動画、動画のグループの指標のみが含まれるようにレポートをフィルタリングできます。

注: この API を使用すると、動画、再生リスト、チャンネルのフィルタに複数の値を指定できます。その場合は、そのフィルタをディメンションのリストに含めることで、返される指標が動画、再生リスト、チャンネルごとにグループ化されます。

レポートオプションの例

たとえば、あるチャンネル所有者が、動画デバイスタイプレポートを取得して、モバイルデバイス、ゲーム機、テレビなどでチャンネルの動画が再生された回数を判断するとします。

チャンネル所有者は、startDate パラメータを 2015-06-01 に、endDate パラメータを 2015-07-31 に設定します。これらの値に基づき、レポートには 2 か月間のデータが含まれます。
デバイスタイプレポートでは views と estimatedMinutesWatched の指標がサポートされているため、チャンネル所有者は metrics パラメータを views,estimatedMinutesWatched に設定できます。
dimensions パラメータの場合、チャンネル所有者はいくつかのオプションを使用できます。次のリストではこの 2 つを示しますが、このセクションの後半では filters パラメータ値の説明で 3 つ目について説明します。
- パラメータ値を deviceType に設定すると、レポートの対象期間全体で、視聴回数と総再生時間がデバイスタイプごとにグループ化されます。そのため、この値を使用すると、次のような疑問に対する答えを得ることができます。
  - 2015 年 6 月 1 日～ 2015 年 7 月 31 日の期間に、モバイルデバイスでこのチャンネルの動画を視聴した回数をお知らせください。
  - 2015 年 6 月 1 日～ 2015 年 7 月 31 日の期間に、ゲーム機でチャンネルの動画を視聴した回数をお知らせください。
  このレポートには、実際にはデバイスタイプごとに合計視聴回数と総再生時間が表示されます。
- パラメータ値を day,deviceType に設定すると、レポート期間中、視聴回数と総再生時間はデバイスタイプごとに日単位で計算されます。そのため、この値を使用すると、次のような疑問に対する答えを得ることができます。
  - 2015 年 6 月 1 日に、チャンネルの動画をモバイルデバイスで視聴した回数をお知らせください。
  - 2015 年 7 月 14 日にチャンネルの動画がテレビで視聴された回数は？
最後に、filters パラメータを使用すると、チャンネル所有者は特定のフィルタ値に一致するデータのみをレポートに含めるよう制限できます。レポートでサポートされているフィルタオプションが多すぎてすべて把握できないため、これらの例で生成されるのはほんのわずかです。
- チャンネル所有者は、Android オペレーティングシステムについてのみ値を返すようにリクエストをフィルタできます。（レポート期間中に Android モバイルデバイスで視聴された回数）
- チャンネル所有者は、リクエストをフィルタして、特定の国の値のみを返すことができます。（レポート期間中に毎日、カナダで動画が視聴された回数）
- チャンネル所有者は、リクエストをフィルタリングして特定の動画についてのみ値を返すことができます。ただし、video フィルタでサポートされている値のカンマ区切りリストはサポートされているため、多くの動画のデータがレポートに含まれる場合があります。
  
  また、video フィルタで複数の値を指定する場合は、動画もディメンションとして指定できます。つまり、dimensions パラメータは値 deviceType,video と day,deviceType,video もサポートします。
  - チャンネル所有者がディメンションのリストに video を含めた場合、指標は各動画の個別の値を指定します。（2015 年 6 月 1 日にゲーム機で動画 XYZ を視聴された回数）
  - チャンネル所有者がディメンションのリストに video を含めない場合、これらの指標は、指定されたすべての動画の合計値を示します。（2015 年 6 月 1 日にゲーム機で ABC、DEF、XYZ の動画が視聴された回数）

レポートの取得

レポートを取得するには、取得した GET リクエストを API の reports.query メソッドに送信し、取得するレポートを定義するパラメータを指定します。

API でサポートされているレポートの一覧については、チャンネルレポートとコンテンツ所有者レポートに関するドキュメントをご覧ください。各レポート定義は、レポートで metrics、dimensions、filters のパラメータに指定できる値を識別します。

指標の集計と削除済み項目

YouTube Analytics API のレスポンスに、削除されたアイテムの指標の内訳は含まれません。たとえば、チャンネル所有者が動画を削除した場合、API レスポンスにその動画が含まれなくなり、動画ごとに指標が返されます。ただし、一連のリソースの指標を集計したレポートには、削除済みアイテムに関連付けられた指標も含まれます。

たとえば、チャンネル所有者が 2 つのレポートを取得したとします。最初のレポートには、特定の期間におけるチャンネルのすべての動画における 1 日の合計視聴回数が表示されます。2 つ目のレポートでは、同じ期間中の 1 日の合計視聴回数が動画ごとに表示されます。

この場合、最初のレポートの数値には、最初のレポートに日次集計が含まれるため、削除された動画の視聴回数も含まれます。ただし、削除されたレポートには動画ごとに視聴がリストされているため、2 番目のレポートには削除された項目に関連付けられた視聴回数は含まれません。そのため、レポートの対象の期間中にチャンネルが動画を削除した場合、最初のレポートで報告される 1 日の再生回数の合計は、2 番目のレポートでは動画ごとの 1 日の再生回数の合計よりも多くなる可能性があります。

データの匿名化

一部の YouTube アナリティクスのデータは、指標が特定のしきい値を満たしていない場合、制限されます。これは、さまざまなレポートで発生します。具体的には、次のような場合、レポートにすべてのデータ（または一部）が含まれないことがあります。

指定した期間に動画またはチャンネルのトラフィックが制限されている

または
特定のソースを満たさないフィルタまたはディメンション（トラフィックソースや国など）が選択されています。

データが制限されると、データの集計方法によって、レポートの合計値が一致しない場合があります。

たとえば、チャンネル所有者が 2 つのレポートを取得したとします。最初のレポートには特定の動画の合計視聴回数が表示され、2 番目のレポートには国別の視聴回数が表示されます。指定の期間内に 1,000 回視聴されたとします。米国で 500 回、カナダで 498 回、フランスで 2 回発生したとします。

この例では、最初のレポートでは動画が 1, 000 回視聴されたことがわかります。2 つ目のレポートでは、米国で 500 回、カナダで 498 回しか視聴されていないことがわかります。そのため、2 つのレポートの合計視聴回数には差異が生じます。なお、2 回目のレポートでは、他に 2 回視聴された（フランスで視聴された）ことは 1 つも表示されません。

実際のデータが制限されるしきい値は公開されず、YouTube の裁量で変更される可能性があります。

制限付きのデータ型

YouTube アナリティクスのレポートでは、次のデータが制限されることがあります。

年齢や性別などのユーザー属性データ。
視聴者の居住地域に関連する指標やディメンション（国または地域など）を含む地域データ。ただし、収益指標に地域別のしきい値は適用されません。
動画の視聴につながった検索語句や外部 URL など、特定のトラフィックソースに関連する指標です。たとえば、非常に少ない視聴回数につながる検索語句や URL はレポートに表示されませんが、多くの視聴者をコンテンツに誘導する語句や URL は表示されます。

YouTube アナリティクスのレポートでのデータの限定について詳しくは、YouTube ヘルプセンターをご覧ください。

割り当て使用量

API リクエストを行うたびに、API 使用量割り当ての 1 単位としてカウントされます。割り当て上限は、Google API Console の [割り当て] パネルに表示されます。