このページは Cloud Translation API によって翻訳されました。

API リクエストのサンプル

このページでは、YouTube Data API に対するリクエストのサンプルを示します。YouTube Data API を使用して、動画、チャンネル、再生リストなどの YouTube リソースを取得、操作します。各サンプルは、Google APIs Explorer にリンクしてデータを入力するので、サンプルを実行してレスポンスを確認できます。

YouTube Data API を使用したコンテンツのアップロードについては、再開可能なアップロードをご覧ください。

概要

わかりやすくするために、このページのサンプルでは、各リクエストの特徴的な要素を示し、Data API リクエストを処理するホストのベース URL（https://www.googleapis.com/youtube/v3）を短縮しています。サンプルのコンテキスト外でリクエストを行うには、完全な URL を含める必要があります。

以下は、このページに表示されるサンプルリクエストの例です。

GET {base-URL}/channels?part=contentDetails
                       &mine=true

このリクエストの完全な URL は次のようになります。

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

一部のリクエストでは、チャンネル登録者のリストなど、YouTube チャンネルの所有者のみがアクセスできるデータを取得します。このリクエストには、チャンネル所有者が Google Data Explorer に YouTube Data API リクエストの実行権限を付与する必要があります。（非公開チャンネルデータへのアクセスを承認する方法について詳しくは、OAuth 2.0 認証を実装するをご覧ください）。APIs Explorer にリンクしたら、[OAuth 2.0 を使用してリクエストを承認する] ボタンをクリックします。この手順では、API Explorer が所有者に代わってリクエストを承認できるようにします。また、承認の範囲を選択して、API Explorer が実行できるリクエストの種類を指定します。

各リクエストに対するレスポンスは、YouTube リソースの JSON 表現です。リクエストの part パラメータは、リソースのどの部分をレスポンスに含めるかを指定します。このパラメータでは、レスポンスに含める必要がある 1 つ以上のトップレベル（ネストされていない）リソースプロパティを識別します。たとえば、video リソースの一部は次のようになります。

スニペット
contentDetails
プレーヤー
statistics
status

これらのパーツはすべて、ネストされたプロパティを含むオブジェクトであり、API サーバーが取得する（または取得しない）メタデータフィールドのグループと考えることができます。そのため、part パラメータでは、アプリが実際に使用するリソースコンポーネントを選択する必要があります。詳しくは、YouTube Data API スタートガイドをご覧ください。

チャンネル情報を取得する

このリクエストでは、channels.list メソッドを使用して、認証済みユーザーに属するチャネルの詳細を取得します。

GET {base_URL}/channels?part=contentDetails
                       &mine=true

このリクエストへのレスポンスには、チャンネル ID と、認証済みユーザーのチャンネルのcontentDetailsが含まれます。contentDetails には、チャンネルに関連付けられた複数のシステム生成プレイリストが含まれます。それ以降のリクエストの多くは、チャンネル ID またはいずれかの再生リスト ID を必要とするため、記録することが重要です。

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

アップロード済みの動画と自動生成された再生リスト

アップロードされたすべての動画は、チャンネルに関連付けられている再生リストに追加されます。アップロードされた動画のリストを取得するには、上記のチャンネル情報のレスポンスで返された「uploads」プレイリストをクエリし、playlistItems.list メソッドを使用してその再生リスト内の動画を取得します。

Google APIs Explorer で次のサンプルリクエストを実行する前に、{UPLOADS_PLAYLIST_ID} を前のリクエストのプレイリスト ID に置き換えます。

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

返された各アイテムの "id" 値はプレイリストのアイテム ID です。プレイリストアイテムの動画 ID は contentDetails 部分の videoId です。

チャンネル情報レスポンスの対応する再生リスト ID に置き換えると、上記のリクエストを使用してユーザーのお気に入り、高評価、再生履歴、後で見るリストを取得できます。

ユーザーが作成した再生リスト

このリクエストでは playlists.list メソッドを使用して、認証済みチャンネルに関連付けられている再生リストを取得します。このリクエストでは、チャンネル情報（アップロード、watchHistory など）に含まれるシステム生成の再生リストは取得されませんのでご注意ください。ユーザーが作成したプレイリストのみを取得します。

GET {base_URL}/playlists?part=snippet
                        &mine=true

プレイリスト ID を取得したら、前のセクションのリクエストでプレイリストのアイテムを取得できます。

チャンネルの公開再生リストに関する情報は、認証なしでリクエストできます。未認証のリクエストを送信するときは、そのリクエストを行うアプリケーションの一意の API キーを指定する key 引数を含める必要があります。たとえば、このリクエストは GoogleDevelopers チャンネルに関連付けられているプレイリストを取得します。

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

サブスクリプションの取得

subscription リソースは、YouTube ユーザー（チャンネル登録者）とチャンネルとの関係を定義します。subscriptions.list メソッドは、リクエストに含めるパラメータに応じて、特定のチャンネルのサブスクライバーまたは特定のユーザーの定期購入を取得します。

チャンネルの登録者数

このリクエストは、認証済みチャンネルのサブスクライバーのリストを取得します。

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

ユーザーの登録

チャンネル登録者を登録する場合と同じ方法（subscriptions.list）で、ユーザーが登録しているチャンネルの一覧を表示できます。このリクエストでは、mine パラメータを使用して、認証済みユーザーが登録している YouTube チャンネルのリストを取得します。

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

ユーザーアクティビティの取得

activity リソースには、特定のチャンネルやユーザーが YouTube で行った操作（動画のアップロード、チャンネル登録など）についての情報が含まれます。activities.list メソッドは、リクエスト条件に一致するチャンネルまたはユーザーに関連付けられたアクションを取得します。たとえば、特定のチャンネル、ユーザーの登録チャンネル、ユーザーの YouTube カスタムホームページに関連付けられているアクションを取得できます。

一定期間のアクティビティ

このリクエストでは、認証されたユーザーが 2013 年 4 月に行ったすべてのアクションを取得します。

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

ホームページのアクティビティ

このリクエストでは、認証済みユーザーの YouTube ホームページに表示されるカスタムアクティビティフィードを取得します。

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

YouTube 動画やチャンネルの視聴に関する統計情報、人気度に関する指標、ユーザー層の情報を取得するには、YouTube Analytics API を使用します。サンプルの API リクエストページでは、YouTube アナリティクスから一般的なレポートを取得する方法について説明します。

検索

search.list メソッドを使用して、指定した条件に一致する YouTube 動画、チャンネル、再生リストを検索できます。動画のプロパティ、キーワード、トピック（またはこれらの組み合わせ）に基づいて検索し、作成日、視聴回数、評価などの要因に基づいて検索結果を並べ替えることができます。

他の YouTube Data API リクエストと同様に、search.list メソッドは YouTube リソースの JSON 表現を返します。ただし、他の YouTube リソースとは異なり、検索結果は一意の ID を持つ永続的なオブジェクトではありません。

多くのリクエストは、一般公開されているコンテンツを検索するため、認証は不要です。以下のサンプルのうち、「my」動画を明示的に求めるため、最初の認証リクエストのみが必要です。未認証のリクエストを送信するときは、アプリケーションの一意の API キーを指定する key 引数を含める必要があります。

再生回数の多い動画

このリクエストでは、認証済みのユーザーの動画がすべて取得され、視聴回数の降順で一覧表示されます。

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

埋め込み可能な高画質動画

特定のプロパティを含む動画、つまり他のサイトに埋め込むことができる高解像度の動画を検索します。評価が降順で一覧表示されます。

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

特定のテーマに関する動画

このリクエストでは、字幕を含む YouTube Data API に関連する動画のキーワード検索を行います。

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

トピックベースの検索

より細かくトピックを指定して動画を検索する場合は、キーワードの代わりに無料ベースのトピックを使用します。YouTube チャンネルと動画のすべてのリソースには、リソースに関連付けられた Freebase トピック ID のリストを含む topicDetails オブジェクトが含まれています。トピックベースの検索は、キーワード検索よりもインテリジェントです。Freebase トピックは、現実世界の概念や事物のあらゆる側面を表現しているからです。

Freebase トピックを使用して検索するには、まず Freebase API を使用してトピック ID を取得する必要があります。このリクエストは、Python 用の Freebase トピックに関連付けられている動画を返します。トピック ID は /m/05z1_ です。

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

再生リストまたはチャンネルの検索

動画以外にも、再生リストやチャンネルを検索することもできます。このリクエストでは、「サッカー」というキーワードに一致する再生リストが取得されます。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

サッカーチャンネルを見つけるには、type パラメータを変更します。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

サッカーに関連するコンテンツ（チャンネル、再生リスト、動画）をすべて検索する場合は、ユニバーサル検索を使用できます。type パラメータを省略すると、リクエストはすべてのタイプのコンテンツを取得します。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

リソースの作成と更新

ここまでに説明したリクエストでは、HTTP GET メソッドを使用して YouTube データを取得します。YouTube Data API では、動画、再生リスト、チャンネルなどの YouTube リソースを作成または更新するために、HTTP POST を使用するメソッドも提供されています。次のリクエストは例です。

POST メソッドには、作成または更新されるリソースの JSON 表現である Request body が含まれます。Google APIs Explorer では、インタラクティブツールを使用して JSON 表現を作成できます。

サブスクリプションを作成する

このリクエストでは、認証済みユーザーが GoogleDevelopers チャンネルに登録されます。つまり、定期購入リソースを作成します。

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

プレイリストを作成する

このリクエストによって新しい公開再生リストが作成されます。

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

動画を再生リストに追加する

再生リストを作成したら、再生リストに動画を追加しましょう。再生リスト（'position': 0）の先頭に動画が追加されます。

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }