YouTube Reporting APIを使ってデータをCSVでダウンロードする

February 16, 2018

youtube-reporting-api レポート csv

YouTube APIを使用して取得するデータは、YouTube APIの利用規約に従った形でのみ使用しましょう

はじめに

YouTubeは、自分がアップロードした動画に対して色々なデータを提供しています。例えば、view (視聴回数) や watch time (視聴時間)、カードのクリック率などです。それらのデータは、Creator StudioにあるYouTube Analyticsで見ることができます。

YouTube Analyticsは、ぱっとデータを確認したりするのにはとても便利ですが、それらのデータをExcelやソフトウェアで処理したい場合には、それらのデータをダウンロードする必要があります。

YouTubeは、それらのデータをダウンロードするために二つのAPIを提供しています。YouTube Analytics APIYouTube Reporting APIです。

YouTube Analytics APIは、基本的には一つの動画に対して、幾つかのデータを特定の日付を指定して取得するものです。例えば、動画 (video ID: "video_id_test") に対して、2018年1月1日から2018年1月31日までの間のviews (視聴回数) とestimatedMinutesWatched (推定の視聴時間を分で)、という感じで使用します。これはつまり、データを取得したい動画の数やデータの種類が多い場合、このAPIを多くの回数呼ぶことになります。

YouTube Reporting APIは、YouTube Analytics APIの後に提供され始めたAPIで、YouTube Analytics APIの幾つかの問題を解決しています。顕著なのが、データを取得するためにAPIを多くの回数呼ぶ必要がなくなったというところです。

YouTube Reporting APIは、あらかじめ定義されたレポートを提供する代わりに、自分のチャンネルにアップロードされている全ての動画を対象としています。 例えば、User activityというレポートには、一般的に良く使われるviews (視聴回数)、watch_time_minues (視聴時間を分で)、likes / dislikes、average_view_duration_seconds (平均視聴時間を秒で)、subscriber_gain (増えた登録者数) / subscriber_lost (減った登録者数)、などのデータが含まれています。YouTube Reporting APIを使ってレポートをダウンロードすると、一回APIを呼ぶだけで全ての動画に対してそれらのデータを取得することができます。

具体的には、YouTubeに対してダウンロードしたいレポートの作成を依頼しておくと、YouTubeが毎日レポートを作成するので、それをダウンロードすることになります。

YouTube Reporting APIを使ってみる

早速YouTube Reporting APIを使いましょう。この記事では、YouTube Reporting APIをGoogle APIs Explorer 1 から使用します。

ダウンロードしたいレポートを決める

まず、ダウンロードしたいレポートを決めます。YouTube Reporting APIが提供しているレポートの一覧は、ここに掲載されています。各々のレポートの項目に、そのレポートが含むdimensionsとmetricsが記載されています。それらを元に、自分が欲しいレポートを決めましょう。ここでは、User activityを例として使用します。

自分が欲しいレポートが決まったら、以下の手順に従ってそのレポートのIDを取得します。

1. YouTube Reporting APIのreportTypes.listのページに行く

2. 自分のYouTubeのチャンネルに結びついているGoogle Accountを使って認証する

以下の画像にあるようなボタンをクリックすることで、Google Accountを使って認証できます。

OAuth

Google Accountを選択した後、YouTubeのチャンネルを選択します。対象としたいYouTubeのチャンネルを選択します。

3. reportTypes.listを実行する

ページの下にある、Executeボタンを押し、reportTypes.listを実行します。その結果、以下のようなレスポンスが返ってきます。

{
  "reportTypes": [
    {
      "id": "channel_annotations_a1",
      "name": "Annotations"
    },
    {
      "id": "channel_basic_a2",
      "name": "User activity"
    },
    {
      "id": "channel_cards_a1",
      "name": "Cards"
    }
  ]
}

一部のみを抜粋していますが、探していたレポートを探してみてください。User activityに関しては、以下がレスポンスに含まれています。

{
  "id": "channel_basic_a2",
  "name": "User activity"
}

ここにある、idに対する値 (channel_basic_a2) が、必要となるレポートのIDとなります。

レポートの作成を設定する

ダウンロードしたいレポートが決まったら、そのレポートが作成されるようにYouTubeに依頼します。YouTube Reporting APIには、jobという概念があり、このジョブが指定したレポートを毎日作成します。

以下の手順に従って、特定のレポートを作成するジョブを作成します。

1. YouTube Reporting APIのjobs.createのページに行く

2. 自分のYouTubeのチャンネルに結びついているGoogle Accountを使って認証する

3. jobs.createを実行する

jobs.createを実行するには、reportTypeIdnameパラメーターを指定する必要があります (APIにおける必須のパラメーターなどの情報は、API Referenceを参照ください)。

reportTypeIdは先ほど取得したレポートのID、nameはレポートの名前です。nameには、自分が好きな値が使えます。例えば、User Basic Reportなどです。後で自分が、そのレポートがどういうレポートなのか分かりやすいような名前にするのが良いでしょう。

ここでは、reportTypeIdchannel_basic_a2を、nameMy User Basic Reportを指定します。

Request bodyの部分は、以下のようになります。

Request body

ページの下の方にあるExecuteボタンを押し、jobs.createを実行します。成功した場合は、以下のようなレスポンスが返ってきます。

{
  "id": "abc123",
  "reportTypeId": "channel_basic_a2",
  "name": "My User Basic Report",
  "createTime": "2018-02-15T02:13:04.014Z"
}

このレスポンスのidが、作成されたジョブのIDになります。このIDは後ほど使用します。ここでは、ジョブのIDがabc123だと仮定します。

作成されたレポートを確認する

ジョブが作成されたので、このジョブはレポートを作成し始めます。ジョブが作成したレポートのリストを取得し、レポートが作成されているのを確認します。

以下の手順に従って、作成されたレポートを確認します。

1. YouTube Reporting APIのreports.listのページに行く

2. 自分のYouTubeのチャンネルに結びついているGoogle Accountを使って認証する

3. reports.listを実行する

jobIdに先ほどのジョブのIDを指定し、Excuteボタンをクリックして実行します。以下のようなレスポンスが返ってきます。

{
  "reports": [
    {
      "id": "some_report_id",
      "jobId": "1c84baf2-c475-4a46-94e3-b9878e55f3dd",
      "startTime": "2018-01-01T08:00:00Z",
      "endTime": "2018-01-02T08:00:00Z",
      "createTime": "2018-02-16T15:14:10.634238Z",
      "downloadUrl": "https://youtubereporting.googleapis.com/v1/media/CHANNEL/some_channel_id/jobs/some_job_id/reports/some_report_id?alt=media"
    }
  ]
}

もし何も返ってこなければ、まだレポートが作成されていない可能性があります。ジョブはレポートを毎日作成するので、最初のレポートが作成されるまでに最低一日ほど待つ必要があります。

idの値や、downloadUrlの一部の値は特定のレポートを示す値ですので少し変えていますが、downloadUrlの値は大体こんな感じのURLです。downloadUrlは次の手順で使用します。

レポートをダウンロードする

最後に、先ほどのdownloadUrlを使用してレポートをダウンロードします。レポートのダウンロードには、Google APIのaccess tokenが必要です。こちらの記事を参考に、有効なaccess tokenを取得してください。

access tokenを取得する際は、レポートを取得しようとしている対象のYouTubeのチャンネルを選択することでログインし、scopeには以下の二つを使用します。

https://www.googleapis.com/auth/yt-analytics.readonly[半角の空白]https://www.googleapis.com/auth/yt-analytics-monetary.readonly

access tokenが取得できたら、以下のコマンドを実行してレポートをダウンロードします。

$ curl -H "Authorization: Bearer {ACCESS_TOKEN}" \
https://youtubereporting.googleapis.com/v1/media/CHANNEL/some_channel_id/jobs/some_job_id/reports/some_report_id\?alt\=media

レポートのURLは、https://youtubereporting.googleapis.com/v1/media + downloadUrl/CHANNELを含む/CHANNEL以降の部分になります。

成功していれば、以下のようなレスポンスが返ってきます。

date,channel_id,video_id,live_or_on_demand,subscribed_status,country_code,views,comments,likes,dislikes,shares,watch_time_minutes,average_view_duration_seconds,average_view_duration_percentage,annotation_impressions,annotation_clickable_impressions,annotation_clicks,annotation_click_through_rate,annotation_closable_impressions,annotation_closes,annotation_close_rate,card_teaser_impressions,card_teaser_clicks,card_teaser_click_rate,card_impressions,card_clicks,card_click_rate,subscribers_gained,subscribers_lost,videos_added_to_playlists,videos_removed_from_playlists,red_views,red_watch_time_minutes

返ってきているのは、User activityのdimensionsとmetricsがヘッダーとなったCSVです。残念ながら、私のチャンネルにアップロードされている動画に対して一つもviewがなかったために実際のデータそのものは含まれていませんが、viewなどがあればヘッダーの下にデータが含まれた形で返ってきます。

さいごに

この記事では、YouTube Reporting APIを使って自分の動画に対するデータをCSVでダウンロードする方法を解説しました。ダウンロードしたCSVをデータベースに保存し、自分で更にデータの解析をする場合などに便利です。


  1. Google APIs Explorerは、Googleが提供するAPIをウェブから試せるページです。 [return]
comments powered by Disqus