重要: このメソッドへの 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 チャンネルまたはコンテンツ所有者を示します。
|
|
metrics |
string YouTube Analytics 指標のカンマ区切りのリスト( views 、likes,dislikes など)。取得できるレポートや各レポートで使用できる指標の一覧については、チャンネル レポートまたはコンテンツ所有者レポートに関するドキュメントをご覧ください。(指標ドキュメントにすべての指標の定義が記載されています)。 |
|
startDate |
string YouTube Analytics データの取得の開始日。値は YYYY-MM-DD の形式にします。注: API のバージョン 1 では、このパラメータの名前は
start-date |
|
省略可能なパラメータ | ||
currency |
string API が推定収益指標(estimatedRevenue、estimatedAdRevenue、estimatedRedPartnerRevenue、aggregateRevenue、cpm、playbackBasedCpm)を指定する際に使用する通貨。これらの指標に対して API が返す値は、為替レートの変動に基づいて毎日算出されます。これらの指標のいずれもリクエストされない場合、このパラメータは無視されます。 パラメータ値は、以下の通貨リストに記載されている ISO 4217 の 3 文字の通貨コードです。サポートされていない通貨を指定すると、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 本の動画のリストが指定されたとします。
|
|
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 レスポンスのデータ形式。
|
|
callback |
コールバック関数。
|
|
prettyPrint |
インデントと改行の付いたレスポンスを返す。
|
|
quotaUser |
このパラメータは API のバージョン 1 でサポートされていましたが、サポートが終了しました。このパラメータは、API のバージョン 2 ではサポートされていません。 | |
userIp |
このパラメータは API のバージョン 1 でサポートされていましたが、サポートが終了しました。このパラメータは、API のバージョン 2 ではサポートされていません。 |
リクエスト本文
このメソッドを呼び出すときはリクエスト本文を送信しないでください。
レスポンス
alt
パラメータの定義で説明したように、API は JSON 形式または CSV 形式のレスポンスを返すことができます。レスポンスの本文については、以下で形式別に説明します。
{ "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 ディメンションを含むクエリのレスポンスには、直近の行は含まれません。 |
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 クライアント ライブラリを使用します。このサンプルを初めてローカルで実行する前に、プロジェクトの認証情報を設定する必要があります。
- Google API Console でプロジェクトを作成または選択します。
- プロジェクトで YouTube Analytics API を有効にします。
- [認証情報] ページの上部で、[OAuth 同意画面] タブを選択します。メールアドレスを選択し、まだ設定していない場合はプロダクト名を入力して、[保存] ボタンをクリックします。
- [認証情報] ページで [認証情報を作成] ボタンをクリックし、[OAuth クライアント ID] を選択します。
- アプリケーションの種類として [ウェブ アプリケーション] を選択します。
- [承認済みの JavaScript 生成元] に、コードサンプルを送信する URL を入力します。たとえば、
http://localhost:8000
やhttp://yourserver.example.com
などを使用します。[承認済みのリダイレクト URI] フィールドは空白のままでもかまいません。 - [作成] ボタンをクリックして、認証情報の作成を完了します。
- ダイアログ ボックスを閉じる前に、クライアント ID をコピーします。この ID はコードサンプルに含まれています。
次に、サンプルをローカル ファイルに保存します。サンプルで次の行を探し、YOUR_CLIENT_ID を、認証情報の設定時に取得したクライアント ID に置き換えます。
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
これで、サンプルを実際にテストする準備ができました。
- ウェブブラウザでローカル ファイルを開き、ブラウザでデバッグ コンソールを開きます。2 つのボタンを含むページが表示されます。
- [Authorize and load] ボタンをクリックして、ユーザー認証フローを起動します。アプリがチャンネル データを取得することを承認すると、ブラウザのコンソールに次の行が表示されます。
Sign-in successful GAPI client loaded for API
- 上記の行の代わりにエラー メッセージが表示された場合は、プロジェクト用に設定した承認済みのリダイレクト URI からスクリプトを読み込んであり、前述のとおりクライアント ID をコードに挿入していることをご確認ください。
- [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 クライアント ライブラリを使用します。このサンプルを初めてローカルで実行する前に、プロジェクトの認証情報を設定する必要があります。
- Google API Console でプロジェクトを作成または選択します。
- プロジェクトで YouTube Analytics API を有効にします。
- [認証情報] ページの上部で、[OAuth 同意画面] タブを選択します。メールアドレスを選択し、まだ設定していない場合はプロダクト名を入力して、[保存] ボタンをクリックします。
- [認証情報] ページで [認証情報を作成] ボタンをクリックし、[OAuth クライアント ID] を選択します。
- アプリケーションの種類として [その他] を選択し、「YouTube Analytics API クイックスタート」という名前を入力して、[作成] ボタンをクリックします。
- [OK] をクリックして、表示されたダイアログを閉じます。
- クライアント ID の右側にある [ (JSON をダウンロード)] ボタンをクリックします。
- ダウンロードしたファイルを作業ディレクトリに移動します。
また、Python 用 Google API クライアント ライブラリと追加のライブラリをインストールする必要があります。
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
これで、サンプルを実際にテストする準備ができました。
- 以下のコードサンプルを作業ディレクトリにコピーします。
- このサンプルでは、認証情報の設定後にダウンロードしたファイルの場所と一致するように
CLIENT_SECRETS_FILE
変数の値を更新します。 - ターミナル ウィンドウでサンプルコードを実行します。
python yt_analytics_v2.py
- 承認フローを行います。認証フローは自動的にブラウザに読み込まれるか、認証 URL をブラウザ ウィンドウにコピーする必要がある場合があります。認証フローの最後で、必要に応じてブラウザに表示された認証コードをターミナル ウィンドウに貼り付け、[Return] をクリックします。
- 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 のリクエストとレスポンスを確認します。