API Reference

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

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

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 リクエスト条件に一致するチャネル アクティビティ イベントのリストを返します。たとえば、特定のチャンネルやユーザー自身のチャンネルに関連付けられたイベントを取得できます。

字幕

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 で、2,048×1,152 ピクセル以上にする必要があります。2,560×1,440 ピクセルの画像をアップロードすることをおすすめします。
  2. ステップ 1 で API が返すレスポンスから url プロパティの値を抽出します。
  3. channels.update メソッドを呼び出して、チャンネルのブランディング設定を更新します。brandingSettings.image.bannerExternalUrl プロパティの値を手順 2 で取得した URL に設定します。

ChannelSections

channelSection リソースには、チャンネルがおすすめとして選択した一連の動画に関する情報が含まれています。たとえば、チャンネルの最新のアップロード動画、最も人気のあるアップロード動画、1 つ以上の再生リストの動画などをセクションに表示できます。

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

チャンネルで作成できるセクションは最大 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 オブジェクトとその子プロパティの更新のみをサポートします。

CommentThreads

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 メソッドを使用します。
delete DELETE /comments コメントを削除します。
update PUT /comments コメントを変更します。

I18nLanguages

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

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

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

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

I18nRegions

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

各 i18nRegion リソースは、地域コードと名前を識別します。リージョン コードは、search.list、videos.list、activities.list、videoCategories.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 リクエストはチャンネル所有者によって承認される必要があります。

MembershipsLevels

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

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

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

playlistItemspageInfo.totalResults

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

YouTube では、再生リストを使用してチャンネルのアップロード済み動画のリストを識別します。このリストの各 playlistItem は、アップロード済み動画 1 つを表します。特定のチャンネルの channel resource から、そのリストの再生リスト ID を取得できます。その後、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 の再生リストを表します。再生リストとは、順序を付けて表示し、他のユーザーと共有できる動画のコレクションを指します。デフォルトでは再生リストは他のユーザーに一般公開されますが、一般公開または非公開にすることができます。

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 リクエストで指定されたクエリ パラメータに一致する検索結果のコレクションを返します。デフォルトでは、検索結果セットは一致する video、channel、playlist リソースを識別しますが、特定のタイプのリソースのみを取得するようにクエリを構成することもできます。

定期購入

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 リソースには一連のオブジェクトが含まれています。各オブジェクトの名前（default、medium、high など）は、サムネイル画像のサイズを表します。
  • さまざまな種類のリソースで、さまざまなサイズのサムネイル画像をサポートできます。
  • さまざまな種類のリソースで、同じ名前のサムネイル画像に対してさまざまなサイズを定義できます。たとえば、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 チャンネルの透かし画像を削除します。