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 アナリティクス API では、チャンネル所有者はこのスコープを使用して、YouTube アナリティクスのグループとグループ アイテムを管理します。
https://www.googleapis.com/auth/youtubepartner 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 日のデータであっても当てはまります)。
注: API のバージョン 1 では、このパラメータの名前は 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 指標のカンマ区切りのリスト(viewslikes,dislikes など)。取得できるレポートや各レポートで使用できる指標の一覧については、チャンネル レポートまたはコンテンツ所有者レポートに関するドキュメントをご覧ください。(指標ドキュメントにすべての指標の定義が記載されています)。
startDate string
YouTube Analytics データの取得の開始日。値は YYYY-MM-DD の形式にします。
注: API のバージョン 1 では、このパラメータの名前は start-date でした。
省略可能なパラメータ
currency string
API が推定収益指標(estimatedRevenueestimatedAdRevenueestimatedRedPartnerRevenueaggregateRevenuecpmplaybackBasedCpm)を指定する際に使用する通貨。これらの指標に対して API が返す値は、為替レートの変動に基づいて毎日算出されます。これらの指標のいずれもリクエストされない場合、このパラメータは無視されます。

パラメータ値は、以下の通貨リストに記載されている ISO 4217 の 3 文字の通貨コードです。サポートされていない通貨を指定すると、API からエラーが返されます。デフォルト値は USD です。

dimensions string
YouTube アナリティクスのディメンションのカンマ区切りリスト(例: videoageGroup,gender)。取得可能なレポートとそれぞれのレポートに使用されるディメンションのリストについては、チャンネル レポートまたはコンテンツ所有者レポートに関するドキュメントをご覧ください。(ディメンションに関するドキュメントには、すべてのディメンションの定義が記載されています)。
filters string
YouTube Analytics データの取得時に適用するフィルタのリスト。チャネル レポートコンテンツ所有者レポートのドキュメントでは、各レポートのフィルタリングに使用できるディメンションをご確認いただけます。また、ディメンションのドキュメントでは、そのディメンションを定義しています。

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

フィルタに複数の値を指定する

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

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

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

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

異なる日付に、複数のコンテンツ所有者がコンテンツ所有者にリンクしている可能性があることを忘れないでください。API リクエストが複数のチャネルのデータを取得し、パラメータ値が false の場合、API レスポンスには各チャネルのリンク日に基づくデータが含まれます。パラメータ値が true の場合、API レスポンスには、API リクエストで指定された日付に一致するデータが含まれます。
注: API のバージョン 1 では、このパラメータの名前は include-historical-channel-data でした。
maxResults integer
レスポンスに含める行の最大数。
注: API のバージョン 1 では、このパラメータの名前は max-results でした。
sort string
YouTube アナリティクス データの並べ替え順序を決定するディメンションまたは指標のカンマ区切りリスト。デフォルトは昇順です。- 接頭辞を使用すると、降順に並べ替えられます。
startIndex integer
取得する最初のエンティティの 1 ベースのインデックス。(デフォルト値は 1 です)。このパラメータは、max-results パラメータとともにページ設定メカニズムとして使用します。
注: API のバージョン 1 では、このパラメータの名前は start-index でした。
標準パラメータ
access_token 現在のユーザーの OAuth 2.0 トークン。
alt このパラメータは、JSON レスポンスのみをサポートする API バージョン 2 ではサポートされていません。API レスポンスのデータ形式。
  • 有効な値: jsoncsv
  • デフォルト値: 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 レスポンスは ageGroupgenderviewerPercentage の順序で列を返します。
columnHeaders[].name string
ディメンションまたは指標の名前。
columnHeaders[].columnType string
列の型(DIMENSION または METRIC)。
columnHeaders[].dataType string
列のデータ型(STRINGINTEGERFLOAT など)。
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 同意画面] タブを選択します。メールアドレスを選択し、まだ設定していない場合はプロダクト名を入力して、[保存] ボタンをクリックします。
  4. [認証情報] ページで [認証情報を作成] ボタンをクリックし、[OAuth クライアント ID] を選択します。
  5. アプリケーションの種類として [ウェブ アプリケーション] を選択します。
  6. [承認済みの JavaScript 生成元] に、コードサンプルを送信する URL を入力します。たとえば、http://localhost:8000http://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>

Python

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

このサンプルを初めてローカルで実行する前に、プロジェクトの認証情報を設定する必要があります。
  1. Google API Console でプロジェクトを作成または選択します。
  2. プロジェクトで YouTube Analytics API を有効にします。
  3. [認証情報] ページの上部で、[OAuth 同意画面] タブを選択します。メールアドレスを選択し、まだ設定していない場合はプロダクト名を入力して、[保存] ボタンをクリックします。
  4. [認証情報] ページで [認証情報を作成] ボタンをクリックし、[OAuth クライアント ID] を選択します。
  5. アプリケーションの種類として [その他] を選択し、「YouTube Analytics API クイックスタート」という名前を入力して、[作成] ボタンをクリックします。
  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'
  )

実習

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