Reports: Query

重要: このメソッドに対する API リクエストには、https://www.googleapis.com/auth/youtube.readonly スコープへのアクセスが必要になりました。

この方法では、さまざまなアナリティクス レポートを取得できます。各リクエストでクエリ パラメータを使用して、チャンネル ID またはコンテンツ所有者、開始日、終了日、1 つ以上の指標を指定します。ディメンション、フィルタ、並べ替えの手順など、追加のクエリ パラメータを指定することもできます。

  • 指標とは、動画の視聴回数や評価（高評価と低評価）など、ユーザー アクションの個々の測定値のことです。
  • ディメンションとは、ユーザー アクションが発生した日付やユーザーが所在する国など、データの集計に使用される共通の条件です。レポートでは、データの各行にはディメンション値の組み合わせが一意ではありません。
  • フィルタは、取得するデータを指定するディメンション値です。 たとえば、特定の国、特定の動画、または動画のグループに関するデータを取得できます。

注: コンテンツ所有者レポートにアクセスできるのは、YouTube パートナー プログラムに参加している YouTube コンテンツ パートナーのみです。

一般的なユースケース

リクエスト

HTTP リクエスト

GET https://youtubeanalytics.googleapis.com/v2/reports

すべての YouTube Analytics API リクエストには承認が必要です。認可ガイドでは、OAuth 2.0 プロトコルを使用して認可トークンを取得する方法を説明しています。

YouTube Analytics API リクエストでは、次の承認スコープを使用します。

スコープ
https://www.googleapis.com/auth/yt-analytics.readonly YouTube コンテンツの YouTube アナリティクス レポートを表示します。このスコープは再生回数や評価数など、ユーザー アクティビティの指標へのアクセスを提供します。
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTube コンテンツに関する YouTube アナリティクス収益レポートを表示します。このスコープでは、ユーザー アクティビティの指標、推定収益、広告パフォーマンスの指標にアクセスできます。
https://www.googleapis.com/auth/youtube YouTube アカウントを管理する。YouTube Analytics API では、チャンネル所有者はこのスコープを使用して YouTube アナリティクス グループとグループ アイテムを管理します。
https://www.googleapis.com/auth/youtubepartner YouTube アセットと YouTube の関連コンテンツの表示と管理。YouTube Analytics API では、コンテンツ所有者はこのスコープを使用して YouTube アナリティクスのグループとグループ アイテムを管理します。

パラメータ

次の表に、クエリレポートを取得する API リクエストに必要なクエリ パラメータと省略可能なクエリ パラメータを示します。表にリストされている標準のクエリ パラメータも省略可能で、多くの Google API でサポートされています。

パラメータ
必須パラメータ
endDate string
YouTube Analytics データの取得終了日。値は YYYY-MM-DD 形式にする必要があります。

API レスポンスには、クエリの時点でクエリ内のすべての指標が使用可能である最終日までのデータが含まれます。たとえば、リクエストで 2017 年 7 月 5 日の終了日が指定されていて、リクエストされたすべての指標の値が 2017 年 7 月 3 日までしか利用できない場合、その日がレスポンスにデータが含まれる最終日になります。（リクエストされた指標の一部のデータが 2017 年 7 月 4 日時点のデータを利用できる場合でも同じです）。
注: バージョン 1 の API では、このパラメータは end-date という名前でした。
ids string
YouTube Analytics データを取得する YouTube チャンネルまたはコンテンツ所有者を識別します。

  • YouTube チャンネルのデータをリクエストするには、ids パラメータ値を channel==MINE または channel==CHANNEL_ID に設定します。CHANNEL_ID は現在認証されているユーザーの YouTube チャンネルを表します。
  • YouTube コンテンツ所有者のデータをリクエストするには、ids パラメータの値を contentOwner==OWNER_NAME に設定します。OWNER_NAME はユーザーの content owner ID です。

metrics string
YouTube Analytics 指標（views、likes,dislikes など）のカンマ区切りリスト。取得できるレポートと各レポートで使用できる指標のリストについては、チャンネル レポートまたはコンテンツ所有者レポートのドキュメントをご覧ください。（すべての指標の定義は、指標ドキュメントに記載されています）。
startDate string
YouTube Analytics データの取得開始日。値は YYYY-MM-DD 形式にする必要があります。
注: バージョン 1 の API では、このパラメータは start-date という名前でした。
オプション パラメータ
currency string
推定収益の指標を指定するために API で使用される通貨: estimatedRevenue、estimatedAdRevenue、estimatedRedPartnerRevenue、grossRevenue、cpm、playbackBasedCpm。これらの指標に対して API から返される値は、毎日変化する為替レートを使用して計算された推定値です。これらの指標がいずれもリクエストされていない場合、パラメータは無視されます。

パラメータ値は、以下の通貨リストから 3 文字の ISO 4217 通貨コードです。サポートされていない通貨を指定すると、API からエラーが返されます。デフォルト値は USD です。
dimensions string
YouTube アナリティクス ディメンションのカンマ区切りリスト（例: video、ageGroup,gender）。取得できるレポートとレポートで使用できるディメンションのリストについては、チャンネル レポートまたはコンテンツ所有者レポートのドキュメントをご覧ください。（すべてのディメンションの定義は、ディメンションのドキュメントに記載されています）。
filters string
YouTube Analytics データの取得時に適用するフィルタのリスト。各レポートのフィルタリングに使用できるディメンションについては、チャンネル レポートとコンテンツ所有者レポートのドキュメントをご覧ください。これらのディメンションについては、ディメンションのドキュメントで定義します。

リクエストで複数のフィルタを使用する場合は、フィルタをセミコロン（;）で結合すると、返される結果のテーブルが両方のフィルタを満たします。たとえば、filters パラメータ値が video==dMH0bHeiRNg;country==IT の場合、結果セットにはイタリアの特定の動画のデータが含まれるよう制限されます。

フィルタの複数の値の指定

API では、video、playlist、channel のフィルタに複数の値を指定できます。そのためには、API レスポンスをフィルタする動画、再生リスト、またはチャンネル ID を分けたリストを指定します。たとえば、filters パラメータ値が video==pd1FJh59zxQ,Zhawgd0REhA;country==IT の場合、結果セットにはイタリアの特定の動画のデータが含まれるよう制限されます。このパラメータ値には、最大 500 個の ID を指定できます。

同じフィルタに複数の値を指定する場合は、リクエストで指定したディメンションのリストにそのフィルタを追加することもできます。これは、特定のレポートでサポートされているディメンションとしてフィルタが表示されていない場合でも同じです。ディメンションのリストにフィルタを追加すると、API はフィルタ値を使用して結果をグループ化します。

たとえば、チャンネルのトラフィック ソース レポートを取得するとします。このレポートでは、視聴者がチャンネルの動画コンテンツにアクセスした方法に基づいて視聴の統計情報が集計されます。また、リクエストの filters パラメータ リクエストで、データを返す必要がある 10 本の動画のリストを指定したとします。
  • dimensions パラメータの値に video を追加すると、API レスポンスは 10 本の動画のそれぞれに対する個別のトラフィック ソース統計情報を提供します。
  • dimensions パラメータの値に video を追加しない場合、API レスポンスは 10 本の動画すべてのトラフィック ソースの統計情報を集計します。
includeHistoricalChannelData boolean
注: このパラメータはコンテンツ所有者レポートにのみ適用されます。

API レスポンスに、チャンネルがコンテンツ所有者にリンクされる前の期間の総再生時間と視聴データを含めるかどうかを指定します。デフォルトのパラメータ値は false です。つまり、API レスポンスには、チャンネルがコンテンツ所有者にリンクされている日付の総再生時間と視聴回数のデータのみが含まれます。

コンテンツ所有者とリンクされるチャンネルは異なる場合があることにご注意ください。API リクエストが複数のチャネルのデータを取得していて、パラメータ値が false の場合、API レスポンスには各チャネルのリンク日に基づくデータが含まれます。パラメータ値が true の場合、API レスポンスには API リクエストで指定された日付に一致するデータが含まれます。
注: バージョン 1 の API では、このパラメータは include-historical-channel-data という名前でした。
maxResults integer
レスポンスに含める最大行数。
注: バージョン 1 の API では、このパラメータは max-results という名前でした。
sort string
YouTube アナリティクス データの並べ替え順序を決定するディメンションまたは指標のカンマ区切りのリスト。デフォルトは昇順です。- 接頭辞を指定すると降順になります。
startIndex integer
最初に取得するエンティティの 1 から始まるインデックス。（デフォルト値は 1 です）。このパラメータは、max-results パラメータとともにページネーション メカニズムとして使用します。
注: バージョン 1 の API では、このパラメータは start-index という名前でした。
標準パラメータ
access_token 現在のユーザーの OAuth 2.0 トークン。
alt このパラメータは、JSON レスポンスのみをサポートするバージョン 2 の API ではサポートされていません。API レスポンスのデータ形式です。
  • 有効な値: json、csv
  • デフォルト値: json
callback コールバック関数。
  • レスポンスを処理する JavaScript コールバック関数の名前。
  • JavaScript JSON-P リクエストで使用されます。
prettyPrint

インデントと改行の付いたレスポンスを返す。

  • true の場合は、人が読める形式でレスポンスを返します。
  • デフォルト値: true。
  • false の場合、一部の環境ではレスポンスのペイロード サイズを小さくできるため、パフォーマンスが向上する可能性があります。
quotaUser このパラメータは、現在非推奨となっている API バージョン 1 でサポートされていました。このパラメータは、API バージョン 2 ではサポートされていません。
userIp このパラメータは、現在非推奨となっている API バージョン 1 でサポートされていました。このパラメータは、API バージョン 2 ではサポートされていません。

リクエスト本文

このメソッドを呼び出すときは、リクエストの本文を送信しないでください。

レスポンス

alt パラメータ定義にあるように、API は JSON 形式または CSV 形式でレスポンスを返すことができます。レスポンスの本文については、以下で形式別に説明します。

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
プロパティ
kind string
この値は、API レスポンスに含めるデータタイプを指定します。query メソッドの場合、kind プロパティ値は youtubeAnalytics#resultTable になります。ただし、API で他のメソッドのサポートが追加された場合、それらのメソッドに対する API レスポンスで他の kind プロパティ値が使用されることがあります。
columnHeaders[] list
この値は、rows フィールドで返されるデータに関する情報を指定します。columnHeaders リストの各項目は rows 値で返されるフィールドを識別します。これにはカンマ区切りデータのリストが含まれます。

columnHeaders リストは API リクエストで指定されたディメンションで始まり、その後に API リクエストで指定された指標が続きます。ディメンションと指標の順序は、API リクエストの順序と一致しています。

たとえば、API リクエストにパラメータ dimensions=ageGroup,gender&metrics=viewerPercentage が含まれている場合、API レスポンスは ageGroup、gender、viewerPercentage の順序で列を返します。
columnHeaders[].name string
ディメンションまたは指標の名前。
columnHeaders[].columnType string
列の型（DIMENSION または METRIC）。
columnHeaders[].dataType string
列のデータの型（STRING、INTEGER、FLOAT など）。
rows[] list
このリストには、結果テーブルのすべての行が含まれます。リストの各アイテムは、1 行のデータに対応するカンマ区切りデータを格納する配列になります。カンマ区切りのデータ フィールドの順序は、columnHeaders フィールドに指定されている列の順序と同じです。

指定されたクエリで使用できるデータがない場合、rows 要素はレスポンスから除外されます。

day ディメンションのクエリのレスポンスには、直近の数日分の行は含まれません。

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

例

注: 次のコードサンプルは、サポートされているプログラミング言語の一部を示しているわけではありません。サポートされている言語の一覧については、クライアント ライブラリのドキュメントをご覧ください。

JavaScript

この例では、YouTube Analytics API を呼び出して、承認されたユーザーの 2017 年のチャンネルの 1 日の視聴回数とその他の指標を取得します。このサンプルでは、Google API JavaScript クライアント ライブラリを使用しています。

このサンプルをローカルで初めて実行する前に、プロジェクトの認証情報を設定する必要があります。
  1. Google API Console でプロジェクトを作成または選択します。
  2. プロジェクトで YouTube Analytics API を有効にします。
  3. [認証情報] ページの上部にある [OAuth 同意画面] タブを選択します。メールアドレスを選択し、プロダクト名が設定されていない場合は入力して [Save] ボタンをクリックします。
  4. [認証情報] ページで [認証情報を作成] ボタンをクリックし、[OAuth クライアント ID] を選択します。
  5. アプリケーションの種類として [ウェブ アプリケーション] を選択します。
  6. [承認済みの JavaScript 生成元] に、コードサンプルを提供する URL を入力します。たとえば、http://localhost:8000 や http://yourserver.example.com などを使用できます。[承認済みのリダイレクト URI] は空欄のままでかまいません。
  7. [作成] ボタンをクリックして、認証情報の作成を完了します。
  8. ダイアログ ボックスを閉じる前に、クライアント ID をコピーします。このクライアント ID をコードサンプルに入力します。

サンプルをローカル ファイルに保存します。サンプルでは、次の行を探して、YOUR_CLIENT_ID を認証情報の設定時に取得したクライアント ID に置き換えます。

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

これで、実際にサンプルをテストする準備が整いました。

  1. ウェブブラウザでローカル ファイルを開き、ブラウザでデバッグ コンソールを開きます。2 つのボタンが表示されたページが表示されます。
  2. [Authorize and load] ボタンをクリックして、ユーザー承認フローを開始します。アプリにチャンネル データの取得を許可すると、ブラウザのコンソールに次の行が表示されます。 
    Sign-in successful
GAPI client loaded for API
  3. 上記の行の代わりにエラー メッセージが表示される場合は、プロジェクト用に設定した承認済みのリダイレクト URI からスクリプトを読み込んでいることと、上記のようにクライアント ID をコードに挿入していることを確認します。
  4. [execute] ボタンをクリックして API を呼び出します。ブラウザのコンソールに response オブジェクトが表示されます。そのオブジェクトでは、result プロパティは API データを含むオブジェクトにマッピングされます。
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

この例では、YouTube Analytics API を呼び出して、承認されたユーザーの 2017 年のチャンネルの 1 日の視聴回数とその他の指標を取得します。このサンプルでは、Google API Python クライアント ライブラリを使用しています。

このサンプルをローカルで初めて実行する前に、プロジェクトの認証情報を設定する必要があります。
  1. Google API Console でプロジェクトを作成または選択します。
  2. プロジェクトで YouTube Analytics API を有効にします。
  3. [認証情報] ページの上部にある [OAuth 同意画面] タブを選択します。メールアドレスを選択し、プロダクト名が設定されていない場合は入力して [Save] ボタンをクリックします。
  4. [認証情報] ページで [認証情報を作成] ボタンをクリックし、[OAuth クライアント ID] を選択します。
  5. アプリケーションの種類として [その他] を選択し、「YouTube Analytics API Quickstart」という名前を入力して、[作成] ボタンをクリックします。
  6. [OK] をクリックしてダイアログを閉じます。
  7. クライアント ID の右側にある （JSON をダウンロード）ボタンをクリックします。
  8. ダウンロードしたファイルを作業ディレクトリに移動します。

Python 用の Google API クライアント ライブラリと追加ライブラリもインストールする必要があります。

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

これで、実際にサンプルをテストする準備が整いました。

  1. 以下のコードサンプルを作業ディレクトリにコピーします。
  2. サンプルでは、認証情報の設定後にダウンロードしたファイルの場所と一致するように CLIENT_SECRETS_FILE 変数の値を更新します。
  3. ターミナル ウィンドウでサンプルコードを実行します。 
    python yt_analytics_v2.py
  4. 承認フローを進めます。認証フローがブラウザで自動的に読み込まれる場合と、認証 URL をブラウザ ウィンドウにコピーしなければならない場合があります。承認フローの最後で、必要に応じて、ブラウザに表示された認証コードをターミナル ウィンドウに貼り付けて [return] をクリックします。
  5. API クエリが実行され、JSON レスポンスがターミナル ウィンドウに出力されます。
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

試してみよう:

APIs Explorer を使用してこの API を呼び出し、API のリクエストとレスポンスを確認します。