このページでは、YouTube Reporting API と YouTube Analytics API の API の変更点とドキュメントの更新について説明します。どちらの API でも、デベロッパーはさまざまな方法で YouTube アナリティクスのデータにアクセスできます。この変更ログにご登録ください。
2023 年 12 月 4 日
YouTube アナリティクス(Targeted Queries)API が更新され、2 つの insightTrafficSourceType
ディメンション値を結合できるようになりました。これまで、このディメンションは再生リストの一部として再生される動画(PLAYLIST
)と、再生リスト内のすべての動画を一覧表示するページからの視聴(YT_PLAYLIST_PAGE
)を区別していました。今後、このディメンションは PLAYLIST
ディメンション値に関連付けられます。
2022 年 12 月 15 日
YouTube Analytics(Targeted Queries)API では、2 つの新しいディメンションと 1 つの新しいレポートがサポートされています。
-
新しいレポートでは、都市ごとのユーザー アクションを確認できます。このレポートは、チャンネルとコンテンツ所有者が閲覧できます。このレポートには、新しい
city
ディメンションが含まれます。このディメンションは、ユーザー アクションが発生した都市について YouTube が推定したものです。 -
新しい
creatorContentType
ディメンションは、データ行のユーザー アクティビティ指標に関連付けられている YouTube コンテンツの種類を識別するためのものです。サポートされている値はLIVE_STREAM
、SHORTS
、STORY
、VIDEO_ON_DEMAND
です。creatorContentType
ディメンションは、チャンネルとコンテンツ所有者のすべての動画レポートで、オプションのディメンションとしてサポートされています。 -
YouTube Analytics API のサンプル リクエスト ガイドでは、2 つの新しいディメンションの例を追加しました。
-
7DayTotals
ディメンションと30DayTotals
ディメンションへの参照は、ドキュメントから削除されました。これらのディメンションのサポート終了は 2019 年 10 月に発表されました。
2022 年 8 月 26 日
YouTube Analytics(Targeted Queries)API と YouTube Reporting(Bulk Reports)API はどちらも、新しいトラフィック ソースの詳細情報値をサポートしています。
- YouTube Analytics API(Targeted Queries)API では、
insightTrafficSourceType
ディメンションの値がSUBSCRIBER
の場合、insightTrafficSourceDetail
の値をpodcasts
に設定できます。これは、トラフィックがポッドキャストのリンク先ページから参照されたことを示します。 - YouTube Reporting(Bulk Reports)API では、
traffic_source_type
ディメンションの値が3
の場合、traffic_source_detail
の値をpodcasts
に設定できます。これは、トラフィックがポッドキャストのリンク先ページから参照されたことを示します。
2022 年 2 月 11 日
gender
ディメンションの有効な値のセットは、2022 年 8 月 11 日以降に変更されます。これは、API 実装における下位互換性のない変更である可能性があります。この変更は、YouTube API サービス利用規約の下位互換性のない変更のセクションに従い、発効する 6 か月前に発表されています。新しい値セットにシームレスに移行できるように、2022 年 8 月 11 日より前に API 実装を更新してください。
具体的な変更は次のとおりです。
- YouTube アナリティクス(Targeted Queries)API では、
gender
ディメンションは現在 2 つの値(female
とmale
)をサポートしています。2022 年 8 月 11 日以降、そのディメンションではfemale
、male
、user_specified
の 3 つの値がサポートされるようになります。 - YouTube Reporting(Bulk Reports)API において、
gender
ディメンションは現在、FEMALE
、MALE
、GENDER_OTHER
の 3 つの値をサポートしています。2022 年 8 月 11 日以降、サポートされる値のセットはFEMALE
、MALE
、USER_SPECIFIED
に変更されます。
2022 年 2 月 9 日
2021 年 12 月 13 日時点で、ループしているクリップのトラフィックを除外するように 2 つの指標が更新されました。この変更は、YouTube アナリティクス(Targeted Queries)API と YouTube Reporting(Bulk Reports)API の両方に影響します。
- YouTube Analytics(Targeted Queries)API の
averageViewDuration
指標とaverageViewPercentage
指標は、2021 年 12 月 13 日時点でループクリップのトラフィックを除外しています。 - YouTube Reporting(Bulk Reports)API の
average_view_duration_seconds
指標とaverage_view_duration_percentage
指標は、2021 年 12 月 13 日時点でのループクリップのトラフィックを除外しています。
2022 年 2 月 2 日
この YouTube Reporting(Bulk Reports)API では、視聴がライブ リダイレクトから発生したことを示す新しいトラフィック ソースのディメンション値がサポートされます。
- YouTube Reporting(Bulk Reports)API では、
traffic_source_type
ディメンションでは値28
がサポートされます。
この種類のトラフィック ソースの場合、traffic_source_detail
ディメンションは、視聴者の参照元となったチャンネル ID を示します。
2020 年 9 月 23 日
この YouTube アナリティクス(Targeted Queries)API と YouTube Reporting(Bulk Reports)API では、どちらも新しいトラフィック ソースのディメンション値をサポートしています。この値は、YouTube ショートの視聴中に上方向にスワイプすることで視聴者が参照されたことを示すものです。
- YouTube Analytics API(Targeted Queries)API では、
insightTrafficSourceType
ディメンションで値SHORTS
がサポートされます。 - YouTube Reporting(Bulk Reports)API では、
traffic_source_type
ディメンションでは値24
がサポートされます。
トラフィック ソースの詳細ディメンション(YouTube Analytics API の insightTrafficSourceDetail
または YouTube Reporting API の traffic_source_detail
)は、この新しい種類のトラフィック ソースでは入力されません。
2020 年 7 月 20 日
この更新では、YouTube アナリティクス(ターゲット クエリ)API に影響する 2 つの変更について説明します。
- YouTube アナリティクスのレポート グループの最大サイズが 200 エンティティから 500 エンティティに引き上げられました。
reports.query
メソッドのfilters
パラメータには、YouTube アナリティクス データの取得時に適用するフィルタのリストを指定します。このパラメータは、video
、playlist
、channel
フィルタに複数の値を指定する機能をサポートし、これらのフィルタに指定できる ID の最大数が 200 から 500 に増えました。
2020 年 2 月 13 日
この更新には、YouTube アナリティクス(ターゲット クエリ)API と YouTube Reporting(Bulk Reports)API に関連する次の変更が含まれます。今回の変更について詳しくは、YouTube ヘルプセンターをご覧ください。
どちらの API でも、通知のトラフィック ソースの詳細情報として指定可能な値のセットは変化しています。ターゲット クエリでは、通知は insightTrafficSourceType=NOTIFICATION
として報告されます。一括レポートでは、通知は traffic_source_type=17
として報告されます。
新しい値により、以前に uploaded
として報告されていた、アップロードされた動画とライブ配信に関連する通知が 2 つのカテゴリに分割されます。
uploaded_push
- 動画のアップロード時にチャンネル登録者に送信されたプッシュ通知から視聴された回数uploaded_other
- 動画のアップロード時にチャンネル登録者に送信される、プッシュ通知以外の通知(メールや受信トレイの通知など)から発生した視聴回数。
これらの値は、2020 年 1 月 13 日(2020 年 1 月 13 日)以降の期間に対して返されます。
なお、これらの値は通知そのものを表すものではなく、特定の YouTube の視聴につながったトラフィック ソースを表すものです。たとえば、レポートの行に views=3
、traffic_source_type=17
(NOTIFICATION
)、traffic_source_detail=uploaded_push
が表示されている場合、この行は、動画のアップロード時に送信されたプッシュ通知を視聴者がクリックしたことによる視聴回数が 3 回であることを示します。
2019 年 10 月 15 日
このアップデートには、YouTube アナリティクス(Targeted Queries)API に関連する次の変更が含まれます。
-
注: これはサポート終了のお知らせです。
YouTube は、
7DayTotals
ディメンションと30DayTotals
ディメンションのサポートを終了します。2020 年 4 月 15 日までは、これらのディメンションを使用してデータを取得できます。この日以降、7DayTotals
または30DayTotals
ディメンションを使用してレポートを取得しようとすると、エラーが返されます。なお、
day
ディメンションを使用してクエリを実行し、7 日間または 30 日間のデータを集計または導出することで、これらのディメンションの一部のデータを再現できます。例:- 7 日間の視聴回数は、その期間の各日での視聴回数を集計して算出できます。
- 7 日間の視聴者の割合は、各日の視聴回数にその日の視聴者の割合を掛けることにより、その日の動画を視聴する際にログインしていた視聴者の数を算出できます。すると、ログインしている視聴者数を期間全体に追加し、その期間の合計視聴回数で割って、期間全体の視聴者の割合を算出できます。
- 同じ視聴者が異なる日のユニーク視聴者として計算される可能性があるため、7 日間のユニーク視聴者数は計算できません。ただし、
30DayTotals
ディメンションの代わりにmonth
ディメンションを使用して、30 日間のユニーク視聴者数に関するデータを推定できる場合があります。month
ディメンションはカレンダー月を参照しているのに対し、30DayTotals
ディメンションは指定された開始日と終了日に基づいて 30 日間の期間を計算します。
2019 年 6 月 27 日
このアップデートには、YouTube アナリティクス(Targeted Queries)API に関連する次の変更が含まれます。
-
バージョン 1 の API のサポートが完全に終了したため、ドキュメントが更新され、このバージョンへの言及が削除されています。これには、サポート終了のお知らせや、バージョン 2 への更新方法を説明した移行ガイドも含まれています。
2018 年 11 月 1 日
このアップデートには、YouTube アナリティクス(Targeted Queries)API に関連する次の変更が含まれます。
-
バージョン 1 の API のサポートが終了しました。まだ更新されていない場合は、サービスの中断を最小限に抑えるために、できるだけ早く API クライアントを更新して、バージョン 2 の API を使用してください。詳しくは、移行ガイドをご覧ください。
なお、今回のサポート終了のスケジュールは、当初 2018 年 4 月 26 日に発表されたものです。
2018 年 9 月 17 日
このアップデートには、YouTube アナリティクス(Targeted Queries)API に関連する次の変更が含まれます。
-
データモデルの概要ドキュメントにある新しいデータの匿名化のセクションでは、指標が特定のしきい値に達しない場合、一部の YouTube アナリティクスのデータが制限されることを説明しています。これはさまざまなケースで発生する可能性があります。実際には、次のような場合には、すべてのデータ(または一部)がレポートに含まれないことがあります。
-
特定の期間中、動画またはチャンネルのトラフィックが制限されている
または
-
特定のしきい値に満たない値があるフィルタまたはディメンション(トラフィック ソースや国など)を選択している。
新しいセクションでは、YouTube アナリティクスのレポートで制限される可能性があるデータの種類についても説明しています。
-
-
チャンネル レポートとコンテンツ所有者レポートのドキュメントを更新し、
redViews
とestimatedRedMinutesWatched
の指標が、再生場所、トラフィック ソース、デバイスタイプ/オペレーティング システムのレポートでサポートされなくなったことを反映しました。
2018 年 6 月 18 日
この更新には、YouTube Analytics(Targeted Queries)API に関する次の変更が含まれます。
- 以下のメソッドのスコープ要件が変更されました。
reports.query
メソッドへのリクエストは、https://www.googleapis.com/auth/youtube.readonly
スコープにアクセスできる必要があります。groupItems.list
メソッドへのリクエストは、次のいずれかにアクセスできる必要があります。https://www.googleapis.com/auth/youtube
スコープ
またはhttps://www.googleapis.com/auth/youtube.readonly
スコープ
とhttps://www.googleapis.com/auth/yt-analytics.readonly
スコープ
最初のオプションでは 1 つのスコープ(読み取り / 書き込みスコープ)を使用しますが、2 番目のオプションでは 2 つの読み取り専用スコープを使用します。
2018 年 5 月 23 日
この更新には、YouTube Analytics(Targeted Queries)API に関する次の変更が含まれます。
- [API の概要] には、集計指標と削除されたアイテムという新しいセクションが追加されました。このセクションでは、削除されたリソース(動画、再生リスト、チャンネルなど)に関連付けられたデータを API レスポンスでどのように処理するかについて説明します。
- API の概要のベスト プラクティス セクションを更新し、YouTube Data API を使用して YouTube Analytics API のレスポンスで識別されたリソースの追加メタデータを取得できることを通知しました。YouTube API サービスのデベロッパー ポリシー(セクション III.E.4.b から III.E.4.d 項)に記載のとおり、API クライアントは、30 日後にその API から保存済みリソース メタデータを削除するか更新する必要があります。
2018 年 5 月 22 日
この更新には、YouTube Reporting(Bulk Reports)API に関連する次の変更が含まれます。
- 現在、以下の変更は 2018 年 7 月に適用されます。新しいポリシーは、すべてのレポートとレポートジョブにグローバルに適用されます。
-
この変更後、バックフィル レポートを含むほとんどの API レポートは、作成から 60 日間ご利用いただけます。ただし、過去のデータを含むレポートは、作成後 30 日間利用できます。
これまですべての API レポートは、作成後 180 日間ご利用いただけます。このポリシー変更が適用されると、30 日以上経過した過去のデータにも API 経由でアクセスできなくなります。生成後 60 日を超えているその他のレポートもすべてアクセスできなくなります。この変更に伴い、ポリシーの変更前に作成されたレポートについては、最長 180 日間利用できることが明記されています。
-
変更後にレポート ジョブをスケジュールすると、YouTube はその日以降、ジョブがスケジュールされた時刻の 30 日前までのレポートを生成します。変更前にレポート ジョブのスケジュールを設定すると、そのジョブがスケジュールされた時刻の 180 日前までのレポートが YouTube によって生成されます。
-
-
ベスト プラクティス セクションを更新し、YouTube Data API を使用して、レポートで特定されるリソースの追加メタデータを取得できることを通知しました。YouTube API サービスのデベロッパー ポリシー(セクション III.E.4.b から III.E.4.d 項)に記載のとおり、API クライアントは、30 日後にその API から保存済みリソース メタデータを削除するか更新する必要があります。
-
[レポートの特性] セクションを更新し、レポートデータがフィルタされていなくても、2018 年 6 月 1 日以降の期間のデータを含むレポートには、レポート生成日の 30 日以上前に削除された YouTube リソースへの参照は含まれないという点を更新しました。
-
API の概要の履歴データ セクションが更新され、新しいレポートジョブをスケジュールした場合、通常、履歴レポートが数日以内に投稿される旨を記載しています。以前のドキュメントには、このようなレポートが利用可能になるまでに最大 30 日かかることが記載されていました。
-
API の概要のバックフィル データ セクションが更新され、バックフィル データを、以前に配信されたデータのセットを置き換えるデータセットとして、より明確に定義しました。
2018 年 4 月 26 日
YouTube Analytics(Targeted Queries)API(v2)のバージョン 2 が一般公開されました。新しい API バージョンに関連したプロダクトとドキュメントの変更点は次のとおりです。
-
v2 API は v1 API とほぼ同じです。ただし、下記の変更を反映するにはコードの更新が必要となる場合もあります。これらの変更については、新しい移行ガイドで詳しく説明しています。
- API のバージョンが
v1
からv2
に変更されました。 - API リクエストのベース URL が
https://www.googleapis.com/youtube/analytics/v1
からhttps://youtubeanalytics.googleapis.com/v2
に変更されました。 reports.query
メソッドのいくつかのパラメータの名前が更新されました。具体的には、ハイフンを含むパラメータ名(v1 API のend-date
など)には、ハイフンではなくキャメルケース(endDate
)を使用します。この変更により、API 全体でパラメータ名が統一されます。これは、API のグループを作成および管理するメソッドで、パラメータ名にすでにキャメルケースが使用されているためです。- v2 API は、Google のグローバル HTTP バッチ エンドポイント(
www.googleapis.com/batch
)に送信されるバッチ リクエストをサポートしていません。v2 API でバッチ リクエストを送信する場合は、代わりにエンドポイントhttps://youtubeanalytics.googleapis.com/v2
を使用する必要があります。
また、v2 API では、以下の v1 機能はサポートされていません。
reports.query
メソッドは、alt
、quotaUser
、userIp
のリクエスト パラメータをサポートしなくなりました。- v2 API では、異なる API へのリクエストで構成されるバッチをサポートするバッチ エンドポイントは提供されていません。(ただし、バッチは、同じ API の異なるメソッドへのリクエストで構成することもできます)。グローバル バッチ エンドポイントはすべての API でサポート終了となるため、今回のサポート終了は YouTube Analytics API に固有のものではありません。
- API v2 では、API v1 でサポートされていた JSON-RPC プロトコルはサポートされていません。繰り返しになりますが、このサポート終了は YouTube Analytics API に固有のものではありません。
- API のバージョンが
-
注: これはサポート終了のお知らせです。
API のバージョン 1(v1)は非推奨になり、2018 年 10 月 31 日までサポートされます。この日を過ぎると、v1 API に対するすべてのリクエストは機能しなくなります。そのため、2018 年 10 月 31 日までに v2 API にアップグレードして、API 経由で YouTube アナリティクス データへアクセスすることが中断しないようにしてください。
2018 年 2 月 21 日
この更新には、YouTube Analytics(Targeted Queries)API に関する次の変更が含まれます。
- 視聴者の年齢層と性別に基づいて視聴の統計情報を集計するユーザー属性レポートでは、ユーザー アクションが発生した YouTube サービスを識別する
youtubeProduct
ディメンションがサポートされなくなりました。
2018 年 1 月 18 日
この改訂での変更内容は次のとおりです。
-
YouTube Reporting API(一括レポート)
- 視聴が発生したデバイスのソフトウェア システムを識別する
operating_system
ディメンションで、次の値がサポートされるようになりました。25
: KaiOS
- 視聴が発生したデバイスのソフトウェア システムを識別する
-
YouTube Analytics API(ターゲット クエリ)
- 「
operatingSystem
」ディメンションでは、ディメンション値「KAIOS
」がサポートされています。
- 「
2017 年 12 月 20 日
この更新には、YouTube Reporting API に関連する次の 2 つの変更が含まれます。
-
API サーバーで、レポートをダウンロードするリクエストで gzip 圧縮がサポートされるようになりました。他のタイプの API リクエストでは、gzip 圧縮はサポートされていません。gzip 圧縮を有効にすると、各 API レスポンスに必要な帯域幅が削減されます。また、アプリケーションで API レスポンスを解凍するために追加の CPU 時間が必要になりますが、通常、消費するネットワーク リソースを減らすことのメリットは、そのコストを上回ります。
gzip でエンコードされたレスポンスを受信するには、次の例のように
Accept-Encoding
HTTP リクエスト ヘッダーをgzip
に設定します。Accept-Encoding: gzip
この機能については、API の概要と
report
リソースのdownloadUrl
プロパティの定義をご覧ください。 -
API がこれらのディメンションに対して返す実際の値を示すように、
age group
およびgender
ディメンションのドキュメントを修正しました。これはドキュメントの修正であり、API の機能または動作の変更を反映するものではありません。具体的には、次の値が変更されました。- ディメンション「
age_group
」の値には大文字を使用し、単語「AGE
」と年齢層の数字の間にアンダースコアを使用します。ハイフンの代わりにアンダースコアを使用します。そのため、age13-17
やage18-24
などの値がそれぞれAGE_13_17
とAGE_18_24
に修正されました。 gender
ディメンションの値には大文字を使用します。したがって、値female
、male
、gender_other
は、FEMALE
、MALE
、GENDER_OTHER
に修正されます。
- ディメンション「
2017 年 8 月 10 日
このドキュメントでは、2016 年 8 月 10 日に、YouTube Analytics API の earnings
指標のサポート終了を発表しました。(これと同時に、同じデータを提供する estimatedRevenue
という名前の新しい指標のサポートも API に追加されました)。
earnings
指標はコア指標であるため、発表日から 1 年間サポートされていました。ただし、この 1 年の期間が終了したため、earnings
指標はサポートされなくなりました。その結果、earnings
指標を指定する API リクエストは 400
HTTP レスポンス コードを返すようになりました。earnings
指標ではなく estimatedRevenue
指標を使用するようにアプリをまだ更新していない場合は、できるだけ早く更新してください。
API ドキュメントが更新され、earnings
指標への残りの参照が削除されました。
2017 年 7 月 6 日
この改訂での変更内容は次のとおりです。
-
YouTube Analytics API(ターゲット クエリ)
-
API ドキュメントが更新され、API レスポンスには、クエリ対象のすべての指標が利用可能なリクエストされた期間の最終日までのデータが含まれるという事実が反映されました。
たとえば、リクエストで終了日が 2017 年 7 月 5 日を指定し、リクエストされたすべての指標の値が 2017 年 7 月 3 日までしか利用できない場合、その日がレスポンスにデータが含まれる最後の日付になります。(要求された一部の指標のデータが 2017 年 7 月 4 日の時点で利用可能である場合も同様です)。
-
adType
ディメンションで、値reservedBumperInstream
がサポートされるようになりました。これは、最大 6 秒のスキップ不可の動画広告で、動画の再生が始まる前に再生されます。広告フォーマットは「auctionBumperInstream
」広告と同じですが、このタイプはオークション ベースではなく予約制で販売される広告を指します。
-
-
YouTube Reporting API(一括レポート)
-
ad_type
ディメンションで、予約ベースで販売されるバンパー広告を表す値20
がサポートされるようになりました。バンパー広告は最長 6 秒のスキップ不可の動画広告で、動画が視聴される前に再生されます。このディメンションの値19
は、予約ベースではなくオークションで販売されるバンパー広告も参照しています。 -
次の YouTube Reporting API レポートのレポートジョブが削除されました。
channel_basic_a1
channel_province_a1
channel_playback_location_a1
channel_traffic_source_a1
channel_device_os_a1
channel_subtitles_a1
channel_combined_a1
content_owner_basic_a2
content_owner_province_a1
content_owner_playback_location_a1
content_owner_traffic_source_a1
content_owner_device_os_a1
content_owner_subtitles_a1
content_owner_combined_a1
content_owner_asset_basic_a1
content_owner_asset_province_a1
content_owner_asset_playback_location_a1
content_owner_asset_traffic_source_a1
content_owner_asset_device_os_a1
content_owner_asset_combined_a1
これらのレポートタイプは 2016 年 9 月 15 日にサポートの終了が発表され、2016 年 12 月 15 日を過ぎると生成されなくなりました。以前に生成されたレポートは、作成後 180 日間はご利用可能でした。そのため、一部のレポートには 2017 年 6 月 15 日以降にアクセスできました。ただし、レポートが利用できなくなったため、レポートに関連付けられたジョブも必要ありません。
-
2017 年 5 月 24 日
次の YouTube Reporting API レポートのレポートジョブがすべて削除されました。
content_owner_ad_performance_a1
content_owner_asset_estimated_earnings_a1
content_owner_estimated_earnings_a1
これらのレポートタイプのサポートは 2016 年 6 月 22 日に発表され、2016 年 9 月 22 日を過ぎると生成されなくなりました。以前に生成されたレポートは、作成後 180 日間はご利用可能でした。そのため、一部のレポートには 2017 年 3 月 22 日以降もアクセス可能でした。ただし、レポートが利用できなくなったため、レポートに関連付けられたジョブも必要ありません。
2017 年 5 月 22 日
この改訂での変更内容は次のとおりです。
-
YouTube Reporting API(一括レポート)
- 動画の共有に使用されたサービスを識別する
sharing_service
ディメンションで、次の値がサポートされるようになりました。85
: YouTube Music86
: YouTube Gaming87
: YouTube Kids88
: YouTube TV
さらに、値
52
を識別するための名前が Kakao(Kakao Talk)のドキュメントで更新され、値73
(Kakao Story)と明確に区別されるようになりました。API の動作やこれらのサービスと共有する動画の分類に変更は反映されません。
- 動画の共有に使用されたサービスを識別する
-
YouTube Analytics API(ターゲット クエリ)
sharingService
ディメンションで次の値がサポートされるようになりました。YOUTUBE_GAMING
YOUTUBE_KIDS
YOUTUBE_MUSIC
YOUTUBE_TV
2017 年 3 月 28 日
YouTube Studio の YouTube アナリティクスから収益データにアクセスできるチャンネル所有者は、YouTube Analytics API でもその収益データにアクセスできるようになりました。
-
この API では、次の収益関連の指標がサポートされています。
adImpressions
cpm
estimatedAdRevenue
estimatedRedPartnerRevenue
estimatedRevenue
grossRevenue
monetizedPlaybacks
playbackBasedCpm
これらの指標は、次のレポートで使用できます。
-
また、チャンネル所有者は広告パフォーマンス レポートを取得できるようになりました。このレポートでは、
adType
ディメンションとオプションのday
ディメンションがサポートされています。 -
YouTube Analytics API のサンプル リクエスト ガイドに、チャンネル収益レポートのセクションが追加されました。
2017 年 3 月 17 日
この改訂での変更内容は次のとおりです。
-
YouTube Analytics API は、YouTube Red の視聴者数に関連する
redViews
とestimatedRedMinutesWatched
の指標をサポートしています。これらの指標は以前からサポートされており、2016 年 9 月 15 日に発表されたとおり、YouTube Reporting API ではすでに両方の指標をサポートしています。redViews
指標は、YouTube Red メンバーによって動画が視聴された回数を示します。estimatedRedMinutesWatched
指標は、YouTube Red メンバーが動画を視聴した時間(分)を示します。
チャンネル レポートとコンテンツ所有者レポートのドキュメントが更新され、この 2 つの新しい指標に対応しているレポートが示されました。
views
指標とestimatedMinutesWatched
指標をすでにサポートしているすべてのレポートでサポートされます。
2017 年 3 月 3 日
この改訂での変更内容は次のとおりです。
-
YouTube Reporting API(一括レポート)
-
date
ディメンションの定義を修正しました。このディメンション値は、太平洋時間の午前 12 時から、指定した日、月、年の午後 11 時 59 分までを指します。時間帯に応じて、太平洋時間は UTC-7 または UTC-8 です。通常、日付は 24 時間を表しますが、時計を先に調整した日付は 23 時間、時計を逆に調整した日付は 25 時間を表します。(以前のドキュメントでは、各日付は一意の 24 時間で表され、太平洋時間は常に UTC-8 であることが記載されていました)。
この修正は、実際の API の動作を変更するものではありません。
- 視聴が発生したデバイスのソフトウェア システムを識別する
operating_system
ディメンションで、次の値がサポートされるようになりました。22
: Tizen23
: Firefox24
: RealMedia
-
レポートタイプ「
content_owner_basic_a1
」のすべてのレポートジョブが削除されました。このレポートタイプは 2016 年 8 月 19 日をもってサポートは完全に終了しましたが、以前に生成されたcontent_owner_basic_a1
レポートは、作成後 180 日間はご利用可能でした。そのため、一部のレポートには 2017 年 2 月 19 日以降もアクセス可能でした。ただし、レポートが利用できなくなったため、レポートに関連付けられたジョブも必要ありません。
-
-
YouTube Analytics API(ターゲット クエリ)
-
time periods
に関連するディメンションの説明を修正しました。ディメンションの値は、太平洋時間の午前 12 時から、指定した日、月、年の午後 11 時 59 分までを指します。時間帯に応じて、太平洋時間は UTC-7 または UTC-8 です。通常、日付は 24 時間を表しますが、時計を先に調整した日付は 23 時間、時計を逆に調整した日付は 25 時間を表します。(以前のドキュメントには、太平洋時間が UTC-8 であると記載されていましたが、1 日が 24 時間の期間を表していない可能性については言及していませんでした)。
この修正は、実際の API の動作を変更するものではありません。
-
チャンネル レポートのドキュメントが更新されました。現在、チャンネル レポートには収益や広告の掲載結果の指標が含まれていないことを明記しています。そのため、現在のところ、
https://www.googleapis.com/auth/yt-analytics-monetary.readonly
スコープではチャンネル レポート内の収益データへのアクセス権は付与されていません。 - 「
operatingSystem
」ディメンションでは、次の 3 つの新しいディメンション値がサポートされています。FIREFOX
REALMEDIA
TIZEN
-
2017 年 2 月 8 日
YouTube Analytics API で、オプションの include-historical-channel-data
パラメータをサポートするようになりました。このパラメータは、コンテンツ所有者レポートを取得する場合にのみ関連します。
コンテンツ所有者は、このパラメータを使って、チャンネルの総再生時間と、チャンネルがコンテンツ所有者にリンクされる前の期間の視聴データを API レスポンスに含めるよう指定できます。デフォルトのパラメータ値は false
です。つまり、デフォルトで API レスポンスには、チャンネルがコンテンツ所有者にリンクされた時点以降の総再生時間と視聴データのみが含まれます。
これらのルールは、API リクエストが複数のチャネルのデータを取得する場合にも適用されます。
- パラメータ値が
false
の場合、特定のチャンネルに対して返される総再生時間と視聴回数のデータは、そのチャンネルがコンテンツ所有者にリンクされた日付に基づきます。
なお、コンテンツ所有者にリンクされるチャンネルは日付によって異なることがあります。API リクエストが複数のチャンネルのデータを取得しており、パラメータ値がfalse
の場合、API レスポンスには各チャンネルのリンク日に基づく総再生時間と視聴データが含まれます。 - パラメータ値が
true
の場合、API リクエストで指定された開始日と終了日に基づいて、すべてのチャンネルの総再生時間と視聴データが返されます。
2016 年 12 月 15 日
以下の YouTube Reporting API レポートはサポートが終了し、ドキュメントから削除されました。各レポートには新しいバージョンが用意されています。(これらのレポートのサポート終了のお知らせは、2016 年 9 月 15 日に行われました)。
-
チャンネル レポート
channel_basic_a1
-channel_basic_a2
レポートに置き換えられます。channel_province_a1
-channel_province_a2
レポートに置き換えられます。channel_playback_location_a1
-channel_playback_location_a2
レポートに置き換えられます。channel_traffic_source_a1
-channel_traffic_source_a2
レポートに置き換えられます。channel_device_os_a1
-channel_device_os_a2
レポートに置き換えられます。channel_subtitles_a1
-channel_subtitles_a2
レポートに置き換えられます。channel_combined_a1
-channel_combined_a2
レポートに置き換えられます。
-
コンテンツ所有者レポート
content_owner_basic_a2
-content_owner_basic_a3
レポートに置き換えられます。content_owner_province_a1
-content_owner_province_a2
レポートに置き換えられます。content_owner_playback_location_a1
-content_owner_playback_location_a2
レポートに置き換えられます。content_owner_traffic_source_a1
-content_owner_traffic_source_a2
レポートに置き換えられます。content_owner_device_os_a1
-content_owner_device_os_a2
レポートに置き換えられます。content_owner_subtitles_a1
-content_owner_subtitles_a2
レポートに置き換えられます。content_owner_combined_a1
-content_owner_combined_a2
レポートに置き換えられます。content_owner_asset_basic_a1
-content_owner_asset_basic_a2
レポートに置き換えられます。content_owner_asset_province_a1
-content_owner_asset_province_a2
レポートに置き換えられます。content_owner_asset_playback_location_a1
-content_owner_asset_playback_location_a2
レポートに置き換えられます。content_owner_asset_traffic_source_a1
-content_owner_asset_traffic_source_a2
レポートに置き換えられます。content_owner_asset_device_os_a1
-content_owner_asset_device_os_a2
レポートに置き換えられます。content_owner_asset_combined_a1
-content_owner_asset_combined_a2
レポートに置き換えられます。
API リファレンス ドキュメントの現在のレポートタイプのリストも更新されました。
2016 年 11 月 11 日
この改訂での変更内容は次のとおりです。
-
終了画面のレポート
- チャンネルの動画の終了画面レポートには、チャンネルのすべての動画の統計情報が含まれます。
- コンテンツ所有者の動画の終了画面レポートには、コンテンツ所有者のチャンネルの動画の統計情報が含まれます。
- コンテンツ所有者のアセットの終了画面レポートには、動画に関連付けられたアセットの統計情報が含まれ、その後に終了画面が表示されます。
-
終了画面のサイズ
end_screen_element_type
: 統計情報に関連付けられている終了画面要素のタイプ。end_screen_element_id
: 終了画面の要素を一意に識別するために YouTube によって使用される ID。
終了画面の指標
注: 終了画面に関する指標のデータは、2016 年 5 月 1 日以降で利用できます。
end_screen_element_impressions
: 終了画面要素の合計表示回数。インプレッションは、表示される終了画面要素ごとに 1 回記録されます。end_screen_element_clicks
: 終了画面要素がクリックされた回数。end_screen_element_click_rate
: 終了画面要素のクリック率。
-
以下のレポートはサポートが終了し、ドキュメントから削除されました。各レポートには新しいバージョンが用意されています。(これらのレポートのサポート終了のお知らせは、2016 年 6 月 22 日に行われました)。
content_owner_ad_performance_a1
-content_owner_ad_rates_a1
レポートに置き換えられます。content_owner_estimated_earnings_a1
-content_owner_estimated_revenue_a1
レポートに置き換えられます。content_owner_asset_estimated_earnings_a1
-content_owner_asset_estimated_revenue_a1
レポートに置き換えられます。
-
次のリストの指標は、完全に非推奨になり、サポートを終了しました。2016 年 8 月 10 日にお知らせしたとおり、同じデータを参照する新しい指標はすでにサポートされています。次の表に、非推奨の指標名と新しい指標名を示します。
非推奨の指標 新しい指標 adEarnings
estimatedAdRevenue
impressionBasedCpm
cpm
impressions
adImpressions
redPartnerRevenue
estimatedRedPartnerRevenue
- 動画ごとの全世界における月間広告収益
- 動画ごとの国ごとの日別広告収益
- アセットごとの全世界における月間広告収益
- アセットごとの国ごとの日別広告収益
- 申し立て(このレポートに収益データは含まれません)
-
この API では、YouTube Red の視聴者数に関する 2 つの新しい指標がサポートされています。
red_views
: YouTube Red メンバーが動画を視聴した回数。red_watch_time_minutes
: YouTube Red メンバーが動画を視聴した時間(分)。
-
この API では、20 個のレポートの新しいバージョンがサポートされています。すべての新しいバージョンで、新しい指標
red_views
とred_watch_time_minutes
がサポートされます。レポートごとに、新しいレポートタイプ ID の番号は以前のレポートタイプ ID の番号よりも 1 つ増えます。(これらのレポートの旧バージョンのサポートは終了しました。詳細については、この変更履歴で後ほど説明します)。たとえば
channel_basic_a1
レポートはサポート終了となり、channel_basic_a2
レポートに置き換えられました。新しいレポートタイプ ID は以下のとおりです。
チャンネルの動画レポート
コンテンツ所有者の動画レポート
コンテンツ所有者のアセット レポート
-
注: これはサポート終了のお知らせです。
上記のレポートの旧バージョンのいずれかを作成するジョブがすでにある場合は、名前を変更したレポートに対応する新しいジョブを作成する必要があります。新しいバージョンのレポートのリリースに伴い、次のバージョンのレポートのサポートは終了しました。
channel_basic_a1
channel_province_a1
channel_playback_location_a1
channel_traffic_source_a1
channel_device_os_a1
channel_subtitles_a1
channel_combined_a1
content_owner_basic_a2
content_owner_province_a1
content_owner_playback_location_a1
content_owner_traffic_source_a1
content_owner_device_os_a1
content_owner_subtitles_a1
content_owner_combined_a1
content_owner_asset_basic_a1
content_owner_asset_province_a1
content_owner_asset_playback_location_a1
content_owner_asset_traffic_source_a1
content_owner_asset_device_os_a1
content_owner_asset_combined_a1
これらのレポートのいずれかに該当する求人がある場合、2016 年 12 月 15 日以降は、その求人に関する新しいレポートが生成されることはありません。生成されたレポートは、作成後 180 日間は利用可能です。
-
content_owner_basic_a1
レポートが完全に非推奨になり、ドキュメントから削除されました。YouTube ではこの種類の新しいレポートは生成されなくなりますが、すでに生成されているレポートは、生成後 180 日間は使用できます。content_owner_basic_a1
レポートは、2016 年 5 月 19 日の変更履歴で説明されているcontent_owner_basic_a2
レポートに置き換えられます。 -
YouTube のエンジニアリングとデベロッパー ブログで詳しく説明されている、新しく公開された YouTube API サービス利用規約(以下「更新後の規約」)では、現在の利用規約に加えられたさまざまな更新内容を提供しています。2017 年 2 月 10 日より適用される更新された利用規約に加えて、この更新には、デベロッパーが従う必要のあるポリシーを説明するのに役立つ補足ドキュメントがいくつか含まれています。
新しいドキュメントのすべてについては、更新された利用規約の変更履歴をご覧ください。さらに、更新版規約や関連文書に対する今後の変更についても、その変更履歴に記載されています。ドキュメントのリンクから、変更履歴における変更内容をリストする RSS フィードに登録できます。
-
YouTube Analytics API(ターゲット クエリ)
-
注: これはサポート終了のお知らせです。
次の表に示す指標は非推奨です。それと同時に、同じデータを参照する新しい指標も導入されています。つまり、古い指標の名前が変更されますが、YouTube Analytics API では、表に記載されているサポート終了日まで両方の指標名がサポートされます。
以前の指標名 新しい指標名 サポート日 earnings
estimatedRevenue
2017 年 8 月 10 日 adEarnings
estimatedAdRevenue
2016 年 11 月 4 日 redPartnerRevenue
estimatedRedPartnerRevenue
2016 年 11 月 4 日 impressionBasedCpm
cpm
2016 年 11 月 4 日 impressions
adImpressions
2016 年 11 月 4 日 なお、
earnings
指標はコア指標だったため、今回の発表から 1 年間サポートされます。その他の指標(主要指標ではない)は、2016 年 11 月 4 日までの 3 か月間サポートされます。たとえば 2016 年 11 月 4 日までは、API リクエストで
impressionBasedCpm
指標とcpm
指標のいずれかまたは両方を指定できます。ただし、この日以降はcpm
指標のみがサポートされます。 - 「
insightTrafficSourceType
」ディメンションでは、次の 2 つの新しいディメンション値がサポートされます。CAMPAIGN_CARD
: このトラフィック ソースはコンテンツ所有者レポートでのみサポートされています。これは、コンテンツ所有者が視聴済みコンテンツのプロモーションに使用し、申し立てを受けたユーザーによってアップロードされた動画から視聴されたことを示しています。END_SCREEN
: 別の動画の終了画面から発生した視聴回数に関するデータ。
どちらの新しいトラフィック ソースについても、
traffic source detail
レポートを取得できます。どちらの場合も、insightTrafficSourceDetail
ディメンションにより、視聴者が参照された動画を特定できます。 -
adType
ディメンションで、値auctionBumperInstream
がサポートされるようになりました。これは、最大 6 秒のスキップ不可の動画広告で、動画の再生が始まる前に再生されます。
-
-
YouTube Reporting API(一括レポート)
traffic_source_type
ディメンションで以下の値がサポートされるようになりました。19
: このトラフィック ソースはコンテンツ所有者レポートでのみサポートされています。これは、コンテンツ所有者が視聴済みコンテンツのプロモーションに使用し、申し立てを受けたユーザーによってアップロードされた動画から視聴されたことを示しています。20
: 別の動画の終了画面から発生した視聴回数に関するデータ。
どちらのトラフィック ソースも、
traffic_source_detail
ディメンションにより、視聴者の参照元となった動画が特定されます。-
API のコア指標のリストが修正され、
estimated_partner_revenue
がコア指標としてリストされ、そのリストからearnings
が削除されました。(earnings
指標は YouTube Reporting API ではサポートされていません)。 -
ad_type
ディメンションで、バンパー広告(動画が視聴される前に再生される最長 6 秒のスキップ不可の動画広告)を指す値19
がサポートされるようになりました。
-
YouTube Analytics API(ターゲット クエリ)
- 以下のチャンネル レポートでサポートされている指標のリストが更新され、カード指標が追加されました。これらのレポートでのカード指標のサポートは、実際には 2016 年 6 月 28 日に追加されました。変更の詳細は、その日付の変更履歴のエントリで確認できます。レポートは次のとおりです。
- 米国の州での基本的なユーザー アクティビティ
- 特定期間の米国各州におけるユーザー アクティビティ
- 州別のユーザー アクティビティ
- 登録済みステータス別のユーザー アクティビティ
- 州ごとの登録済みステータス別のユーザー アクティビティ
- 上位の動画(州別)
- チャンネル登録者または未登録の視聴者に人気の動画
-
チャンネルの視聴者維持率レポートとコンテンツ所有者の視聴者維持率レポートの両方でフィルタのリストを修正しました。
video
フィルタが必須であり、group
フィルタがサポートされていないことが明記されています。以前の両方のレポートのドキュメントには、この 2 つのフィルタのいずれかを使用するか、どちらのフィルタも使用せずにレポートを取得できると誤って記載されていました。
- 以下のチャンネル レポートでサポートされている指標のリストが更新され、カード指標が追加されました。これらのレポートでのカード指標のサポートは、実際には 2016 年 6 月 28 日に追加されました。変更の詳細は、その日付の変更履歴のエントリで確認できます。レポートは次のとおりです。
-
YouTube Reporting API(一括レポート)
- API の概要で、レポートのダウンロード URL の取得方法に関するセクションを更新し、データが利用できない日についてはダウンロード可能なレポートを YouTube が生成することを明記しました。これらのレポートにはヘッダー行が含まれますが、追加データは含まれません。この情報は、同じドキュメントの「レポートの特性」セクションですでに 2016 年 4 月 12 日に更新されています。
content_owner_asset_cards_a1
レポートのディメンションのリストが修正され、レポートでcard_id
ディメンションが使用されるようになりました。以前のドキュメントでは、ディメンション名がcard_title
と誤って記載されていました。
- 基本統計情報(チャンネル、コンテンツ所有者)
- 時間ベース(チャンネル、コンテンツ所有者)
- ユーザーの地域(チャンネル、コンテンツ所有者)
- チャンネル登録ステータス別のユーザー アクティビティ(チャンネル、コンテンツ所有者)
- 人気の動画(チャンネル、コンテンツ所有者)
-
API の概要のレポートの特性セクションが更新され、レポートの生成から 180 日間は API 経由でレポートを利用できることが明記されました。
以前のドキュメントには、API リクエストの送信日から最大 180 日間についてレポートが生成されると記載されていました。技術的にも正しいものの、オリジナルのテキストは、良くもわかりづらいものでした。
-
API では、3 つのレポートの新しいバージョンがサポートされています。そのうち 2 つのレポートには、新しい指標と名前が変更された指標も含まれています。
-
content_owner_ad_rates_a1
レポートは、「content_owner_ad_performance_a1
」レポートの新しいバージョンです。名前が変更されたレポートは前のバージョンと同じです。 -
新しいバージョンを含む 2 つのレポートの名前が変更されました。
content_owner_estimated_earnings_a1
レポートの新しいバージョンの名前は「content_owner_estimated_revenue_a1
」です。content_owner_asset_estimated_earnings_a1
レポートの新しいバージョンの名前は「content_owner_asset_estimated_revenue_a1
」です。
名前が新しくなったレポートは、従来版と次の点で異なります。
- YouTube Premium 定期購入の総収益を推定する新しい指標
estimated_partner_red_revenue
を追加しました。 - 新しい指標
estimated_partner_transaction_revenue
を追加しました。この指標は、有料コンテンツや視聴者ファンディングなどの取引の収益から、パートナーの請求による払い戻しを差し引いた収益を推定するものです。 estimated_partner_ad_sense_revenue
指標の名前をestimated_partner_ad_auction_revenue
に変更しました。estimated_partner_double_click_revenue
指標の名前をestimated_partner_ad_reserved_revenue
に変更しました。
これらのレポートの旧バージョンを作成するジョブがすでにある場合は、名前を変更したレポートに対応する新しいジョブを作成する必要があります。新しいバージョンのレポートのリリースに伴い、
content_owner_ad_performance_a1
、content_owner_estimated_earnings_a1
、content_owner_asset_estimated_earnings_a1
の各レポートのサポートは終了しました。これらのレポートのいずれかに該当する求人がある場合、2016 年 9 月 22 日以降は、その求人に関する新しいレポートが生成されることはありません。生成されたレポートは、作成後 180 日間は利用可能です。
-
-
reportType
リソースのid
プロパティの定義が更新され、利用可能なレポートの現在のセットが反映されました。 -
2 つの指標の名前が、レポートに表示される名前と一致するようにドキュメントで修正されました。これは単なるドキュメントの修正であり、実際のレポートの内容の変更を反映するものではありません。
estimated_partner_adsense_revenue
指標の名前がestimated_partner_ad_sense_revenue
に更新されました。ただし、この指標が表示されるのは、今回の更新でサポートが終了する 2 つのレポートのみです。上記のように、これらのレポートの新しいバージョンでは、この指標の名前がestimated_partner_ad_auction_revenue
に変更されました。estimated_partner_doubleclick_revenue
指標の名前がestimated_partner_double_click_revenue
に更新されました。繰り返しになりますが、この指標は今回の更新でサポートが終了する 2 つのレポートにのみ表示されます。上記のように、これらのレポートの新しいバージョンでは、この指標の名前がestimated_partner_ad_reserved_revenue
に変更されました。
-
Reporting API のディメンションのドキュメントが更新され、
elapsed_video_time_percentage
プロパティとaudience_retention_type
プロパティが表示されなくなりました。これらのディメンションは、現在 API で利用できるどのレポートでもサポートされていません。 -
この API は、新しいバージョンのコンテンツ所有者アクティビティ レポートをサポートしています。新しいレポートのレポートタイプ ID は
content_owner_basic_a2
です。以前のバージョンのレポートcontent_owner_basic_a1
とは異なり、新しいバージョンではlikes
指標とdislikes
指標がサポートされています。content_owner_basic_a1
レポートを作成するジョブがすでに存在する場合でも、content_owner_basic_a2
レポート用の新しいジョブを作成する必要があります。YouTube は、コンテンツ所有者を自動的に新しいレポート バージョンに移行することや、新しいレポート バージョンを生成するジョブを自動的に作成することはありません。実装によっては、新しい予期しないジョブの表示が互換性を破る変更になる可能性があります。新しいレポートのリリースに伴い、
content_owner_basic_a1
レポートは非推奨になりました。そのレポートのジョブがある場合、2016 年 8 月 19 日以降、そのジョブに関する新しいレポートが生成されることはありません。生成されたレポートは、作成後 180 日間は利用可能です。 -
reportType
、job
、report
リソースはすべて、関連するリソースが非推奨のレポートタイプを表すかどうかを識別する新しいプロパティをサポートしています。-
reportType
リソースのdeprecateTime
プロパティは、レポートタイプのサポートを終了する日時を指定します。このプロパティで指定されるのは、サポート終了が発表されたレポートの値のみで、YouTube がそのタイプのレポートの生成を停止する日付を表します。特定のレポートタイプのサポート終了が発表されると、YouTube はそのタイプのレポートをさらに 3 か月間生成します。たとえば、2016 年 5 月 19 日のアップデートでは、
content_owner_basic_a1
レポートのサポート終了を発表しています。つまり、そのレポートタイプのdeprecateTime
では、2016 年 8 月 19 日の時刻が指定されていて、それ以降は YouTube はそのタイプのレポートの生成を停止します。 -
job
リソースのexpireTime
プロパティは、ジョブが期限切れまたは期限切れになる日時を指定します。ジョブに関連付けられたレポートタイプが廃止されている場合、またはジョブに対して生成されたレポートが長期間ダウンロードされていない場合、このプロパティには値が入ります。この日付は、そのジョブに関する新しいレポートが YouTube で生成されなくなる時刻を示します。 -
report
リソースのjobExpireTime
プロパティは、レポートに関連付けられている求人が期限切れになるか期限切れになる日時を指定します。このプロパティには、このリストの前の項目で説明したように、job
リソースのexpireTime
プロパティと同じ値が含まれます。
-
-
サポートが終了したレポートのジョブを作成しようとすると、
jobs.create
メソッドが400
HTTP レスポンス コード(Bad Request
)を返すようになりました。また、このメソッドのドキュメントでは、API リクエストが失敗する原因となる他の理由をいくつか挙げています。 -
レポートジョブが最初にスケジュールされた時点の 180 日前までのデータが YouTube で生成されるようになりました。これまで、Reporting API は過去のデータを配信していませんでした。この変更は、このお知らせの前に作成されたジョブを含むすべてのジョブに影響します。
履歴レポートは、ジョブに対してすべての履歴データが投稿されるまでに約 1 か月かかりますが、利用可能になるとすぐに投稿されます。そのため、レポートジョブをスケジュールしてから 1 か月後、約 7 か月分のデータにアクセスできるようになります。(この発表の前に作成された求人の履歴データはすべて、この発表から 1 か月以内に投稿する必要があります)。
過去のデータは 2015 年 7 月 1 日以降のデータのみ利用できます。そのため、2015 年 12 月 28 日より前に作成されたジョブの過去のデータは、180 日未満になります。
これらの変更については、Reporting API の概要の新しい過去のデータセクションで確認できます。
-
YouTube Reporting API の概要のレポートの特性セクションが更新され、以下の変更が加えられました。
-
ドキュメントには、レポートは生成後 180 日間は保存され、API クライアントはダウンロードできると記載されています。以前のドキュメントには、API リクエストの送信日から最大 6 か月前までのレポートが利用可能であることが記載されていました。
-
データが利用できない日については API でダウンロード可能なレポートが生成されるようになったという事実を反映して、ドキュメントが更新されました。これらのレポートにはヘッダー行が含まれますが、追加のデータは含まれません。
-
-
YouTube Reporting API では、広告収益データや YouTube Premium 定期購入収益データを含む、自動生成され、システム管理型の一連のレポートがまもなくサポートされるようになります。このレポートは、YouTube クリエイター ツールで手動でダウンロード可能な収益レポートにアクセスできるコンテンツ所有者にご利用いただけます。したがって、この新しい API 機能では、そのデータにプログラム的にアクセスできます。
システム管理レポートのリリースに向けて、次の API の変更が発表されます。
-
job
リソースの新しいsystemManaged
プロパティは、このリソースがシステム管理レポートを生成するジョブを記述しているかどうかを示します。YouTube のコンテンツ所有者に対しては、システム管理レポートが自動的に生成されます。コンテンツ所有者は、そうしたレポートを作成するジョブの変更や削除はできません。 -
jobs.list
メソッドの新しいincludeSystemManaged
パラメータは、API レスポンスにシステム管理レポートのジョブを含める必要があるかどうかを示します。パラメータのデフォルト値はfalse
です。 -
jobs.reports.list
メソッドの新しいstartTimeAtOrAfter
パラメータは、レポートの最も古いデータが指定した日付以降の場合にのみ、API レスポンスにレポートが含まれることを示します。同様に、startTimeBefore
パラメータは、レポートの最も古いデータが指定した日付より前の場合にのみ、API レスポンスにレポートが含まれることを示します。レポートが作成された時刻に関連するメソッドの
createdAfter
パラメータとは異なり、新しいパラメータはレポートのデータに関するものです。 -
reportType
リソースの新しいsystemManaged
プロパティは、このリソースがシステム管理レポートを記述しているかどうかを示します。 -
reportTypes.list
メソッドの新しいincludeSystemManaged
パラメータは、API レスポンスにシステム管理レポートを含めるかどうかを示します。パラメータのデフォルト値はfalse
です。
-
- YouTube Reporting API の
sharing_service
ディメンションでは、次の新しい値がサポートされています。82
: iOS システム アクティビティ ダイアログ83
: Google 受信トレイ84
: Android メッセンジャー
- YouTube Analytics API の
sharingService
ディメンションでは、次の新しい値がサポートされています。ANDROID_MESSENGER
: Android メッセンジャーINBOX
: Google 受信トレイIOS_SYSTEM_ACTIVITY_DIALOG
: iOS システム アクティビティ ダイアログ
- 「
playback_location_type
」ディメンションでは、次の 2 つの新しいディメンション値がサポートされます。7
: YouTube のホームページ、ホーム画面、ユーザーの登録チャンネル フィード、または YouTube の別のブラウジング機能で発生した視聴回数に関するデータ。8
: YouTube 検索結果ページで直接発生した視聴回数のデータ。
traffic_source_type
ディメンションで、ディメンション値として18
がサポートされるようになりました。この値は、再生リスト内のすべての動画を一覧表示するページから動画再生回数が発生したことを示します。このソースはソースタイプ14
とは異なります。ソースタイプは、再生リストの一部として動画の再生中に発生した視聴回数であることを示します。- 「
insightPlaybackLocationType
」ディメンションでは、次の 2 つの新しいディメンション値がサポートされます。BROWSE
: YouTube のホームページ、ホーム画面、ユーザーの登録チャンネル フィード、または YouTube の別のブラウジング機能で発生した視聴回数に関するデータ。SEARCH
: YouTube 検索結果ページで直接発生した視聴回数のデータ。
insightTrafficSourceType
ディメンションで、ディメンション値としてYT_PLAYLIST_PAGE
がサポートされるようになりました。この値は、再生リスト内のすべての動画を一覧表示するページから動画再生回数が発生したことを示します。このソースは、再生リストの一部として動画の再生中に発生した視聴回数を示すPLAYLIST
ソースタイプとは異なります。- YouTube Reporting API では、
operating_system
ディメンションは値21
を使用して、Chromecast を経由した視聴を表します。 - YouTube Analytics API では、
operatingSystem
ディメンションは値CHROMECAST
を使用して、Chromecast を経由した視聴を識別します。 -
YouTube Analytics API で、3 つの新しい再生詳細ディメンションがサポートされるようになりました。これらのディメンションは、チャンネル レポートとコンテンツ所有者に関するさまざまなレポートで使用できます。
liveOrOnDemand
: このディメンションは、レポートのデータが、ライブ配信中のユーザー アクティビティを示しているかどうかを示します。subscribedStatus
: このディメンションは、データ内のユーザー アクティビティ指標が、動画または再生リストのチャンネルに登録している視聴者に関連付けられているかどうかを示します。youtubeProduct
: このディメンションは、ユーザー アクションが発生した YouTube プロパティを示します。指定できる値は、YouTube の中核となるウェブサイト(または YouTube アプリ)、YouTube Gaming、YouTube Kids です。
チャンネルとコンテンツ所有者が利用できる新しい再生詳細レポートを識別できるよう、ドキュメントが更新されました。また、その他の多くのレポートが更新され、これらのディメンションの 1 つ以上をオプションでディメンションやフィルタとして使用できるようになりました。
-
レポートを説明する表の形式が変更され、各レポートの取得に使用できるディメンション、指標、フィルタの有効な組み合わせを簡単に特定できるようになりました。以下の表に新しいフォーマットを示します。以下の表はチャネルの「デバイスタイプ」レポートの説明です。
目次 サイズ: 必須 deviceType 0 以上の値を使用 day、liveOrOnDemand、subscribedStatus、youtubeProduct 指標: 1 つ以上使用 views、estimatedMinutesWatched フィルタ: 0 または 1 を使用します country、economic、新しい機能、subContinent 0 または 1 を使用します video、group 0 以上の値を使用 operatingSystem、liveOrOnDemand、subscribedStatus、youtubeProduct 必須フィールドとオプション フィールドに関する用語については、チャンネル レポートとコンテンツ所有者 レポートのドキュメントをご覧ください。
-
YouTube Analytics API では、複数の値(
video
、playlist
、channel
)をサポートするフィルタからデータを取得できないエンティティが自動的に削除されるようになりました。これまでは、指定したアイテムの少なくとも 1 つのデータに API ユーザーがアクセスできない場合、API サーバーはエラーを返していました。たとえば、
video
フィルタで 20 個の動画 ID がリストされている API リクエストをユーザーが送信したとします。ユーザーが 18 本の動画を所有している。ただし、1 つの動画 ID は別のチャンネルが所有する動画を示し、もう 1 つの ID は、削除されたため存在しない動画を示します。この場合、API サーバーはエラーを返すのではなく、ユーザーがアクセスできない 2 つの動画を削除します。API レスポンスには、API ユーザーが所有する 18 本の動画のデータが含まれます。 -
空の YouTube アナリティクス
group
のデータをリクエストした場合、API はエラーではなく空のデータセットを返すようになりました。 -
YouTube Analytics API の
groupItems.insert
メソッドが、エンティティをグループに追加しようとしたときにそのエンティティへのアクセス権がない場合、未承認(403
HTTP レスポンス コード)エラーを返すようになりました。これまでは、API でグループにエンティティを追加できましたが、後でそのグループのレポートデータを取得しようとすると、未承認のエラーが返されました。 -
YouTube Analytics API の
groups.list
メソッドでページ分けがサポートされるようになりました。API レスポンスで使用可能なグループがすべて含まれていない場合、レスポンスのnextPageToken
パラメータには、結果の次のページを取得するために使用するトークンを指定します。メソッドのpageToken
パラメータをその値に設定すると、追加の結果を取得できます。 -
YouTube Analytics API で
redPartnerRevenue
指標がサポートされるようになりました。この指標は、選択したレポート ディメンションで YouTube Premium の定期購入から得られた推定収益の合計をレポートするものです。指標の値は音楽コンテンツと音楽以外のコンテンツの両方からの収益を反映しており、月末に調整される可能性があります。YouTube Analytics API のコンテンツ所有者レポートのリストが更新され、
redPartnerRevenue
指標をサポートする動画レポートを識別できるようになりました。 -
YouTube Analytics API の人気の動画レポートの定義では、このレポートで収益の指標(
earnings
、adEarnings
、grossRevenue
、monetizedPlaybacks
、playbackBasedCpm
、impressions
、impressionBasedCpm
)もサポートされるようになりました。 -
YouTube Reporting API の
date
ディメンションのドキュメントを修正しました。日付が太平洋時間の午前 12 時(UTC-8)から始まる 24 時間を参照していることを反映するように修正されました。以前のドキュメントには、日付が午前 12 時(GMT)に始まると記載されていました。また、YouTube Analytics API のドキュメントが更新され、日付関連のディメンション(
day
、7DayTotals
、30DayTotals
、month
)はすべて、太平洋時間(UTC-8)の午前 12 時からの日付を指していることを記載しました。 -
YouTube Reporting API の
jobs.reports.list()
メソッドで、クエリ パラメータcreatedAfter
がサポートされるようになりました。このパラメータを指定すると、指定した日時以降に作成されたレポート(バックフィルされたデータの新しいレポートを含む)のみが API レスポンスでリストされます。パラメータ値は、レポートが作成された時刻に関するもので、返されたデータに関連付けられた日付に関するものではありません。パラメータ値は、RFC3339 UTC「Zulu」形式のタイムスタンプで、精度はマイクロ秒です。(例:
"2015-10-02T15:01:23.045678Z"
)。YouTube Reporting API のベスト プラクティスも更新され、同じレポートが繰り返し処理されないように
createdAfter
パラメータを使用する方法について説明しました。 -
job
リソースのcreateTime
プロパティと、report
リソースのstartTime
、endTime
、createTime
プロパティの定義がすべて修正され、プロパティ値がナノ秒ではなくマイクロ秒に正確であることに気付きました。また、プロパティ値がタイムスタンプであることがすべての定義に正確に反映されるようになりました。 -
YouTube Analytics API の
sharingService
ディメンションのドキュメントが更新され、使用可能なディメンション値のリストが追加されました。このリストには、新たにサポートされるサービスがいくつか含まれています。YouTube Reporting API の
sharing_service
ディメンションの定義も更新され、新たにサポートされる値が追加されました。59
より大きい列挙値は、リスト内の新しい値です。 -
新しい YouTube Reporting API を使用すると、チャンネルまたはコンテンツ所有者の YouTube アナリティクス データを含む一括データレポートを取得できます。大規模なデータセットをインポートし、そのデータのフィルタリング、並べ替え、マイニングを行うためのツールを提供するアプリケーション向けに設計されています。
各 YouTube Reporting API レポートには、事前定義されたディメンションと指標のセットが含まれています。(YouTube Analytics API レポートでも指標とディメンションが使用されます)。レポートの各行には、ディメンション値の一意の組み合わせがあります。行のデータをディメンション値に基づいて集計し、個々の動画、国、ライブ動画、チャンネル登録しているユーザーなどの指標を計算できます。
API を使用してレポート作成ジョブのスケジュールを設定できます。各ジョブには、YouTube が生成するレポートが識別されます。ジョブを設定すると、YouTube によって日次レポートが生成され、非同期でダウンロードできます。各レポートには、24 時間の固有のデータが含まれます。
-
YouTube Analytics API と YouTube Reporting API はどちらも別の API ですが、デベロッパーはどちらも YouTube アナリティクス データを取得できます。どちらの API も類似したデータセットへのアクセスを提供しているため、ドキュメントは 1 つのドキュメント セットとして公開されています。
- ドキュメント セットの [ガイド] タブには、API リクエストを承認する手順など、両方の API に共通する情報が含まれています。
- [一括レポート] タブには、YouTube Reporting API 向けのリファレンス ドキュメントやその他のコンテンツが用意されています。
- [ターゲット クエリ] タブには、YouTube Analytics API に関するリファレンス ドキュメントなどのコンテンツがあります。
- [サンプル] タブには、2 つの API のいずれかで使用できるコードサンプルが表示されます。
- [Tools] タブには、デベロッパーが 2 つの API のいずれかを実装するために役立つ追加リソースが表示されます。
-
API ドキュメントは、API を理解しやすくするために再構成されました。そのため、これらの変更は新機能について説明するものではありません。
-
このドキュメントには、利用可能なすべてのチャンネル レポートを一覧表示する 1 つのページと、利用可能なすべてのコンテンツ所有者レポートを一覧表示するページが追加されました。これまで、このドキュメントにはチャンネルの動画レポート、チャンネル再生リストのレポートなど別のページがありました。
-
新しいデータモデルの概要では、API の仕組みをより明確に紹介することを目指しています。このドキュメントでは特に、YouTube が指標、ディメンション、フィルタを使用してレポートの値を計算する仕組みをわかりやすく解説します。
-
レポートの取得に使用する API の
reports.query
メソッドについて、個別に説明するようになりました。そのページの情報は、以前別のページに存在していた。新しいページは、レポートを取得するために送信する必要がある情報をより簡単に特定できるように設計されています。
-
-
新しい指標「
adEarnings
」には、Google 経由販売のすべての広告ソースからの推定総収益(純収益)が含まれます。コア指標ではありません。この API では、すでにearnings
指標をサポートしていたすべてのレポートで、adEarnings
指標がサポートされます。また、
earnings
指標の定義を修正しました。この指標には、Google が販売したすべての広告ソースと広告以外のソースからの総推定収益額が含まれるという事実が反映されています。以前の定義では、この指標には広告ソースからの収益しか含まれていないと誤って判断されていました。 -
primaryAdGrossRevenue
指標が非推奨になりました。代わりに、grossRevenue
指標を使用して収益データを取得してください。 -
サポートが終了した
primaryAdGrossRevenue
指標に加えて、広告パフォーマンス レポートでmonetizedPlaybacks
指標とplaybackBasedCpm
指標がサポートされなくなりました。ただし、一部の動画レポートでは、これらの指標が引き続きサポートされています。 -
API は、動画レポートに
videosAddedToPlaylists
とvideosRemovedFromPlaylists
の 2 つの新しい指標をサポートするようになりました。チャンネルとコンテンツ所有者の動画レポートのリストが更新され、新しい指標をサポートしているレポートが特定されました。videosAddedToPlaylists
– クエリの範囲内の動画が YouTube 再生リストに追加された回数。当該動画は、動画所有者の再生リストまたは他のチャンネルの再生リストに追加された可能性があります。videosRemovedFromPlaylists
– クエリの範囲内の動画が YouTube 再生リストから削除された回数。該当する動画は、動画所有者の再生リストまたは他のチャンネルの再生リストから削除された可能性があります。
どちらの指標にも、[後で見る] 再生リストなどのデフォルトの再生リストが含まれます。ただし、チャンネルのアップロード再生リストやユーザーの再生履歴など、動画が自動的に追加される再生リストはカウントされません。また、これらの指標には追加と削除の絶対数が反映されています。たとえば、ユーザーが再生リストに動画を追加し、削除してから再び追加した場合、指標は 2 つの再生リストに追加され、1 つの再生リストから削除されたことを示しています。
これらの指標では、2014 年 10 月 1 日以降のデータをご利用いただけます。
-
favoritesAdded
指標とfavoritesRemoved
指標は、今回の発表をもって非推奨となりました。これらはいずれも主な指標であり、利用規約で規定されている非推奨ポリシーの対象となります。 -
新しい
currency
パラメータを使用すると、収益指標を米ドル(USD
)以外の通貨で取得できます。このパラメータが設定されている場合、API はearnings
、grossRevenue
、playbackBasedCpm
、impressionBasedCpm
指標の値を指定された通貨に変換します。返される値は、日々変化する為替レートを使用して計算された推定値です。パラメータ値は 3 文字の ISO 4217 通貨コードです。デフォルト値は
USD
です。パラメータ定義には、サポートされている通貨コードのリストを指定します。 -
この API では、YouTube アナリティクス グループの作成と管理に加え、それらのグループのレポートデータを取得する機能がサポートされるようになりました。
-
グループの作成と管理
この更新により、グループの作成と管理を行うための
group
リソースとgroupItem
リソースが導入されます。group
リソースは、アナリティクス グループを表します。アナリティクス グループは、最大 200 個のチャンネル、動画、再生リスト、アセットで構成されるカスタム コレクションです。API は、このリソースに対してlist
、insert
、update
、delete
メソッドをサポートしています。groupItem
リソースは、アナリティクス グループ内のアイテムを表します。API は、このリソースに対してlist
、insert
、delete
の各メソッドをサポートしています。
たとえば、
groups.insert
メソッドを使用してグループを作成し、groupItems.insert
メソッドを使用してそのグループにアイテムを追加できます。 -
グループのレポートデータの取得
ディメンションに関するドキュメントが更新され、
group
ディメンションが追加されました。このディメンションは、多くのチャンネル レポートやコンテンツ所有者レポートでフィルタとして使用できます。group
フィルタを使用すると、API はそのグループ内のすべての項目のデータを返します。なお、この API では現在、アセット グループのレポートを作成する機能はサポートされていません。
YouTube アナリティクス グループについて詳しくは、YouTube ヘルプセンターをご覧ください。
-
-
API では、
show
ディメンションはサポートされなくなりました。 -
API で、
video
、playlist
、channel
、show
ディメンションをフィルタとして使用する場合に、これらのディメンションに複数の値を指定できるようになりました。複数の値を指定するには、filters
パラメータ値に、API レスポンスをフィルタする動画、再生リスト、チャンネル、または番組の ID のカンマ区切りのリストを設定します。パラメータ値には最大 200 個の ID を指定できます。同じフィルタに複数の値を指定した場合は、リクエストで指定するディメンションのリストにそのフィルタを追加することもできます。これは、特定のレポートでサポートされているディメンションとしてフィルタが記載されていない場合にも当てはまります。ディメンションのリストにフィルタを追加した場合、API はフィルタ値を使用して結果をグループ化します。
この機能の詳細については、
filters
パラメータの定義をご覧ください。 -
チャンネル レポートを取得する際に、
ids
パラメータの値をchannel==MINE
に設定することで、認証されたユーザーのチャンネルのデータを取得できるようになりました。(ids
パラメータをchannel==CHANNEL_ID
に設定して、指定したチャネルのデータを取得することもできます)。 -
API で再生リスト レポートがサポートされるようになりました。レポートには、再生リストに関連して発生した動画再生回数に関連する統計情報が含まれます。再生リストレポートは、チャンネルとコンテンツ所有者が閲覧できます。
すべての再生リスト レポートは、
views
指標とestimatedMinutesWatched
指標をサポートし、一部の再生リスト レポートはaverageViewDuration
指標もサポートしています。また、すべての再生リスト レポートで次の新しい指標がサポートされています。なお、これらの各指標にはウェブでの再生リストの視聴回数のみが反映されます。
playlistStarts
: 視聴者が再生リストの再生を開始した回数。viewsPerPlaylistStart
: 再生リストを再生するたびに発生した動画の平均視聴回数。averageTimeInPlaylist
: 再生リスト開始後に視聴者が再生リスト内の動画を視聴した推定平均時間(分単位)。
再生リスト レポートを取得するリクエストでは、
isCurated
フィルタを使用する必要があります。1
(isCurated==1
)に設定する必要があります。 -
API で視聴者維持率レポートがサポートされるようになりました。このレポートは、動画の視聴者維持率を測定したものです。レポートの新しい
elapsedVideoTimeRatio
ディメンションでは、動画の経過時間が対応する指標値に対して測定されます。-
audienceWatchRatio
指標は、動画内の特定のポイントで動画を視聴した視聴者の絶対比率を示します。この比率は、動画の一部が視聴された回数を、動画の合計視聴回数と比較して算出されます。1 回の動画視聴で、動画の一部が複数回(またはまったく視聴されない)場合もあります。たとえば、ユーザーが動画の同じ部分を巻き戻して複数回視聴した場合、その部分の絶対比は
1
より大きくなることがあります。 -
relativeRetentionPerformance
指標は、長さが同程度の他の YouTube 動画と比較した、再生中の視聴者維持率を示す指標です。値が 0 の場合、視聴者は長さが同程度の他のどの動画よりも維持率が低くなります。値が 1 の場合、他の長さの動画よりも視聴者維持率が高くなります。中央値が 0.5 の場合、同程度の長さの動画の半分は視聴者の維持率が高く、残りの半分は視聴者の維持率が低いことを示しています。
また、
audienceType
フィルタを使用して、オーガニック ビュー、TrueView インストリーム広告の視聴回数、または TrueView インディスプレイ広告の視聴回数に関連するデータのみをレポートに表示することもできます。(オーガニック ビューは、動画の検索や関連動画のクリックなど、ユーザー アクションによって直接生じる視聴回数です)。 -
-
API は、アノテーションに関連するいくつかの新しい指標をサポートしています。以下の指標は、これまで指標
annotationClickThroughRate
とannotationCloseRate
をサポートしていたレポートで取得できます。annotationImpressions
: アノテーションの合計インプレッション数。annotationClickableImpressions
: 表示されたアノテーションの数と、クリックが可能だったアノテーションの数。annotationClosableImpressions
: 表示されたアノテーションと、閉じることができるアノテーションの数。annotationClicks
: クリックされたアノテーションの合計数。annotationCloses
: 閉じたアノテーションの合計数。
新しい指標はすべてコア指標であり、非推奨ポリシーの対象となります。ただし、新しい指標のデータは 2013 年 7 月 16 日時点のものをご利用いただけます。(
annotationClickThroughRate
指標とannotationCloseRate
指標のデータは 2012 年 6 月 10 日以降に使用できます)。 -
GOOGLE_SEARCH
は、insightTrafficSourceType
ディメンションの個別の値としてレポートされなくなりました。代わりに、Google 検索結果からの参照はトラフィック ソースの種類「EXT_URL
」に分類されます。そのため、insightTrafficSourceType
フィルタをGOOGLE_SEARCH
に設定したinsightTrafficSourceDetail
レポートを取得することもできなくなります。 -
コンテンツ所有者レポートのドキュメントを更新し、コンテンツ所有者が申し立てまたはアップロードしたコンテンツについて、
subscribersGained
とsubscribersLost
の指標を取得できるようになりました。この変更は、コンテンツ所有者向けの最初の基本統計情報レポートで確認できます。現在は
claimedStatus
フィルタとuploaderType
フィルタがサポートされるようになりました。 -
サンプル リクエスト ドキュメントが再設計され、カテゴリ別にサンプルがグループ化されました。チャンネル レポートとコンテンツ所有者レポート用に最近リリースされたものと同様のタブ形式が使用されています。新しいデザインでは、例は次のカテゴリに分類されます。
- 基本統計情報
- 時間ベース
- 地域
- 再生場所
- トラフィック ソース
- 端末/ OS
- ユーザー属性
- ソーシャル
- 収益/広告(コンテンツ所有者レポートのみ)
-
サンプル リクエストのドキュメントでは、チャンネル レポートまたはコンテンツ所有者レポートのいずれかで、州ごとのデータを取得するための新しいサンプルを追加しました。
-
米国の州とワシントン D.C. の州別の指標: このレポートでは、チャンネルの動画について、州ごとの視聴回数やその他の統計情報が取得されます。データの対象は米国の州とワシントン D.C. です。この例では、
province
ディメンションを使用し、filters
パラメータを使用して、レスポンスに米国の結果のみが含まれるように制限しています。 -
カリフォルニア州の視聴者層(年齢層と性別): このレポートには、カリフォルニア州在住でチャンネルの動画を視聴したユーザーの年齢層と性別に関する統計情報が取得されます。コンテンツ所有者レポートの場合は、コンテンツ所有者が申し立てを行ったコンテンツについて、ユーザー属性と性別に関する統計情報が取得されます。この例では、
filters
パラメータを使用して、レスポンスに特定の都道府県のデータのみが含まれるようにします。
-
-
province
ディメンションの定義が更新され、dimensions
パラメータ値にprovince
が含まれている場合、リクエストでは、filters
パラメータ値にcountry==US
を含めることでデータを米国に限定しなければならないことに注意してください。 -
サポートされているチャンネル レポートとコンテンツ所有者レポートを一覧にしたドキュメントのデザインが一新されました。各ドキュメントでは、想定されるすべてのレポートを一覧表示した表ではなく、レポートをカテゴリ別にグループ化しています。
- 基本統計情報
- 時間ベース
- 地域
- 再生場所
- トラフィック ソース
- 端末/ OS
- ユーザー属性
- ソーシャル
- 人気の動画
各ドキュメントでは、これらのカテゴリがタブのリストとして表示されます。いずれかのタブをクリックすると、そのカテゴリでサポートされているレポートを表示できます。
-
API で 3 つの新しい地域ディメンション(
province
、continent
、subContinent
)がサポートされるようになりました。-
province
ディメンションを使用すると、米国の州とコロンビア特別区の統計情報を取得できます。API では、このディメンションを次の 2 つの用途で使用できます。-
API は、統計情報を状態ごとに分類する 2 つのレポートをサポートしています。どちらのレポートも、チャンネルとコンテンツ所有者が閲覧できます。
- 主要統計情報レポートには、視聴回数や推定再生時間(分)など、いくつかの統計情報が表示されます。
- 時間ベースのレポートでも同じ統計情報が表示されますが、データは日単位、7 日単位、30 日単位、月単位で集計されます。
-
filters
クエリ パラメータを使用すると、特定の州の統計情報のみがレポートに含まれるように制限できます。地域別レポート、再生場所レポート、トラフィック ソース レポート、デバイス レポート、オペレーティング システム レポート、ユーザー属性レポート、人気の動画レポートなど、いくつかのレポートがこうしたフィルタリングに対応しています。
-
-
continent
ディメンションでは、大陸を識別する国際連合(UN)統計地域コードを指定します。このディメンションはフィルタとしてのみ使用できます。 -
subContinent
ディメンションは、大陸の下位地域を識別する国連(UN)統計地域コードを指定します。このディメンションはフィルタとしてのみ使用できます。各小地域は 1 つの大陸にのみ関連付けられるため、
subContinent
フィルタを使用する場合は、continent
フィルタも使用する必要はありません。(実際に、リクエストで両方のディメンションを使用すると、API からエラーが返されます)。
-
-
insightTrafficSourceDetail
ディメンションに有効なフィルタ値としてinsightTrafficSourceType
値PROMOTED
が含まれないように、ドキュメントを修正しました。 -
YouTube Analytics API には、利用規約に記載されているサポート終了ポリシーが適用されるようになりました。ただし、API のコア以外のディメンションとコア以外の指標は、サポート終了ポリシーの対象になりません。ディメンションとmetricsのページを更新し、主要なディメンションと指標のリストを追加しました。また、主要なディメンションと指標を明確に識別できるよう、各ページの定義も更新されています。
-
API で
insightPlaybackLocationType
ディメンションの値としてEXTERNAL_APP
がサポートされるようになりました。今回のアップデートに伴い、2013 年 9 月 10 日以降、再生はMOBILE
の再生として分類されなくなりますが、この日付より前に発生したモバイルの再生は今後もその値で分類されます。今回のアップデートにより、モバイルでの再生は、再生が行われるアプリのタイプに応じて
WATCH
、EMBEDDED
、EXTERNAL_APP
のいずれかに分類されるようになりました。 -
API で
insightTrafficSourceType
ディメンションの値としてPLAYLIST
がサポートされるようになりました。この値は、動画再生が再生リストから参照されたことを示します。これまで、このような視聴はディメンションのYT_OTHER_PAGE
カテゴリを使って分類されていました。 -
複数の詳細分析と指標を基準としてレポートを並べ替えられるようになりました。この機能を説明する新しい例として、複数のディメンション/指標によるリクエストの並べ替えがサンプル リクエストのドキュメントに追加されています。リクエストはトラフィック ソース データを取得します。
sort
パラメータ値はday,-views
です。結果は時系列順に並べ替えられますが、各日の結果セット内では最初の行に最も多くの再生回数を生成したトラフィック ソースのデータが含まれ、2 番目の行にはその次に多くの再生回数を生成したソースのデータが含まれる、というように続きます。 -
この API では、
deviceType
とoperatingSystem
という 2 つの新しいディメンションがサポートされるようになりました。これらのディメンションを使用して、視聴者が動画を視聴しているデバイスに関するデータを取得できます。API がサポートするのは、いずれかまたは両方のディメンションを使用するレポートです。-
deviceType
レポートでは、パソコン、モバイル、タブレットなど、さまざまな種類のデバイスの視聴回数と推定総再生時間を確認できます。また、operatingSystem
フィルタを使用して、特定のオペレーティング システム(Android や iOS など)を実行しているデバイスの統計情報のみが含まれるように、デバイスタイプのレポートを制限することもできます。 -
operatingSystem
レポートでは、Android、iOS、Linux などのさまざまなオペレーティング システムについて、視聴回数と推定総再生時間を取得できます。また、deviceType
フィルタを使用して、特定の種類のデバイス(モバイル デバイスやタブレットなど)の統計情報のみがオペレーティング システムのレポートに含まれるように制限することもできます。
新しく追加された端末タイプおよびオペレーティング システムのレポートは、チャンネルおよびコンテンツ所有者に対してのみ使用可能です。
-
-
サンプル リクエストのドキュメントを更新し、チャンネルとコンテンツ所有者について、それぞれ 3 種類の端末レポートを追加しています。
-
insightPlaybackLocationType
ディメンションは、値YT_OTHER
を返すことがあります。この値は、ディメンションの他の値のいずれかを使用して分類されていないビューを表します。 -
コンテンツ所有者レポートのドキュメントを更新し、人気の動画レポートを収益の降順で並べ替えられることを反映しています。これにより、最も収益の高い動画を特定することができます。このレポートは、[ユーザー アクティビティと収益のレポート] セクションの 2 番目の表に記載されている最初のレポートです。
-
YouTube では、試験的な API の機能とサービスを識別しなくなりました。代わりに、サポート終了予定ポリシーの対象となる YouTube API のリストを提供しています。
-
この API では、視聴に関する指標、エンゲージメント指標、収益指標、広告のパフォーマンス指標と併せて、総再生時間の指標(
estimatedMinutesWatched
、averageViewDuration
、averageViewPercentage
)を取得できるようになりました。この変更を反映して、使用可能なチャンネル レポートおよびコンテンツ所有者レポートのリストを更新しています(再生時間の指標はリストに示されている他のレポートの一部として取得できるため、実際にはリストが縮小されています)。
サンプルの API リクエストのドキュメントも更新しています。
-
insightPlaybackLocationDetail
およびinsightTrafficSourceDetail
ディメンションを使用するレポートは、次の点において拡張されています。-
オプションの
country
フィルタがサポートされるようになりました。 -
コンテンツ所有者は、次のいずれかの新しい
filter
の組み合わせを使用して、これらのレポートを取得できるようになりました。これらの組み合わせはすべて、オプションのcountry
フィルタもサポートしています。-
再生場所の詳細
channel,insightPlaybackLocationType==EMBEDDED
show,insightPlaybackLocationType==EMBEDDED
claimedStatus,insightPlaybackLocationType==EMBEDDED
uploaderType,insightPlaybackLocationType==EMBEDDED
uploaderType,claimedStatus,insightPlaybackLocationType==EMBEDDED
-
トラフィック ソースの詳細
channel,insightTrafficSourceType
show,insightTrafficSourceType
claimedStatus,insightTrafficSourceType
uploaderType,insightTrafficSourceType
uploaderType,claimedStatus,insightTrafficSourceType
-
-
-
新しいサンプル API リクエストのドキュメントでは、YouTube Analytics API を使用してさまざまな種類のレポートを取得する方法の例を紹介しています。それぞれの例には、リクエストが取得するレポートの簡単な説明が含まれ、リクエストのディメンション、指標、フィルタ、並べ替えのパラメータが表示されます。
-
insightTrafficSourceType
ディメンションで、有効な値としてSUBSCRIBER
がサポートされるようになりました。この値は、動画再生が YouTube トップページ上のフィードから参照されたのか、YouTube のチャンネル登録機能から参照されたのかを識別します。このトラフィック ソースに基づいてフィルタした場合、insightTrafficSourceDetail
フィールドには、トップページ フィードなど、視聴の参照元となったページが特定されます。 -
この API で、
annotationClickThroughRate
とannotationCloseRate
という 2 つの新しい指標がサポートされるようになりました。これらの指標は、動画中に表示されるアノテーションに対する視聴者の操作に関するものです。チャンネル レポートとコンテンツ所有者レポートのリストが更新され、新しい指標をサポートしているレポートが区別されるようになりました。annotationClickThroughRate
– クリック可能なアノテーションの合計表示回数のうち、視聴者がクリックしたアノテーションの割合。annotationCloseRate
– アノテーションの合計インプレッション数のうち、視聴者が閉じたアノテーションの割合。
-
収益の指標と広告の掲載結果の指標に加え、新しい広告の掲載結果レポートをサポートするようになりました。これらの指標とレポートにアクセスできるのは、YouTube パートナー プログラムに参加している YouTube コンテンツ パートナーだけです。
-
新しくサポートされたレポートでは、再生回数ベースの広告の掲載結果の指標と表示回数ベースの広告の掲載結果の指標をサポートしています。広告の掲載結果レポートの詳細については、コンテンツ所有者レポートのドキュメントを参照してください。
-
新しくサポートされた指標は、以下のリストに示すとおりです。コンテンツ所有者レポートは、新しい 2 つのレポートなど、これらの指標をサポートするレポートを識別するように更新されています。
earnings
– Google が販売したすべての広告ソースからの推定総収益。grossRevenue
– Google パートナーまたは DoubleClick パートナーからの推定総収益。primaryAdGrossRevenue
– レポートの対象となる動画再生について、メインの広告タイプ別に集計および分類された Google または DoubleClick パートナーからの推定総収益。monetizedPlaybacks
– 少なくとも 1 つの広告インプレッションが表示された再生回数。playbackBasedCpm
– 再生回数 1,000 回あたりの推定総収益。impressions
– 配信された確認済みの広告インプレッションの数。impressionBasedCpm
– 広告インプレッション 1,000 回あたりの推定総収益。
注: 詳細については、指標の定義を参照してください。
-
収益や広告の掲載結果の指標を取得するリクエストでは、新しい
https://www.googleapis.com/auth/yt-analytics-monetary.readonly
スコープを使用してアクセス権を付与する認証トークンを送信する必要があります。
-
-
各タイプのレポートを個別のページで説明するように API ドキュメントを再構成しました。そのため、各タイプのチャンネル レポートとコンテンツ所有者レポートは、それぞれ個別のページで説明しされています。
-
API のリファレンス ガイドに、例のセクションを追加しました。このセクションには、Java、JavaScript、Python、Ruby の各クライアント ライブラリを使用して API を呼び出す方法を示したコード サンプルが掲載されています。JavaScript のコードサンプルは、サンプル アプリケーションのドキュメントで詳しく説明しているものと同じです。
-
API リファレンス ガイドに APIs Explorer が導入され、API の呼び出し、API リクエストの確認、レスポンスの実際のデータの取得が可能になりました。
-
チャンネルとコンテンツ所有者の両方について、新しい複数のレポートをサポートしています。これらのレポートについては、以下で説明します。各レポートは、チャンネル レポートまたはコンテンツ所有者レポートとして使用できます。それに応じてディメンションとmetricsのページも更新されました。
-
再生場所レポートは、各タイプのページまたはアプリケーションで発生した動画再生数を示します。
-
再生場所の詳細レポートは、指定した動画について最も多くの再生回数を生成した埋め込み動画プレーヤーを示します。このレポートでは再生回数上位の埋め込み動画プレーヤーに関連付けられた URL が特定されるため、再生場所レポートよりも詳細なデータが示されます。
-
トラフィック ソース レポートは、各タイプの参照元から発生した動画再生数を示します。
-
トラフィック ソースの詳細レポートは、指定した動画と指定したトラフィック ソースのタイプについて最も多くの再生回数を生成した参照元を示します。たとえば、このレポートを使用することで、指定した動画に最も多くのトラフィックを送信した動画を特定することができます。このレポートは、複数のトラフィック ソースに対してサポートされています。
-
再生時間レポートは、視聴者がコンテンツの視聴に費やした合計時間を示します。このレポートでは、特定の期間(1 日、過去 7 日間、過去 30 日間など)または国のデータを集計できます。日または国のいずれかでデータを集計する場合は、ユーザーが視聴した各動画の平均長と各動画の平均再生率も示されます。
-
-
YouTube Analytics API をすべてのデベロッパーが利用できるようになりました。プロジェクトの API は、最初にアクセスをリクエストしなくても、APIs console の [サービス] パネルから有効にできます。
-
新しいスタートガイド セクションでは、YouTube Analytics API を使用するアプリケーションを構築するための前提条件と基本的な手順について概説しています。
-
新しいクォータの使用方法についてのセクションには、API クォータの使用量を最適化するガイドラインが掲載されています。API サーバーは各リクエストのクエリ コストを計算し、そのコストが API 使用量クォータから減算されます。クエリ コストはレポートのタイプによって大幅に異なるため、効率的にクォータを使用するように計画する必要があります。アプリケーションは、実際に必要な指標とデータだけをリクエストするように作成してください。
-
時間ディメンションのセクションを更新し、このようなディメンションによって、アナリティクス レポートでは期間に基づいてデータが集計されることを説明しています。API は、以下の時間ディメンションをサポートしています。
7DayTotals
– レポートのデータは、各行に 7 日間のデータが含まれるように集計されます。30DayTotals
– 各行に 30 日間のデータが含まれるように、レポートのデータが集計されます。month
– レポートのデータが月ごとに集計されます。
同様に、使用可能なレポートのセクションを更新し、このようなディメンションを使用するレポートに対する API のサポートを反映しています。
-
レポート エンティティ ディメンションのセクションを更新し、コンテンツ所有者レポートを取得する API リクエストでは、これらのディメンション(
video
、channel
、show
)のいずれか、またはサポートされているclaimedStatus
およびuploaderType
ディメンションの組み合わせを使用してデータをフィルタリングする必要があることを記載しました。 -
人気の動画レポートで、新しい 2 つの並べ替えオプションがサポートされるようになりました。これらのレポートはチャンネル レポートまたはコンテンツ所有者レポートとして使用可能であり、国別の指標(再生回数、コメント数、評価数など)が含まれています。また、このような指標が動画別に分類されています。これらのレポートは、動画再生ページに登録したユーザー数または登録解除したユーザー数に基づいて並べ替えられるようになりました。
-
subscribersGained
とsubscribersLost
のmetricsの定義を更新し、動画再生ページ、チャンネル ページ、YouTube ホームページに表示されるガイドなど、複数の場所でチャンネル登録者数の増減が可能であることを説明しました。これらの指標を動画専用のレポートで表示した場合、そのレポートには、指定した動画の再生ページの統計情報だけが含まれます。
YouTube Reporting API では、3 つの新しい終了画面レポートと、これらのレポート用の新しいディメンションと指標がサポートされています。このレポートには、動画の再生が停止した後に表示される終了画面のインプレッションとクリックスルーの統計情報が記載されます。
動画に終了画面を追加する方法について詳しくは、YouTube ヘルプセンターをご覧ください。
2016 年 11 月 8 日
この更新には、YouTube Analytics API に対する次の変更が含まれます。
2016 年 10 月 27 日
YouTube Studio の [レポート] セクションのレポートへのアクセス権を持つコンテンツ所有者に対しては、システムが管理する一連の広告収益レポートが自動的に生成されるようになりました。新しいシステム管理 API レポートは、手動でダウンロードできるクリエイター ツール レポートでも利用できるデータにプログラムからアクセスできるようにすることを目的としています。
システム管理レポートの概要では、新しいレポートの概要と、API を使用してレポートを取得するプロセスについて説明しています。このプロセスは、YouTube アナリティクスの一括レポートを取得する場合とは若干異なります。これは、パートナーはレポートを生成するためのジョブをスケジュールする必要がないためです。
reportType
リソースの id
プロパティが更新され、API を介してアクセスできるシステム管理レポートのリストが追加されました。
2016 年 9 月 27 日
注: これはサポート終了のお知らせです。
YouTube Analytics API の uniques
指標が非推奨になりました。これは主要な指標ではなく、2016 年 10 月 31 日までサポートされます。
2016 年 9 月 15 日
この更新には、YouTube Reporting API に関する次の変更が含まれます。
2016 年 8 月 19 日
このアップデートには、YouTube Reporting API に関する次の変更が含まれます。
2016 年 8 月 11 日
この改訂での変更内容は次のとおりです。
2016 年 8 月 10 日
このアップデートには、次の変更が含まれます。
2016 年 7 月 18 日
このアップデートには、次の変更が含まれます。
2016 年 6 月 28 日
YouTube Analytics API のドキュメントが更新され、多数のチャンネル レポートとコンテンツ所有者レポートでカード指標がサポートされるようになりました。新たにサポートされる指標は次のとおりです。
この指標は、次のタイプのレポートで使用できます。
2016 年 6 月 22 日
この更新には、YouTube Reporting API に関する次の変更が含まれます。最初の変更は API 全般に関するものであり、残りの変更はコンテンツ所有者レポートにのみ影響します。
2016 年 5 月 19 日
この更新には、YouTube Reporting API に関する次の変更が含まれます。
2016 年 4 月 12 日
この更新には以下の変更が含まれます。これらの変更はすべて、YouTube Reporting API にのみ影響します。
2016 年 3 月 28 日
YouTube Reporting API と YouTube Analytics API で、いくつかの追加共有サービスの視聴統計情報が返されるようになりました。
2016 年 3 月 16 日
このアップデートには、YouTube Reporting API と YouTube Analytics API の両方に影響する次の変更が含まれます。
YouTube Reporting API
YouTube Analytics API
2016 年 2 月 8 日
YouTube Analytics API でサポートされている指標のリストが更新され、カード指標はその API でサポートされている指標として表示されなくなりました。(この API のレポートはすべて、カード指標をサポートするものとして文書化されていません)。
なお、YouTube Reporting API を使用してカード指標を取得することは可能です。この API は、多数のチャンネル レポートやコンテンツ所有者レポートでこれらの指標をサポートしています。
2016 年 1 月 6 日
YouTube Reporting API と YouTube Analytics API はどちらも、Chromecast デバイスで発生した視聴を明確に識別できるようになりました。
2015 年 12 月 21 日
ドキュメントでは、annotation_clickable_impressions
指標と annotation_closable_impressions
指標の名前が、レポートで返される名前に合わせて更新されました。以前は、名前は clickable_annotation_impressions
と closable_annotation_impressions
とドキュメント化されていました。
2015 年 12 月 18 日
欧州連合(EU)の法律により、EU のエンドユーザーに対して特定の開示を行い、エンドユーザーから同意を得ることが義務付けられています。そのため、欧州連合のエンドユーザーに対しては、EU ユーザーの同意ポリシーに準拠する必要があります。YouTube API 利用規約に、この要件に関するお知らせを追加しました。
2015 年 12 月 15 日
このアップデートには、次の変更が含まれます。これらはすべて YouTube Analytics API に影響します。
2015 年 11 月 10 日
この改訂での変更内容は次のとおりです。
2015 年 10 月 29 日
この改訂での変更内容は次のとおりです。
2015 年 10 月 8 日
この改訂での変更内容は次のとおりです。
2015 年 9 月 24 日
この改訂での変更内容は次のとおりです。
2015 年 8 月 20 日
この改訂での変更内容は次のとおりです。
2015 年 7 月 22 日
このアップデートには複数の変更が含まれますが、いずれもコンテンツ所有者のみに適用されます。
2015 年 6 月 1 日
この改訂での変更内容は次のとおりです。
2015 年 3 月 31 日
この改訂での変更内容は次のとおりです。
2015 年 3 月 16 日
この改訂での変更内容は次のとおりです。
2015 年 2 月 25 日
この改訂での変更内容は次のとおりです。
2015 年 2 月 13 日
この改訂での変更内容は次のとおりです。
2014 年 8 月 28 日
この改訂での変更内容は次のとおりです。
2014 年 7 月 16 日
この改訂での変更内容は次のとおりです。
2014 年 1 月 31 日
この改訂での変更内容は次のとおりです。
2014 年 1 月 16 日
この改訂での変更内容は次のとおりです。
2014 年 1 月 6 日
この改訂での変更内容は次のとおりです。
2013 年 9 月 30 日
この改訂での変更内容は次のとおりです。
2013 年 7 月 16 日
この改訂での変更内容は次のとおりです。
May 23, 2013 年 5 月 23 日
この改訂での変更内容は次のとおりです。
2013 年 5 月 10 日
この改訂での変更内容は次のとおりです。
2013 年 5 月 6 日
この改訂での変更内容は次のとおりです。
2013 年 5 月 3 日
この改訂での変更内容は次のとおりです。
2013 年 3 月 28 日
この改訂での変更内容は次のとおりです。
2013 年 3 月 21 日
この改訂での変更内容は次のとおりです。
2013 年 2 月 4 日
この改訂での変更内容は次のとおりです。
2012 年 11 月 14 日
この改訂での変更内容は次のとおりです。
2012 年 10 月 2 日
この改訂での変更内容は次のとおりです。
2012 年 9 月 12 日
この改訂での変更内容は次のとおりです。