Reports: Query

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

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

  • 指標は、動画の視聴回数や評価(高評価と低評価)など、ユーザー アクティビティの個々の測定値です。
  • ディメンションは、ユーザー アクティビティが発生した日付やユーザーが居住している国など、データの集計に使用される一般的な条件です。レポートでは、データ行ごとにディメンション値の一意の組み合わせがあります。
  • フィルタは、取得するデータを指定するディメンション値です。たとえば、特定の国、特定の動画、または動画のグループのデータを取得できます。

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

一般的なユースケース

リクエスト

HTTP リクエスト

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

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

YouTube アナリティクス 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 Analytics API では、コンテンツ所有者はこのスコープを使用して YouTube アナリティクス グループとグループ アイテムを管理します。

パラメータ

次の表に、クエリ レポートを取得するための API リクエストの必須クエリ パラメータと省略可能なクエリ パラメータを示します。表に記載されている標準のクエリ パラメータもオプションであり、多くの Google API でサポートされています。

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

API レスポンスには、クエリの時点でクエリ内のすべての指標が利用可能な最終日までのデータが含まれます。たとえば、リクエストで 2017 年 7 月 5 日の終了日が指定され、リクエストされたすべての指標の値が 2017 年 7 月 3 日までしか利用できない場合、レスポンスに含まれるデータの最終日は 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 が次の推定収益指標(estimatedRevenueestimatedAdRevenueestimatedRedPartnerRevenuegrossRevenuecpmplaybackBasedCpm)を指定するために使用する通貨。API がこれらの指標に対して返す値は、毎日変動する為替レートを使用して計算された推定値です。これらの指標がリクエストされていない場合、パラメータは無視されます。

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

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

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

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

API は、videoplaylistchannel フィルタに複数の値を指定する機能をサポートしています。これを行うには、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 リクエストで指定された日付に一致するデータが含まれます。
注: 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 このパラメータは API のバージョン 2 ではサポートされていません。バージョン 2 では JSON レスポンスのみがサポートされています。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 年の毎日の視聴回数などの指標を取得します。このサンプルでは、Google API JavaScript クライアント ライブラリを使用します。

このサンプルをローカルで初めて実行する前に、プロジェクトの認可認証情報を設定する必要があります。
  1. Google API Console でプロジェクトを作成または選択します。
  2. プロジェクトで YouTube アナリティクス 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. [実行] ボタンをクリックして 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 年の毎日の視聴回数などの指標を取得します。このサンプルでは、Google APIs Python クライアント ライブラリを使用します。

このサンプルをローカルで初めて実行する前に、プロジェクトの認可認証情報を設定する必要があります。
  1. Google API Console でプロジェクトを作成または選択します。
  2. プロジェクトで YouTube アナリティクス API を有効にします。
  3. [認証情報] ページの上部で [OAuth 同意画面] タブを選択します。メールアドレスを選択し、サービス名が設定されていない場合はサービス名を入力して、[保存] ボタンをクリックします。
  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'
  )

試してみよう:

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