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 か月間のデータが含まれます。デバイスタイプ レポートは、視聴回数と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 モバイル デバイスで発生した視聴回数）
チャンネル所有者は、リクエストをフィルタして、特定の国の値のみを返すことができます。（レポート対象期間の各日にカナダで動画が視聴された回数）
チャンネル所有者は、リクエストをフィルタして、特定の動画の値のみを返すことができます。ただし、動画フィルタはカンマ区切りの値のリストをサポートしているため、レポートには実際には多くの動画のデータが含まれる可能性があります。
また、video フィルタで複数の値を指定する場合は、video をディメンションとして指定することもできます。つまり、
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 日あたりの合計視聴回数が動画ごとに表示されます。
この場合、最初のレポートには日単位の集計が含まれているため、最初のレポートの数値には、後で削除された動画の視聴回数が含まれます。ただし、2 つ目のレポートには、削除されたアイテムに関連付けられた視聴回数は含まれません。2 つ目のレポートには、動画ごとの視聴回数が一覧表示されるためです。そのため、レポートの対象期間中にチャンネルで動画が削除された場合、最初のレポートに表示される 1 日の合計視聴回数は、2 番目のレポートに表示される 1 日の動画別の視聴回数の合計よりも多くなる可能性があります。
データの匿名化
指標が一定のしきい値に達していない場合、YouTube アナリティクスの一部のデータは限定的にしか利用できません。これは、さまざまなレポートで発生する可能性があります。実際には、次の場合に、レポートにデータの一部（またはすべて）が含まれない可能性があります。
指定した期間の動画またはチャンネルのトラフィックが少ない場合、
または
値が一定のしきい値を満たしていない、トラフィック ソースや国などのフィルタやディメンションを選択した場合。
データが限定的である場合、レポートでのデータ集計方法によっては、各レポートで報告される合計値に差異が生じることがあります。
たとえば、チャンネル所有者が 2 つのレポートを取得するとします。最初のレポートには特定の動画の総視聴回数が表示され、2 番目のレポートにはその動画の総視聴回数が国別に表示されます。指定された期間中に動画が 1,000 回視聴されており、そのうち 500 回は米国、498 回はカナダ、2 回はフランスで視聴されたとします。
この例では、最初のレポートには動画の視聴回数が 1, 000 回と表示されます。2 つ目のレポートでは、米国で 500 回、カナダで 498 回視聴されたことのみが示されます。そのため、2 つのレポートの合計視聴回数に差異が生じます。2 つ目のレポートには、この動画がもう 2 回視聴されたこと（またはフランスで視聴されたこと）を示す情報は含まれません。
一部のデータ型
YouTube アナリティクスのレポートでは、次のデータが限定的にしか利用できない場合があります。
- 年齢や性別などのユーザー属性データ。
- 地理データ。視聴者が所在する国や地域に関連する指標やディメンション（国や地域など）が含まれます。ただし、レポートでは収益指標に地域のしきい値は適用されません。
- 特定のトラフィック ソースに関連する指標（動画の視聴につながった検索キーワードや外部 URL など）。たとえば、視聴回数が非常に少ない検索語句や URL はレポートに表示されませんが、コンテンツに多くの視聴者を誘導している検索語句や URL は引き続き表示されます。
YouTube アナリティクス レポートの限定的データについて詳しくは、YouTube ヘルプセンターをご覧ください。
割り当て使用量
API リクエストは、1 回ごとに API 使用量割り当ての 1 ユニットとしてカウントされます。割り当て上限は、Google Cloud コンソールの [割り当て] パネルで確認できます。