Dimensions

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このドキュメントでは、YouTube Analytics API でサポートされているディメンションを定義します。この API は、ターゲットを絞り込んだリアルタイム クエリに対応し、カスタムの YouTube アナリティクス レポートを生成できます。

ディメンションは、データの集計に使用される一般的な条件です（ユーザー アクティビティが発生した日付や、ユーザーが所在する国など）。

各クエリ レポートには、サポートされているディメンションが示されています。たとえば、時間別にユーザー アクティビティを取得する場合は、データのレポート対象期間（日または月）を選択します。どのレポートでも、データの各行にはディメンション値の一意の組み合わせがあります。

クエリ レポートを取得するには、YouTube Analytics API の reports.query メソッドを呼び出します。リクエストで dimensions パラメータを使用して、レポートの指標値の計算に YouTube が使用するディメンションを指定します。

主要なディメンション

YouTube Analytics API は、利用規約で定義されている非推奨ポリシーの対象となりますが、コア以外のディメンション（およびコア以外の指標）はポリシーの対象外です。このページの定義では、コア ディメンションであるディメンションは明示的に識別されます。

次のリストに、API のコア ディメンションを示します。

• ageGroup
• channel
• country
• day
• gender
• month
• sharingService
• uploaderType
• video

詳細については、非推奨ポリシーが適用される YouTube API のリストをご覧ください。

フィルタ

すべてのクエリ レポートでフィルタがサポートされています。フィルタは、取得したデータセットに存在する必要があるディメンション値を特定します。そのため、特定の値または値のセットに一致するデータのみが API レスポンスに含まれるように制限されます。たとえば、すべての国のユーザー アクティビティ指標を取得するのではなく、フィルタを使用して特定の国のデータのみを取得できます。

クエリ レポートを取得するリクエストでは、省略可能な filters リクエスト パラメータで、データをフィルタするディメンション値を指定します。たとえば、ヨーロッパのユーザー アクティビティ指標を取得するには、filters パラメータの値を continent==150 に設定します。

重要: コンテンツ所有者レポートを取得する API リクエストでは、レポート対象エンティティのディメンションのいずれかを使用するか、claimedStatus ディメンションと uploaderType ディメンションのサポートされている組み合わせを使用してデータをフィルタする必要があります。

ディメンション

以降のセクションでは、YouTube Analytics API のクエリ レポートで使用されるディメンションを定義します。特に明記されていない限り、これらのディメンションはチャンネル レポートとコンテンツ所有者レポートの両方で使用されます。フィルタとしてのみ使用できるディメンションも識別されます。

リソース

これらのディメンションは、チャンネルとコンテンツ所有者が YouTube で管理するリソースに対応しています。

• video
• playlist
• channel
• group

注: この API では、video、playlist、channel ディメンションをフィルタとして使用するときに、複数の値を指定できます。これを行うには、filters パラメータの値を、API レスポンスのフィルタ対象となる動画 ID、再生リスト ID、チャンネル ID のカンマ区切りリストに設定します。パラメータ値には、最大 500 個の ID を指定できます。

動画 （コア ディメンション）

YouTube 動画の ID。YouTube Data API では、これは video リソースの id プロパティの値です。This is a core dimension and is subject to the Deprecation Policy.

再生リスト

YouTube 再生リストの ID。YouTube Data API では、これは playlist リソースの id プロパティの値です。

channel（コア ディメンション）（コンテンツ所有者のレポートでのみ使用）

YouTube チャンネルの ID。YouTube Data API では、これは channel リソースの id プロパティの値です。This is a core dimension and is subject to the Deprecation Policy.

channel ディメンションは、コンテンツ所有者レポートでよく使用されます。これらのレポートでは通常、複数のチャンネルのデータが集計されるためです。

group（フィルタのみ）

YouTube アナリティクス グループの ID。この値は、YouTube Analytics API の groups.list メソッドを使用して取得できます。group フィルタを使用すると、API レスポンスには、そのグループ内のすべての動画、再生リスト、チャンネルのデータが含まれます。

例

次のサンプル リクエストでは、レポート エンティティのディメンションまたはフィルタを使用しています。

• チャンネルの例

  • 基本統計情報
    • トップ 10 – チャンネル内で最も視聴された動画
    • 上位 10 件 - チャンネルで最も視聴された動画のアノテーションのクリック率
    • 特定の再生リストの統計情報
    • トップ 10 - チャンネルで最も視聴された再生リスト
  • 地域
    • トップ 10 – 特定の国における再生回数が多い動画
    • トップ 10 - ヨーロッパで最も視聴された動画

• コンテンツ所有者の例

  • 基本統計情報
    • 上位 10 件 - コンテンツ所有者の視聴回数が最も多い動画
    • 上位 10 件 - コンテンツ所有者の視聴回数が最も多い動画
    • 上位 10 件 - コンテンツ所有者のチャンネルで最も視聴された動画
    • 上位 10 件 - チャンネルで最も視聴された動画のアノテーションのクリック率
    • 上位 10 件 - コンテンツ所有者の再生回数が最も多い再生リスト
  • 地域
    • トップ 10 - コンテンツ所有者のヨーロッパでの視聴回数が最も多い動画
    • トップ 10 - 米国で最も再生された再生リスト

地理的エリア

これらのディメンションは、ユーザー アクティビティ、広告のパフォーマンス、推定収益の指標に関連付けられた地域を特定します。

country（コア ディメンション）

レポートの行の指標に関連付けられている国。ディメンションの値は、US、CN（中国）、FR（フランス）などの 2 文字の ISO-3166-1 国コードです。国コード ZZ は、YouTube が関連する国を特定できなかった指標を報告するために使用されます。This is a core dimension and is subject to the Deprecation Policy.

province

レポートの行の指標に関連付けられている米国の州または地域。ディメンションの値は、米国の州またはコロンビア特別区を識別する ISO 3166-2 コードです（US-MI（ミシガン）や US-TX（テキサス）など）。州コード US-ZZ は、YouTube が関連する米国の州を特定できなかった指標を報告するために使用されます。API リクエストの dimensions パラメータ値に province が含まれている場合は、filters パラメータ値に country==US を含めて、データを米国に限定する必要があります。

注: このディメンションは、米国の離島を識別する ISO 3166-2 値をサポートしていません。これらの地域には独自の ISO 3166-1 国コードもあります。また、米国以外の国の行政区画もサポートされていません。

dma

Nielsen がデータ行に記載されている視聴イベントに関連付けられた指定マーケット エリア（DMA）を識別するために使用する 3 桁の識別子。

city

レポートの行の指標に関連付けられている推定都市。このディメンションのデータは、2022 年 1 月 1 日以降の日付について使用できます。

continent（フィルタのみ）

国連（UN）統計地域コード。この API は、次の値をサポートしています。

値
002	アフリカ
019	南北アメリカ（北米、ラテンアメリカ、南米、カリブ海地域）
142	アジア
150	ヨーロッパ
009	オセアニア

このディメンションは、データのフィルタリングにのみ使用できます。このディメンションを使用するには、filters パラメータの値を continent==REGION_CODE に設定し、表の REGION_CODE 値を指定します。

subContinent（フィルタのみ）

地理的サブリージョンを識別する国連統計地域コード。国連統計局には、サブリージョンと、各リージョンに関連付けられている国がリストされています。

サポートされているサブリージョンのリストを表示します。

値	地域	亜地域
014	アフリカ	アフリカ大陸東部
017	アフリカ	アフリカ大陸中央部
015	アフリカ	アフリカ大陸北部
018	アフリカ	アフリカ大陸南部
011	アフリカ	アフリカ大陸西部
029	南北アメリカ	カリブ諸国系
013	南北アメリカ	中米
021	南北アメリカ	北アメリカ
005	南北アメリカ	南アメリカ
143	アジア	中央アジア
030	アジア	東アジア
034	アジア	南アジア
035	アジア	東南アジア
145	アジア	西アジア
151	ヨーロッパ	東欧
154	ヨーロッパ	北ヨーロッパ
039	ヨーロッパ	南ヨーロッパ
155	ヨーロッパ	西ヨーロッパ
053	オセアニア	オーストラリア、ニュージーランド
054	オセアニア	メラネシア
057	オセアニア	ミクロネシア
061	オセアニア	ポリネシア

このディメンションは、データのフィルタリングにのみ使用できます。このディメンションを使用するには、filters パラメータの値を subContinent==REGION_CODE に設定し、UN リストの REGION_CODE 値を指定します。

例

次のサンプル リクエストでは、地域のディメンションまたはフィルタを使用しています。

• チャンネルの例

  • 基本統計情報: チャンネルの国別の視聴回数など
  • 地域
    • チャンネルの動画の国別再生時間の指標
    • チャンネルの動画のアノテーションに関する国別の指標
    • 米国の州とワシントン DC の州固有の指標
    • チャンネルの再生リストの国別の総再生時間の指標
    • トップ 10 - 米国で最も再生された再生リスト
  • 再生場所: さまざまな再生場所での 1 日あたりの視聴回数と総再生時間
  • トラフィック ソース: 国内のさまざまなトラフィック ソースからの視聴回数と総再生時間
  • ユーザー属性: カリフォルニア州の視聴者のユーザー属性（年齢層と性別）
  • 人気の動画
    • トップ 10 – 特定の国における再生回数が多い動画
    • トップ 10 - ヨーロッパで最も視聴された動画

• コンテンツ所有者の例

  • 基本統計情報: 自分でアップロードしたすべての動画の国別の視聴回数など
  • 地域
    • 自身がアップロードしたコンテンツの国別再生時間の指標
    • 自身がアップロードしたコンテンツのアノテーションに関する国別の指標
    • 米国の州とワシントン DC の州固有の指標
    • コンテンツ所有者のプレイリストの国別の総再生時間の指標
    • トップ 10 - 米国で最も再生された再生リスト
  • 再生場所: さまざまな再生場所での 1 日の視聴回数と総再生時間
  • ユーザー属性: カリフォルニア州の視聴者のユーザー属性（年齢層と性別）
  • 人気の動画: トップ 10 - コンテンツ所有者のヨーロッパでの視聴回数上位の動画
  • 収益/広告のパフォーマンス: 国別の収益と広告のパフォーマンス指標

期間

これらのディメンションは、レポートで期間（日、週、月など）に基づいてデータを集計することを示します。startDate と endDate のリクエスト パラメータは、レポートにデータが含まれる期間を指定します。ただし、レポートで実際に返されるデータは、クエリが実行された時点でリクエストで指定されたすべての指標が利用可能な最終日までのものです。レポートでは、日付は YYYY-MM-DD 形式で表示されます。

重要: すべての日付は、太平洋時間（UTC-7 または UTC-8）の午前 0 時から、指定した日付、月、年の午後 11 時 59 分までの期間を指します。そのため、夏時間に合わせて時計が進められる日付は 23 時間の期間を表し、時計が遅められる日付は 25 時間の期間を表します。

[月] ディメンションは、指定した月と年の 1 日目の午前 0 時（太平洋時間（UTC-7 または UTC-8））から始まる期間を表します。

日 （コア ディメンション）

このディメンションを使用すると、レポート内のデータは日単位で集計され、各行には 1 日分のデータが含まれます。他のディメンションを使用して、データをさらに細かく分類することもできます。たとえば、トラフィック ソース レポートでは、ユーザーが動画にアクセスした方法に基づいて 1 日の視聴統計情報を集計できます。This is a core dimension and is subject to the Deprecation Policy.

月 （コア ディメンション）

レポートのデータは暦月ごとに集計されます。日次レポートと同様、他のフィルタを使用してデータをさらに細かく分類することができます。レポートの日付は YYYY-MM 形式で表示されます。

注: API クエリで month ディメンションを使用する場合は、start-date パラメータと end-date パラメータの両方を 1 日目に設定する必要があります。This is a core dimension and is subject to the Deprecation Policy.

例

次のサンプル リクエストでは、時間ディメンションまたはフィルタを使用しています。

• チャンネルの例

  • 時間ベース
    • チャンネルの動画の日別再生時間の指標
    • チャンネルの動画のアノテーションに関する日別の指標
    • チャンネルの 1 日の再生リスト視聴回数
  • 再生場所: さまざまな再生場所での 1 日あたりの視聴回数と総再生時間
  • トラフィック ソース: さまざまなトラフィック ソースからの 1 日あたりの視聴回数と総再生時間
  • デバイス/OS
    • Android オペレーティング システムの端末のタイプに関する日別の指標
    • 携帯端末のオペレーティング システムに関する日別の指標
    • オペレーティング システムと端末のタイプに関する日別の指標

• コンテンツ所有者の例

  • 時間ベース
    • 自身がアップロードしたコンテンツの日別再生時間の指標
    • 申し立てが行われたコンテンツのアノテーションに関する指標
    • コンテンツ所有者の 1 日の再生リストの視聴回数
  • 再生場所: さまざまな再生場所での 1 日あたりの視聴回数と総再生時間
  • トラフィック ソース: さまざまなトラフィック ソースからの 1 日あたりの視聴回数と総再生時間
  • デバイス/OS
    • 申し立てが行われた動画の端末のタイプに関する日別の指標
    • 申し立てが行われた動画が携帯端末で再生されたときのオペレーティング システムに関する日別の指標
    • オペレーティング システムと端末のタイプに関する日別の指標
  • 収益/広告のパフォーマンス: 1 日あたりの収益と広告のパフォーマンスに関する指標

再生場所

これらのディメンションでは、ユーザー アクティビティが発生したページまたはアプリに関する分析情報を確認できます。

insightPlaybackLocationType

レポートのデータは、動画の再生が発生したページまたはアプリの種類に基づいて集計されます。このディメンションの値は次のとおりです。

• BROWSE - YouTube のホームページまたはホーム画面、ユーザーのチャンネル登録フィード、または YouTube の他のブラウジング機能で行われた視聴を表すデータです。

• CHANNEL - チャンネル ページで発生した視聴回数を示すデータ。

• EMBEDDED -