Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

サンプルの 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 APIs Explorer に、所有者に代わって YouTube Data API リクエストを実行する権限を付与する必要があります（非公開チャンネルデータへのアクセスを承認する方法について詳しくは、OAuth 2.0 認証の実装をご覧ください）。API Explorer にリンクしたら、[Authorize requests using OAuth 2.0] ボタンをクリックします。この手順により、API Explorer は所有者に代わってリクエストを行う権限が付与されます。また、承認のスコープを選択します。これにより、API Explorer が実行できるリクエストの種類を指定します。

各リクエストに対するレスポンスは、YouTube リソースの JSON 表現です。リクエストの part パラメータは、レスポンスに含めるリソースの部分を指定します。パラメータは、レスポンスに含める 1 つ以上の最上位（ネストされていない）リソースプロパティを指定します。たとえば、動画リソースの一部は次のとおりです。

snippet
contentDetails
プレーヤー
statistics
ステータス

これらのパーツはすべて、ネストされたプロパティを含むオブジェクトであり、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
  },
}

アップロードされた動画とシステム生成の再生リスト

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

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

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

返された各アイテムの "id" 値は、その playlistItem ID です。再生リストアイテムの動画 ID は、contentDetails 部分の videoId です。

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

ユーザー作成の再生リスト

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

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 を持つ永続オブジェクトではありません。

多くのリクエストは一般公開されているコンテンツを検索するため、認証は必要ありません。以下のサンプルでは、最初のサンプルのみが認証を必要とします。これは、「自分の」動画を具体的にリクエストしているためです。認証されていないリクエストを送信する場合は、アプリケーションの一意の 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}

トピックに基づく検索

特定のトピックに関する動画を検索するより高度な方法は、Freebase トピックをキーワードの代わりに使用することです。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}

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

検索は動画に限定されません。再生リストやチャンネルを検索することもできます。このリクエストは、キーワード「soccer」に一致する再生リストを取得します。

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 には、HTTP POST を使用して、動画、再生リスト、チャンネルなどの YouTube リソースを作成または更新するメソッドもあります。次のリクエストはその例です。

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

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

このリクエストは、認証済みユーザーを 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
      }
   }

サンプルの API リクエスト コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要