API Reference

YouTube Data API を使うと、YouTube Web サイトで通常実行する機能を、自分の Web サイトやアプリケーションに統合できます。以下のリストは、API を使って取得できるさまざまなリソースの種類を特定したものです。API は、こうしたさまざまなリソースの挿入、更新、または削除するメソッドもサポートします。

このリファレンスガイドでは、API を使ってこれらすべての操作を実行する方法について説明します。本ガイドはリソースの種類別に整理されています。リソースは、動画、再生リスト、または登録チャンネルなど YouTube エクスペリエンスの一部を構成するアイテムの種類を表しています。リソースの種類ごとに、ガイドは 1 つまたは複数のデータ表現をリスト表示し、リソースは JSON オブジェクトとして表されます。またガイドは、リソースの種類ごとにサポートされる 1 つ以上のメソッド（LIST、POST、DELETE など）をリスト表示し、ユーザーのアプリケーションでの使用方法を説明します。

API の呼び出し

次の要件が、YouTube Data API のリクエストに適用されます。

すべてのリクエストは、API キー（key パラメータを指定）または OAuth 2.0 のトークンを指定する必要があります。使用する API キーは、プロジェクトの API コンソールの API Access ペインで使用できます。
すべての挿入、更新、および削除のリクエストに認証トークンを送信する必要があります。また、認証されたユーザーの非公開データを取得する任意のリクエストにも認証トークンを送信する必要があります。

また、リソースを取得する API メソッドの中には、承認を必要とするパラメータをサポートするメソッドや、リクエストが承認されたときに追加のメタデータを含めることができるメソッドがあります。たとえばリクエストがユーザーによって承認されている場合、その特定のユーザーがアップロードした動画を取得するリクエストに非公開動画を含めることもできます。
API は OAuth 2.0 の認証プロトコルをサポートしています。次のいずれかの方法で OAuth 2.0 トークンを指定できます。
- 次のような access_token クエリパラメータを使用: ?access_token=oauth2-token
- 次のような HTTP Authorization ヘッダーを使用: Authorization: Bearer oauth2-token
アプリケーションで OAuth 2.0 認証を実装する詳細な手順は、認証ガイドを参照してください。

リソースの種類

API は次の種類のリソースを処理します。

activities
channelBanners
channels
guideCategories
playlistItems
playlists
search
subscriptions
thumbnails
videoCategories
videos

activities

activity リソースには、特定のチャンネルまたはユーザーが、YouTube で行った操作に関する情報が格納されています。アクティビティフィードに報告される操作には、動画の評価、動画の共有、お気に入りへの動画の追加、動画へのコメントの投稿、動画のアップロードなどがあります。各 activity リソースは、操作の種類、操作に関連付けられたチャンネル、および操作に関連付けられたリソース（評価またはアップロードされた動画など）を識別します。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`list`	`GET /activities`	リクエスト条件に一致するチャネルアクティビティイベントのリストを返します。たとえば、特定のチャンネルと関連付けられたイベント、ユーザーの登録チャンネルや Google+ フレンドに関連付けられたイベント、各ユーザーにカスタマイズされた YouTube トップページフィードなどを取得できます。
`insert`	`POST /activities`	特定のチャンネルに対するお知らせメッセージを投稿します（リクエストを送信するユーザーは、チャンネルの代理で行動する権限を与えられていることが必要です）。注: `activity` リソースには、動画の評価やお気に入りへの動画の追加といった操作に関する情報が含まれますが、これらの `activity` リソースを生成するには別の API メソッドを使う必要があります。たとえば動画の評価は API の `videos.rate()` メソッド、お気に入りへの動画の追加は `playlistItems.insert()` メソッドを使います。

channelBanners

channelBanner リソースには、新しくアップロードされた画像をチャンネル用のバナー画像として設定するために使う URL が含まれています。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド HTTP リクエスト説明

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`insert`	`POST /channelBanners/insert`	YouTube にチャンネルバナー画像をアップロードします。このメソッドは、チャンネル用のバナー画像を更新する 3 ステップのプロセスのうち、最初の 2 つのステップを示したものです。 `channelBanners.insert` メソッドを呼び出し、バイナリ画像データを YouTube にアップロードします。画像は 16:9 のアスペクト比で、少なくとも 2120 x 1192 ピクセル必要です。ステップ 1 で API が返す応答から `url` プロパティ値を抽出します。チャンネルのブランディング設定を更新する `channels.update` メソッドを呼び出します。`brandingSettings.image.bannerExternalUrl` プロパティの値をステップ 2 で取得した URL に設定します。

https://www.googleapis.com/youtube/v3 に対する相対 URI

insert

POST /channelBanners/insert

YouTube にチャンネルバナー画像をアップロードします。このメソッドは、チャンネル用のバナー画像を更新する 3 ステップのプロセスのうち、最初の 2 つのステップを示したものです。

channelBanners.insert メソッドを呼び出し、バイナリ画像データを YouTube にアップロードします。画像は 16:9 のアスペクト比で、少なくとも 2120 x 1192 ピクセル必要です。
ステップ 1 で API が返す応答から url プロパティ値を抽出します。
チャンネルのブランディング設定を更新する channels.update メソッドを呼び出します。brandingSettings.image.bannerExternalUrl プロパティの値をステップ 2 で取得した URL に設定します。

channels

channel リソースには、YouTube チャンネルに関する情報が格納されます。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`list`	`GET /channels`	リクエスト条件に一致するゼロ個以上の `channel` リソースを返します。
`update`	`PUT /channels`	チャンネルのメタデータを更新します。このメソッドは現在、`channel` リソースの `brandingSettings` と `invideoPromotion` オブジェクトとその子プロパティに対する更新のみをサポートすることに注意してください。

guideCategories

guideCategory リソースは、チャンネルのコンテンツや、チャンネルの人気度などのインジケータに基づいて YouTube がアルゴリズム的に割り当てるカテゴリを識別します。このリストは video categories と似ています。異なる点は、動画をアップロードしたユーザーは動画カテゴリを割り当てることができますが、チャンネルカテゴリを割り当てられるのは YouTube だけです。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`list`	`GET /guideCategories`	YouTube チャンネルに関連付けることができるカテゴリのリストを返します。

playlistItems

playlistItem リソースは、再生リストに含まれている動画などの別のリソースを識別します。また playlistItem リソースには、特に、含まれているリソースが再生リストでどのように使用されるかに関連する、リソースについての詳細が含まれています。

YouTube は再生リストを使って、次に示すようなチャンネルごとの動画の特別なコレクションを識別します。

アップロードした動画
お気に入りの動画
高く評価された動画
再生履歴
後で見る

具体的には、これらのリストは、個人、グループ、または会社の動画、再生リスト、および他の YouTube 情報のコレクションで、チャンネルに関連付けられています。

特定のチャンネルに対するこれらのリストの再生リスト ID を channel resource から取得できます。そのあと、 playlistItems.list メソッドを使って対応するリストを取得できます。また、playlistItems.insert メソッドや playlistItems.delete メソッドを呼び出すことで、これらのリストにアイテムを追加したり、削除したりできます。たとえば、動画をお気に入りに追加すると、その動画はそのユーザーのチャンネルのお気に入り動画の再生リストに挿入されます。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`delete`	`DELETE /playlistItems`	再生リストのアイテムを削除します。
`insert`	`POST /playlistItems`	再生リストにリソースを追加します。
`list`	`GET /playlistItems`	API リクエストのパラメータに一致する、再生リストのアイテムのコレクションが返されます。指定した再生リストのアイテムをすべて取得したり、一意の ID で再生リストのアイテムを 1 つまたは複数取得できます。
`update`	`PUT /playlistItems`	再生リストのアイテムを変更します。たとえば、再生リスト内のアイテムの位置を更新できます。

playlists

playlist リソースは YouTube の再生リストを表します。再生リストとは、順序を付けて表示し、他のユーザーと共有できる動画のコレクションを指します。再生リストには最大 200 本の動画を登録できます。また、各ユーザーが作成する再生リストの数に制限はありません。デフォルトでは再生リストは他のユーザーに一般公開されますが、一般公開または非公開にすることができます。

また YouTube では再生リストを使って、次に示すようなチャンネルの動画の特殊なコレクションを識別します。

アップロードした動画
お気に入りの動画
高く評価された動画
再生履歴
後で見る

より具体的には、これらのリストは、個人、グループ、または会社の動画、再生リスト、および他の YouTube 情報のコレクションで、チャンネルに関連付けられています。特定のチャンネルに対するこれらのリストの再生リスト ID を channel resource から取得できます。

そのあと、playlistItems.list メソッドを使って対応するリストを取得できます。playlistItems.insert メソッドや playlistItems.delete メソッドを呼び出すことで、これらのリストにアイテムを追加したり、削除したりできます。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`delete`	`DELETE /playlists`	再生リストを削除します。
`list`	`GET /playlists`	API リクエストのパラメータに一致する再生リストのコレクションが返されます。たとえば、認証されたユーザーが所有する再生リストをすべて取得したり、一意の ID で再生リストを 1 つまたは複数取得したりできます。
`insert`	`POST /playlists`	再生リストを作成します。
`update`	`PUT /playlists`	再生リストを変更します。たとえば、再生リストのタイトル、説明、公開ステータスを変更できます。

search

検索結果には、API リクエストで指定した検索パラメータに一致する YouTube 動画、チャンネル、または再生リストに関する情報が含まれます。検索結果は、動画など一意に識別可能なリソースを出力しますが、検索結果自体は永続的なデータを持ちません。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`list`	`GET /search`	API リクエストで指定したクエリパラメータに一致する検索結果のコレクションを返します。デフォルトでは、検索結果は `video`、`channel`、`playlist` などの一致するリソースを識別しますが、特定の種類のリソースだけを取得するようにクエリを設定することもできます。

subscriptions

subscription リソースには、YouTube ユーザーの登録チャンネルに関する情報が含まれます。登録チャンネルは、新しい動画がチャンネルに追加されたり、別のユーザーが動画のアップロード、動画の評価、動画へのコメントといった、YouTube でなんらかの操作を行った場合、ユーザーに通知します。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`delete`	`DELETE /subscriptions`	登録チャンネルを削除します。
`insert`	`POST /subscriptions`	認証されたユーザーのチャンネル登録を追加します。
`list`	`GET /subscriptions`	API リクエスト条件に一致する登録チャンネルのリソースを返します。

thumbnails

thumbnail リソースは、リソースに関連付けられたさまざまなサムネイル画像のサイズを識別します。サムネイル画像には次の特性があります。

リソースの snippet.thumbnails プロパティは、そのリソースに使用可能なサムネイル画像を識別するオブジェクトです。
thumbnail リソースには一連のオブジェクトが含まれています。各オブジェクトの名前（default、medium、high など）はサムネイル画像のサイズを表します。
さまざまな種類のリソースで、さまざまなサイズのサムネイル画像をサポートできます。
さまざまな種類のリソースで、同じ名前のサムネイル画像に対してさまざまなサイズを定義できます。たとえば default サムネイル画像（video リソース）は通常 120 x 90 ピクセルで、default サムネイル画像（channel リソース）は通常 88 x 88 ピクセルです。
同じ種類のリソースで、元の画像や YouTube にアップロードされたコンテンツの解像度によって、特定の画像に対してさまざまなサイズのサムネイル画像を指定できます。たとえば HD 動画は、HD 以外の動画よりも高解像度のサムネイルをサポートできます。
サムネイル画像のサイズについての情報が含まれている各オブジェクトは、width プロパティと height プロパティを持ちます。ただし width と height のプロパティがその画像に対して返されないことがあります。
アップロードされたサムネイル画像が必要な寸法に一致しない場合、その画像はアスペクト比を変更することなく、正しいサイズに合わせてサイズ変更されます。画像はトリミングされませんが、サイズが正しくなるように黒いバーが含まれる場合があります。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`set`	`POST /thumbnails/set`	カスタム動画サムネイルを YouTube にアップロードして、動画に設定します。

videoCategories

videoCategory リソースは、アップロードした動画に関連付けられているか、関連付けることができるカテゴリを識別します。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`list`	`GET /videoCategories`	YouTube 動画に関連付けることができるカテゴリのリストを返します。

videos

video リソースは YouTube 動画を表します。

このリソースの詳細については、対応するリソース表現とプロパティのリストを参照してください。

メソッド	HTTP リクエスト	説明
`https://www.googleapis.com/youtube/v3` に対する相対 URI
`insert`	`POST /videos`	YouTube に動画をアップロードし、オプションで動画のメタデータを設定します。
`list`	`GET /videos`	API リクエストのパラメータに一致する動画のリストを返します。
`delete`	`DELETE /videos`	YouTube 動画を削除します。
`update`	`PUT /videos`	動画のメタデータを更新します。
`rate`	`POST /videos/rate`	動画に高い/低い評価を追加したり、動画から評価を削除します。
`getRating`	`GET /videos/getRating`	許可されたユーザーが、指定した動画リストにつけた評価を取得します。