API Reference

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

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

API の呼び出し

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

  1. すべてのリクエストでは、API キー(key パラメータを含む)を指定するか、OAuth 2.0 トークンを指定する必要があります。作成した API キーは、Play Console でプロジェクトの [API アクセス] ペインで確認できます。

  2. 挿入、更新、削除の各リクエストに対して認証トークンを送信する必要があります。また、認証済みユーザーのプライベート データを取得するリクエストに対しても認証トークンを送信する必要があります。

    また、リソースを取得する API メソッドの中には、承認を必要とするパラメータをサポートするメソッドや、リクエストが承認されたときに追加のメタデータを含めることができるメソッドがあります。たとえばリクエストがユーザーによって承認されている場合、その特定のユーザーがアップロードした動画を取得するリクエストに非公開動画を含めることもできます。

  3. API は OAuth 2.0 の認証プロトコルをサポートしています。次のいずれかの方法で OAuth 2.0 トークンを指定できます。

    • access_token クエリ パラメータを次のように使用します。?access_token=oauth2-token
    • HTTP Authorization ヘッダーを次のように使用します。Authorization: Bearer oauth2-token

    アプリケーションに OAuth 2.0 認証を実装する詳細な手順については、認証ガイドをご覧ください。

リソースタイプ

アクティビティ

activity リソースには、特定のチャンネルまたはユーザーが YouTube で行った操作に関する情報が格納されます。アクティビティ フィードでレポートされる操作には、動画の評価、動画の共有、お気に入りへの追加、動画のアップロードなどがあります。各 activity リソースは、アクションのタイプ、アクションに関連付けられたチャンネル、アクションに関連付けられたリソース(評価やアップロードされた動画など)を識別します。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /activities リクエスト条件に一致するチャネル アクティビティ イベントのリストを返します。たとえば、特定のチャネルやユーザー自身のチャネルに関連付けられているイベントを取得できます。
insert POST /activities 注: このメソッドは非推奨となり、サポートを終了しました。

字幕

caption リソースは、YouTube の字幕トラックを表します。字幕トラックは、1 つの YouTube 動画とのみ関連付けられます。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
delete DELETE /captions 指定した字幕トラックを削除します。
download GET /captions/id 字幕トラックをダウンロードします。リクエストで tfmt パラメータの値が指定されている場合を除き、字幕トラックは元の形式で返されます。リクエストで tlang パラメータの値が指定されている場合は、この限りではありません。
insert POST /captions 字幕トラックをアップロードします。
list GET /captions 指定した動画に関連付けられている字幕トラックのリストを返します。なお、API レスポンスには実際の字幕は含まれません。また、captions.download メソッドでは字幕トラックを取得できます。
update PUT /captions 字幕トラックを更新します。字幕トラックを更新する際、トラックのドラフト ステータスの変更、トラックの新しい字幕ファイルのアップロード、またはその両方を行うことができます。

channelBanners

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

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
insert POST /channelBanners/insert YouTube にチャンネル バナー画像をアップロードします。このメソッドは、チャンネル用のバナー画像を更新する 3 ステップのプロセスのうち、最初の 2 つのステップを示したものです。

  1. channelBanners.insert メソッドを呼び出して、バイナリ画像データを YouTube にアップロードします。画像は、アスペクト比が 16:9 で、2048x1152 ピクセル以上である必要があります。2560x1440 ピクセルの画像をアップロードすることをおすすめします。
  2. ステップ 1 で API が返すレスポンスから url プロパティの値を抽出します。
  3. channels.update メソッドを呼び出して、チャンネルのブランディング設定を更新します。brandingSettings.image.bannerExternalUrl プロパティの値を、手順 2 で取得した URL に設定します。

チャンネル セクション

channelSection リソースには、チャンネルがおすすめとして取り上げた動画セットに関する情報が格納されます。たとえば、チャンネルの最新アップロード、特に人気の高いアップロード、再生リストの動画などをセクションとして表示できます。

チャンネルのセクションが表示されるのは、そのチャンネルのコンテンツがフィードビューではなくブラウズビューで表示されている場合のみです。チャンネルでコンテンツをブラウズビューに表示できるようにするには、指定したチャンネルの brandingSettings.channel.showBrowseView プロパティを true に設定します。

1 つのチャンネルで作成できるセクションは最大 10 個です。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
delete DELETE /channelSections チャンネル セクションを削除します。
insert POST /channelSections 認証されたユーザーのチャンネルにチャンネル セクションを追加します。1 つのチャンネルで作成できるセクションは最大 10 個です。
list GET /channelSections API リクエスト条件に一致する channelSection リソースのリストを返します。
update PUT /channelSections チャンネル セクションを更新します。

チャンネル

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

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

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

コメント スレッド

commentThread リソースには、YouTube のコメント スレッドに関する情報が含まれています。コメント スレッドは、最上位のコメントと、そのコメントに対する返信(存在する場合)で構成されます。commentThread リソースは、動画またはチャンネルのいずれかに対するコメントを表します。

最上位のコメントと返信はどちらも、実際には commentThread リソース内にネストされた comment リソースです。commentThread リソースには、必ずしもコメントに対するすべての返信が含まれているわけではありません。特定のコメントに対するすべての返信を取得するには、comments.list メソッドを使用する必要があります。また、一部のコメントには返信がありません。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /commentThreads API リクエストのパラメータに一致するコメント スレッドのリストを返します。
insert POST /commentThreads 新しい最上位のコメントを作成します。既存のコメントに返信を追加するには、代わりに comments.insert メソッドを使用します。

コメント

comment リソースには、1 つの YouTube コメントに関する情報が含まれます。comment リソースは、動画またはチャンネルに関するコメントを表します。また、トップレベル コメントまたはトップレベル コメントに対する返信をコメントにすることができます。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /comments API リクエストのパラメータに一致するコメントのリストを返します。
setModerationStatus POST /comments/setModerationStatus 1 つ以上のコメントの管理ステータスを設定します。API リクエストは、コメントに関連付けられたチャンネルまたは動画の所有者によって承認される必要があります。
insert POST /comments 既存のコメントへの返信を作成します。注: 最上位のコメントを作成するには、commentThreads.insert メソッドを使用します。
markAsSpam POST /comments/markAsSpam 注: このメソッドは非推奨となり、サポートを終了しました。
delete DELETE /comments コメントを削除します。
update PUT /comments コメントを変更します。

guideCategories

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

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

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

国際言語

i18nLanguage リソースは、YouTube ウェブサイトがサポートするアプリケーション言語を識別します。アプリ言語は UI 言語と呼ばれることもあります。YouTube ウェブサイトの場合、Google アカウントの設定、ブラウザの言語、IP の場所に基づいて、アプリケーションの言語が自動的に選択されます。ユーザーが YouTube サイトのフッターから目的の UI 言語を手動で選択することもできます。

i18nLanguage リソースは、言語コードと名前を識別します。言語コードは、videoCategories.listguideCategories.list などの API メソッドを呼び出すときに hl パラメータの値として使用できます。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /i18nLanguages YouTube ウェブサイトがサポートするアプリケーション言語のリストを返します。

地域

i18nRegion リソースは、YouTube ユーザーが優先コンテンツの地域として選択できる地域を識別します。コンテンツ ロケールは、コンテンツ ロケールとも呼ばれます。YouTube ウェブサイトの場合、YouTube ドメインやユーザーの IP ロケーションなどのヒューリスティックに基づいて、コンテンツの地域が自動的に選択されます。ユーザーは、YouTube サイトのフッターから目的のコンテンツのリージョンを手動で選択することもできます。

i18nRegion リソースは、リージョン コードと名前を識別します。リージョン コードは、search.listvideos.listactivities.listvideoCategories.list などの API メソッドを呼び出すときに regionCode パラメータの値として使用できます。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /i18nRegions YouTube ウェブサイトがサポートするコンテンツ リージョンのリストを返します。

メンバー

member リソースは、YouTube チャンネルのチャンネル メンバーを表します。メンバーはクリエイターに定期的な金銭的サポートを提供し、特別な特典を受けることができます。たとえば、クリエイターがチャットに対してメンバー限定モードをオンにしている場合、メンバーはチャットできます。

このリソースの詳細については、そのリソース表現プロパティのリストをご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /members チャンネルのメンバー(旧称「スポンサー」)を一覧表示します。API リクエストはチャンネル所有者の承認を受ける必要があります。

メンバーシップ レベル

membershipsLevel リソースは、API リクエストを承認した作成者の料金レベルを識別します。

このリソースの詳細については、そのリソース表現プロパティのリストをご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /membershipsLevels API リクエストを承認したチャネルが所有する 0 個以上の membershipsLevel リソースのコレクションを返します。レベルは暗黙的な表示順序で返されます。

playlistItemspageInfo.totalResults

playlistItem リソースは、再生リストに含まれる別のリソース(動画など)を識別します。さらに、playlistItem リソースには、含まれるリソースに関する詳細が含まれ、具体的には、そのリソースがプレイリスト内でどのように使用されるかについての情報が含まれます。

YouTube では、チャンネルにアップロードされた動画のリストも再生リストを使用して識別します。リスト内の各 playlistItem は 1 本の動画を表します。そのリストの再生リスト ID は、特定のチャンネルの channel resource から取得できます。その後、playlistItems.list メソッドを使用してリストを追加できます。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

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

再生リスト

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 再生リストを変更します。たとえば、再生リストのタイトル、説明、公開ステータスを変更できます。

検索結果には、API リクエストで指定された検索パラメータに一致する YouTube 動画、チャンネル、または再生リストの情報が含まれます。検索結果は、動画のように一意に識別できるリソースを参照しますが、固有の永続データはありません。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /search API リクエストで指定されたクエリ パラメータに一致する検索結果のコレクションを返します。デフォルトでは、検索結果セットは一致する videochannelplaylist リソースが識別されますが、特定のタイプのリソースのみを取得するようにクエリを構成することもできます。

サブスクリプション

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

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

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

サムネイル

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

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

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

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

VideoAbuseReportReasons(動画の不正行為の報告の理由

videoAbuseReportReason リソースには、不適切なコンテンツが動画に含まれていると報告される理由に関する情報が含まれます。アプリが videos.reportAbuse メソッドを呼び出して不正な動画を報告すると、このリクエストでは videoAbuseReportReason リソースからの情報を使用して、動画が報告されている理由を特定します。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
list GET /videoAbuseReportReasons 不適切なコンテンツを報告する際に利用できる理由のリストを取得する。

videoCategories

videoCategory リソースは、アップロードされた動画に関連付けられたカテゴリ、または関連付けられている可能性のあるカテゴリを識別します。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

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

動画

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 許可されたユーザーが、指定した動画リストにつけた評価を取得します。
reportAbuse POST /videos/reportAbuse 不適切なコンテンツを含む動画を報告する。

ウォーターマーク

watermark リソースは、指定したチャンネルの動画の再生中に表示される画像を識別します。画像のリンク先ターゲット チャンネルや、動画の再生中に透かしを表示するタイミングとその長さを指定することもできます。

このリソースの詳細については、リソース表現およびプロパティ一覧をご覧ください。

メソッド HTTP リクエスト 説明
https://www.googleapis.com/youtube/v3 からの相対 URI
set POST /watermarks/set YouTube に透かし画像をアップロードしてチャンネルに設定します。
unset POST /watermarks/unset チャンネルの透かし画像を削除します。