YouTube Analytics API を使用すると、YouTube アナリティクス データを含むカスタム レポートを生成できます。この API は、チャンネルとコンテンツ所有者のレポートをサポートしています。レポートのフィールドは、ディメンションまたは指標として分類されます。
-
ディメンションは、データを集計するために使用される一般的な条件です。たとえば、アクションが発生した日付やユーザーが居住している国などがあります。
レポートでは、各データ行にディメンション値の一意の組み合わせがあります。そのため、レポートで選択するディメンションによって、YouTube がそのレポートの指標の値を計算する方法が決まります。
- 指標は、ユーザー アクティビティ、広告のパフォーマンス、推定収益に関連する個々の測定値です。ユーザー アクティビティの指標には、動画の視聴回数や評価（高評価と低評価）などがあります。
Analytics API にはフィルタリング パラメータと並べ替えパラメータが用意されているため、呼び出し元アプリケーションでこれらの関数をネイティブにサポートする必要はありません。また、この API を使用すると、YouTube アナリティクス グループのデータを取得することもできます。グループは、最大 500 個の動画、再生リスト、チャンネル、アセットを独自にグループ化したものです。
レポートのパラメータを選択する
API の reports.query メソッドを使用してレポートをリクエストすると、レポート値の計算方法を決定する 5 つのパラメータが API リクエストに含まれます。
-
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の値もサポートしています。
-
レポートの取得
レポートを取得するには、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 アナリティクス API のレスポンスには、削除されたアイテムの指標の内訳は含まれません。たとえば、チャンネル所有者が動画を削除した場合、その動画は動画ごとの指標を返す API レスポンスに表示されなくなります。ただし、一連のリソースの指標を集計するレポートには、削除されたアイテムに関連付けられた指標が引き続き含まれます。
たとえば、チャンネル所有者が 2 つのレポートを取得するとします。最初のレポートには、特定の期間におけるチャンネルのすべての動画の 1 日あたりの合計視聴回数が表示されます。2 つ目のレポートには、同じ期間の動画ごとの 1 日あたりの合計視聴回数が表示されます。
この場合、最初のレポートには、後で削除された動画の視聴回数が含まれます。これは、最初のレポートに日ごとの集計が含まれているためです。ただし、2 つ目のレポートには、削除されたアイテムに関連付けられた視聴回数は含まれません。これは、2 つ目のレポートでは動画ごとに視聴回数が表示されるためです。そのため、レポートの対象期間中にチャンネルで動画が削除された場合、最初のレポートで報告された 1 日の合計視聴回数が、2 番目のレポートの 1 日の動画ごとの視聴回数の合計よりも多くなることがあります。
データの匿名化
指標が一定のしきい値に達していない場合、YouTube アナリティクスの一部のデータは限定的にしか利用できないことがあります。この問題は、さまざまなレポートで発生する可能性があります。つまり、以下の条件を満たしていれば、レポートにデータの一部またはすべてが含まれていない可能性があります。
-
指定した期間のトラフィックが少ない動画やチャンネルがある場合、
または
-
値が一定のしきい値を満たしていない、トラフィック ソースや国などのフィルタやディメンションを選択した場合。
データが限定的である場合、レポートでのデータ集計方法によっては、各レポートで報告される合計値に差異が生じることがあります。
たとえば、チャンネル所有者が 2 つのレポートを取得するとします。1 つ目のレポートには特定の動画の総視聴回数が表示され、2 つ目のレポートにはその動画の総視聴回数が国別に表示されます。指定された期間中に動画が 1,000 回視聴されており、そのうち 500 回は米国、498 回はカナダ、2 回はフランスで視聴されたとします。
この例では、最初のレポートには動画の視聴回数が 1, 000 回と表示されます。2 つ目のレポートでは、米国で 500 回、カナダで 498 回視聴されたことのみが示されます。そのため、2 つのレポートの合計視聴回数に差異が生じます。なお、2 つ目のレポートには、この動画がもう 2 回視聴されたことや、フランスで視聴されたことについて示されません。
データが限定的になる実際のしきい値は公開されておらず、YouTube の裁量で変更される可能性があります。
一部のデータ型
YouTube アナリティクスのレポートで、次のデータが制限されることがあります。
- 年齢や性別などのユーザー属性データ。
- 視聴者の国や地域など、視聴者の所在地に関連する指標やディメンションを含む地理データ。ただし、レポートでは、収益指標に地域ごとのしきい値は適用されません。
- 動画の視聴につながった検索キーワードや外部 URL など、特定のトラフィック ソースに関連する指標。たとえば、視聴回数が非常に少ない検索語句や URL はレポートに表示されませんが、多くの視聴者をコンテンツに誘導している語句や URL は引き続き表示されます。
YouTube アナリティクス レポートの限定的データについて詳しくは、YouTube ヘルプセンターをご覧ください。
割り当て使用量
API リクエスト 1 回につき、API 使用量割り当ての 1 単位がカウントされます。割り当て上限は、Google API Console の [割り当て] パネルで確認できます。