- この記事で扱う内容
- 前提と基本用語
- Searchリソースの使い方
- listメソッド
- HTTPリクエスト
- クエリ
- 必須パラメータ
- フィルタパラメータ
- オプションパラメータ
- channelId
- channelType
- eventType
- location
- locationRadius
- maxResults
- onBehalfOfContentOwner
- order
- pageToken
- publishedAfter
- publishedBefore
- q
- regionCode
- relevanceLanguage
- safeSearch
- topicId
- type
- videoCaption
- videoCategoryId
- videoDefinition
- videoDimension
- videoDuration
- videoEmbeddable
- videoLicense
- videoPaidProductPlacement
- videoSyndicated
- videoType
- オプションパラメータの使用頻度別一覧
- HTTPリクエストヘッダー
- HTTPリクエストボディ
- HTTPレスポンス
- listメソッド
- 無料かつコードなしでAPIを試す
- おすすめの関連記事
- 参考
この記事で扱う内容
この記事では、YouTube Data APIのSearchリソースのメソッドごとのHTTPリクエスト・HTTPレスポンスについて解説します。
前提と基本用語
必要な知識・スキル
- API(Application Programming Interface)に関する基本知識
必要な環境
- PC
YouTube Data APIのリソースとメソッドとは
YouTube Data APIのリソースとは、動画やチャンネルなどの対象(データの種類)のことです。
YouTube Data APIのメソッドとは、そのリソース(動画やチャンネルなど)に対して行える操作(検索・取得・更新など)のことです。
このリソースとメソッドを組み合わせることで、欲しい情報を取得したり変更したりできます。
YouTube Data APIのプロパティとは
YouTube Data APIのプロパティとは、HTTPレスポンス(JSON形式のデータなど)の中に含まれる個々の情報項目のことです。
一般的に、フィールドや項目と表現されることもあります。
例えば、動画のタイトルやID、公開日時などがプロパティとして返されます。
割り当て使用量(quota)とは
割り当て使用量(quota)とは、APIの1日あたりの利用上限値のようなものです。
通常、Google Cloudプロジェクトを作成後、そのプロジェクトでYouTube Data APIを有効にし、認証情報(APIキーやOAuth 2.0認証情報)を作成して、それらを使用してAPIを利用します。
既定の割り当て使用量は、1つのGoogle Cloudプロジェクトにつき、1日あたり10,000ユニットです。
割り当てコスト(quota cost)とは
割り当てコスト(quota cost)とは、APIの利用値のようなものです。
APIを利用するたびに割り当てコストがかかり、割り当て使用量を超えると、その日はAPIが利用できなくなります。
APIによって割り当てコストが異なります。
Searchリソースの使い方
YouTube Data APIのSearchリソースとは、YouTube上の検索対象(動画・チャンネル・再生リスト)のことです。
このリソースのメソッドを使うことで、自作のプログラムなどから、キーワードや条件を指定して目的の動画・チャンネル・再生リストを効率的に探すことができます。
以下のメソッドが提供されています。
| No | メソッド名 | 概要 | 割り当てコスト(ユニット) |
|---|---|---|---|
| 1 | list | 指定したキーワードや条件に合う動画・チャンネル・再生リストを検索し、それらの情報を取得できる。 | 100 |
listメソッド
HTTPリクエスト
以下は、このメソッドを使うために送信するHTTPリクエストの構成要素です。
リクエストライン
HTTPメソッド
GETリクエストターゲット
https://www.googleapis.com/youtube/v3/searchHTTPバージョン
クエリ
以下は、このメソッドで使えるクエリのパラメータです。
必須パラメータ
設定は必須です。
| パラメータ | 設定値 | 概要 |
|---|---|---|
| part (検索結果に含める情報の種類) | 以下から1つ以上を設定。 ・snippet (動画タイトル、動画概要、チャンネル名、公開日時などを含める) | 検索結果に「どの種類の情報を含めるか」を指定するパラメータ。 |
part
検索結果に「どの種類の情報を含めるか」を指定します。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&key=あなたのAPIキーフィルタパラメータ
設定は任意です。
もし設定する場合、「いずれか1つだけ」を設定します。
| パラメータ | 設定値 | 概要 |
|---|---|---|
| forContentOwner (コンテンツ所有者用の検索) | 以下のどちらかを設定。 ・true ・false | 特定のチャンネル全体に限定して検索したいときに指定するパラメータ。 true:限定する false:限定しない |
| forDeveloper (開発者用の検索) | 以下のどちらかを設定。 ・true ・false | 特定のアプリやWebサービスからアップロードされた動画に限定して検索したいときに指定するパラメータ。 true:限定する false:限定しない |
| forMine (YouTubeチャンネル所有者用の検索) | 以下のどちらかを設定。 ・true ・false | 特定のYouTubeチャンネルの動画に限定して検索したいときに指定するパラメータ。 true:限定する false:限定しない |
forContentOwner
YouTubeコンテンツパートナー用のパラメータです。
特定の管理対象全体に限定して検索したいときに指定します。
プログラムから実行する場合、値は「boolean」型で指定します。
HTTPリクエスト例)
・リクエストライン
GET https://www.googleapis.com/youtube/v3/search?forContentOwner=true&type=video・HTTPリクエストヘッダー
Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}forDeveloper
YouTube Data API経由で動画アップロード機能を提供しているアプリやWebサービスの開発者用のパラメータです。
特定のアプリやWebサービスからアップロードされた動画だけを検索したいときに使うことがあると思います。
プログラムから実行する場合、値は「boolean」型で指定します。
HTTPリクエスト例)
・リクエストライン
GET https://www.googleapis.com/youtube/v3/search?forDeveloper=true&type=video・HTTPリクエストヘッダー
Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}forMine
YouTubeチャンネル所有者用のパラメータです。
特定のYouTubeチャンネルの動画だけを検索したいときに使うことがあると思います。
プログラムから実行する場合、値は「boolean」型で指定します。
HTTPリクエスト例)
・リクエストライン
GET https://www.googleapis.com/youtube/v3/search?forMine=true&type=video・HTTPリクエストヘッダー
Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}オプションパラメータ
設定は任意です。
もし設定する場合、中には「他のパラメータと組み合わせないと使えないもの」や「自動的に他パラメータと組み合わせられるもの」があるので注意が必要です。
| パラメータ | 設定値 | 概要 |
|---|---|---|
| channelId (チャンネルID) | 任意のチャンネルID 例:UCrXUsMBcfTVqwAS7DKg9C0Q (YouTube Japan 公式チャンネルのチャンネルID) | 検索対象のチャンネルIDを指定するパラメータ。 |
| channelType (チャンネル種類) | 以下のいずれか1つを設定。 ・any (すべて) ・show (番組のみ) ※既定値は「any」。 | 検索対象のチャンネル種類を指定するパラメータ。 ※番組とは、公式番組提供者向けの番組チャンネルが提供する動画のこと。通常のチャンネルの動画やライブ配信とは異なる。 |
| eventType (ライブ配信の状態) | 以下のいずれか1つを設定。 ・completed (ライブ配信完了) ・live (ライブ配信中) ・upcoming (ライブ配信予定) | 検索対象のライブ配信の状態を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| location (地理的な中心位置) | 任意の緯度と経度の座標 例:37.42307,-122.08427 | 検索対象の地理的な中心位置を指定するパラメータ。 ※あわせて「locationRadius」パラメータを指定し、「type」パラメータに「video」を指定する必要あり。 |
| locationRadius (地理的な中心位置からの半径) | 任意の1,000km以下の距離 例:5.5km | 検索対象の位置情報の半径を指定するパラメータ。 ※浮動小数点数の後に測定単位(有効はm、km、ft、mi)を付けて指定する。 ※あわせて「location」パラメータを指定し、「type」パラメータに「video」を指定する必要あり。 |
| maxResults (検索結果の取得件数) | 0~50 ※既定値は「5」。 | 検索結果の件数を指定するパラメータ。 |
| onBehalfOfContentOwner (コンテンツ所有者アカウントID) | 任意のコンテンツ所有者アカウントID 例:abcd1234 (Googleから付与されるID) | 特定のコンテンツ所有者アカウントIDを指定するパラメータ。 ※YouTubeコンテンツパートナー専用パラメータ。 ※OAuth 2.0認証が必須(APIキーでは利用できない)。 |
| order (検索結果の並び順) | 以下のいずれか1つを設定。 ・date (作成日時の新しい順) ・rating (評価の高い順) ・relevance (関連性の高い順) ・title (タイトルのアルファベット順) ・videoCount (アップロードされた動画数の多い順) ・viewCount (動画は表示回数の多い順、ライブ配信は同時視聴者数の多い順) ※既定値は「relevance」。 | 検索結果の並び順を指定するパラメータ。 |
| pageToken (ページトークン) | 任意のページトークン 例:ABCDEF | 検索結果の特定ページを指定するパラメータ。 ※検索結果が多い場合、検索結果はページ単位に分割され、それぞれにページトークンが割り振られる。 |
| publishedAfter (公開日時の下限(これ以降)) | 任意のRFC 3339形式の日時 例:2024-12-31T15:00:00Z (日本時間の2025-01-01 00:00:00) | 検索対象の公開日時の下限(これ以降)を指定するパラメータ。 ※UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する。 |
| publishedBefore (公開日時の上限(これ以前)) | 任意のRFC 3339形式の日時 例:2025-12-31T14:59:59Z (日本時間の2025-12-31 23:59:59) | 検索対象の公開日時の上限(これ以前)を指定するパラメータ。 ※UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する。 |
| q (検索キーワード) | 任意のキーワード 例:猫 例:猫|犬 例:猫|犬 -鳥 | 検索キーワードを指定するパラメータ。 ※「-(否定)」や「|(または)」記号をキーワード前に付けることで、特定のキーワードを除外したり、複数の検索キーワードで検索したりできる。 |
| regionCode (動画を視聴できる国のコード) | 任意のISO 3166-1 alpha-2形式の国コード 例:JP (日本の国コード) | 検索対象の動画を視聴できる国のコードを指定するパラメータ。 ※ユーザーの視聴可能性をもとに選別するだけで、動画投稿元の国を指定するものではない。 |
| relevanceLanguage (関連性の高い言語コード) | 任意のISO 639-1(2文字)の言語コード 例:ja (日本の言語コード) | 検索対象と関連性の高い言語のコードを指定するパラメータ。 |
| safeSearch (検索の安全レベル) | 以下のいずれか1つを設定。 ・moderate (一部のコンテンツを除外(少なくとも、ユーザーの言語・地域で制限されているコンテンツは除外)) ・none (何も除外しない) ・strict (すべての制限付きコンテンツを除外) ※既定値は「moderate」 | 検索結果の安全レベルを指定するパラメータ。 |
| topicId (FreebaseトピックID) | 任意のFreebaseのトピックID 例:/m/04rlf (Music) | 検索対象と関連性の高いFreebaseのトピックIDを指定するパラメータ。 ※Freebase は既に公式に非推奨。使用可能なFreebaseトピックIDは不明。 |
| type (検索対象の種類) | 以下から1つ以上を設定。 ・channel (チャンネル) ・playlist (再生リスト) ・video (動画) ※既定値は、「video,channel,playlist」。 | 検索するリソースの種類(動画、チャンネル、再生リスト)を指定するパラメータ。 |
| videoCaption (動画の字幕有無) | 以下のいずれか1つを設定。 ・any (すべて) ・closedCaption (字幕有りのみ) ・none (字幕無しのみ) | 検索対象の動画の字幕有無を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoCategoryId (動画カテゴリーID) | 任意の動画カテゴリーID 例:22 (ブログ) | 検索対象の動画のカテゴリーIDを指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoDefinition (動画の解像度) | 以下のいずれか1つを設定。 ・any (すべて) ・high (高画質(HD)の動画のみ) ・standard (標準画質(SD)の動画のみ) | 検索対象の動画の解像度を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoDimension (動画の画面次元) | 以下のいずれか1つを設定。 ・2d (2D動画のみ) ・3d (3D動画のみ) ・any (すべて) ※既定値は「any」。 | 検索対象の動画の画面次元を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoDuration (動画の再生時間) | 以下のいずれか1つを設定。 ・any (すべて) ・long (20分超) ・medium (4~20分) ・short (4分未満) ※既定値は「any」。 | 検索対象の動画の再生時間を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoEmbeddable (動画の埋め込み可否) | 以下のいずれか1つを設定。 ・any (すべて) ・true (埋め込み可能な動画のみ) | 検索対象の動画の埋め込み可否を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoLicense (動画のライセンス種別) | 以下のいずれか1つを設定。 ・any (すべて) ・creativeCommon (クリエイティブ・コモンズライセンスを持つ動画のみ) ・youtube (標準のYouTubeライセンスを持つ動画のみ) | 検索対象の動画のライセンス種別を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoPaidProductPlacement (動画の商品プロモーション表示有無) | 以下のいずれか1つを設定。 ・any (すべて) ・true (有料プロモーションを含む動画のみ) | 検索対象の動画内の商品プロモーション有無を指定するパラメータ。 ※YouTube広告の有無ではない。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoSyndicated (動画の配信範囲) | 以下のいずれか1つを設定。 ・any (すべて) ・true (シンジケーション動画(youtube.com以外でも再生できる動画)のみ) | 検索対象の動画の配信範囲を指定するパラメータ。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
| videoType (動画種類) | 以下のいずれか1つを設定。 ・any (すべて) ・episode (番組エピソードのみ) ・movie (映画のみ) | 検索対象の動画種類を指定するパラメータ。 ※映画とは、YouTubeが公式に提供している映画動画のこと。通常の動画とは異なる。 ※あわせて「type」パラメータに「video」を指定する必要あり。 |
channelId
検索するチャンネルのIDを指定するパラメータです。
特定のチャンネルに限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UCrXUsMBcfTVqwAS7DKg9C0Q&key=あなたのAPIキーchannelType
検索対象のチャンネル種類を指定するパラメータです。
番組チャンネルが提供する番組動画に限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&channelType=show&key=あなたのAPIキーeventType
検索対象のライブ配信の状態を指定するパラメータです。
動画のライブ配信状態で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&eventType=completed&type=video&key=あなたのAPIキーlocation
検索対象の地理的な中心位置を指定するパラメータです。
「locationRadius」パラメータと組み合わせて、円形の地理的範囲を指定します。
指定した地理的範囲をメタデータ(タイトル、説明文、タグなど)に設定している動画に限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&location=37.42307,-122.08427&locationRadius=5.5km&type=video&key=あなたのAPIキーlocationRadius
検索対象の位置情報の半径を指定するパラメータです。
「location」パラメータと組み合わせて、円形の地理的範囲を指定します。
指定した地理的範囲をメタデータ(タイトル、説明文、タグなど)に設定している動画に限定した検索ができます。
設定値は、浮動小数点数の後に測定単位を付けて指定する必要があり、有効な測定単位は以下の通りです。
- m(メートル)
- km(キロメートル)
- ft(フィート)
- mi(マイル)
※1,000kmを超える設定値には、対応していません。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&location=37.42307,-122.08427&locationRadius=5.5km&type=video&key=あなたのAPIキーmaxResults
検索結果の件数を指定するパラメータです。
検索結果の件数を制御できます。
プログラムから実行する場合、値は「unsigned integer」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&maxResults=50&key=あなたのAPIキーonBehalfOfContentOwner
YouTubeコンテンツパートナー専用パラメータで、特定のコンテンツ所有者アカウントIDを指定するパラメータです。
Googleから付与されるIDを指定します。
プログラムから実行する場合、値は「string」型で指定します。
HTTPリクエスト例)
・リクエストライン
GET https://www.googleapis.com/youtube/v3/search?part=snippet&onBehalfOfContentOwner=abcd1234・HTTPリクエストヘッダー
Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}order
検索結果の並び順を指定するパラメータです。
検索結果の並び順を制御できます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&order=date&key=あなたのAPIキーpageToken
検索結果の特定ページを指定するパラメータです。
検索結果が多い場合、検索結果はページ単位に分割され、それぞれにページトークンが割り振られます。
そのような場合、割り振られたページトークンを指定することで、特定のページを検索できます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&pageToken=ABCDEF&key=あなたのAPIキーpublishedAfter
検索対象の公開日時の下限(これ以降)を指定するパラメータです。
日時は、RFC 3339形式で指定する必要があります。
また、日時は、UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する必要があります。
プログラムから実行する場合、値は「datetime」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&publishedAfter=2024-12-31T15:00:00Z&key=あなたのAPIキーpublishedBefore
検索対象の公開日時の上限(これ以前)を指定するパラメータです。
日時は、RFC 3339形式で指定する必要があります。
また、日時は、UTC(世界協定時刻)で解釈されるため、日本時間を指定する場合は、日本時間から9時間引いた日時を指定する必要があります。
プログラムから実行する場合、値は「datetime」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&publishedBefore=2025-12-31T14:59:59Z&key=あなたのAPIキーq
検索キーワードを指定するパラメータです。
キーワードに関連する情報を検索できます。
キーワードに「-(否定)」や「|(または)」記号を付けることで、特定のキーワードを除外したり、複数の検索キーワードに関連する情報を検索したりできます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&q=猫&key=あなたのAPIキーregionCode
検索対象の動画を視聴できる国のコードを指定するパラメータです。
設定値は、ISO 3166-1 alpha-2形式の国コードを指定する必要があります。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet®ionCode=JP&key=あなたのAPIキーrelevanceLanguage
検索対象と関連性の高い言語のコードを指定するパラメータです。
特定の言語と関連性が高い動画を検索できます。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&relevanceLanguage=ja&key=あなたのAPIキーsafeSearch
検索結果の安全レベルを指定するパラメータです。
制限付きコンテンツの有無で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&safeSearch=strict&key=あなたのAPIキーtopicId
検索対象と関連性の高いFreebaseのトピックIDを指定するパラメータです。
FreebaseのトピックIDに限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&topicId=/m/04rlf&key=あなたのAPIキーtype
検索するリソースの種類(動画、チャンネル、再生リスト)を指定するパラメータです。
特定のリソースの種類(動画、チャンネル、再生リスト)に限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&type=video&key=あなたのAPIキーvideoCaption
検索対象の動画の字幕有無を指定するパラメータです。
動画の字幕有無で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoCaption=closedCaption&type=video&key=あなたのAPIキーvideoCategoryId
検索対象の動画のカテゴリーIDを指定するパラメータです。
特定のカテゴリーが設定された動画に限定した検索ができます。
具体的なカテゴリーIDについては、「VideoCategoriesリソースのlistメソッド」で取得できます。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoCategoryId=22&type=video&key=あなたのAPIキーvideoDefinition
検索対象の動画の解像度を指定するパラメータです。
動画の解像度で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoDefinition=high&type=video&key=あなたのAPIキーvideoDimension
検索対象の動画の画面次元を指定するパラメータです。
動画の画面次元で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoDimension=2d&type=video&key=あなたのAPIキーvideoDuration
検索対象の動画の再生時間を指定するパラメータです。
特定の再生時間の動画に限定した検索ができます。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoDuration=short&type=video&key=あなたのAPIキーvideoEmbeddable
検索対象の動画の埋め込み可否を指定するパラメータです。
動画の埋め込み可否で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoEmbeddable=true&type=video&key=あなたのAPIキーvideoLicense
検索対象の動画のライセンス種別を指定するパラメータです。
動画のライセンス種別で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoLicense=creativeCommon&type=video&key=あなたのAPIキーvideoPaidProductPlacement
検索対象の動画内の商品プロモーション有無を指定するパラメータです。
動画内の商品プロモーション有無で限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoPaidProductPlacement=true&type=video&key=あなたのAPIキーvideoSyndicated
検索対象の動画の配信範囲を指定するパラメータです。
動画の配信範囲に限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoSyndicated=true&type=video&key=あなたのAPIキーvideoType
検索対象の動画種類を指定するパラメータです。
動画種類に限定した検索ができます。
プログラムから実行する場合、値は「string」型で指定します。
リクエストライン例)
GET https://www.googleapis.com/youtube/v3/search?part=snippet&videoType=movie&type=video&key=あなたのAPIキーオプションパラメータの使用頻度別一覧
個人的な使用感ですが、オプションパラメータを使用頻度別に分けしてみました。
もちろん、APIの利用用途によって変わる部分なので、すべての方に当てはまるとは思いませんが、初学者の方でしたら、以下の優先順位で覚えるのも良いのではないかと思います。
よく使う
- maxResults(検索結果の取得件数)
- order(検索結果の並び順)
- pageToken(ページトークン)
- q(検索キーワード)
- type(検索対象の種類)
まあまあ使う
- channelId(チャンネルID)
- publishedAfter(公開日時の下限(これ以降))
- publishedBefore(公開日時の上限(これ以前))
- videoCategoryId(動画カテゴリーID)
- videoDuration(動画の再生時間)
たまに使う
- eventType(ライブ配信の状態)
- regionCode(動画を視聴できる国のコード)
- relevanceLanguage(関連性の高い言語コード)
ほぼ使わない
- channelType(チャンネル種類)
- location(地理的な中心位置)
- locationRadius(地理的な中心位置からの半径)
- onBehalfOfContentOwner(コンテンツ所有者アカウントID)
- safeSearch(検索の安全レベル)
- topicId(FreebaseトピックID)
- videoCaption(動画の字幕有無)
- videoDefinition(動画の解像度)
- videoDimension(動画の画面次元)
- videoEmbeddable(動画の埋め込み可否)
- videoLicense(動画のライセンス種別)
- videoPaidProductPlacement(動画の商品プロモーション表示有無)
- videoSyndicated(動画の配信範囲)
- videoType(動画種類)
HTTPリクエストヘッダー
Authorization
OAuth 2.0認証を使う場合に必須です。
HTTPリクエストヘッダー例)
Authorization: Bearer {OAuth 2.0認証で取得したアクセストークン}If-Match
ETagを使用してキャッシュ制御をしたいときに使います。
「ETag が一致する場合」にAPIを実行します。
HTTPリクエストヘッダー例)
If-Match: "W/\"{過去に取得したレスポンスに含まれていたETag}\""If-None-Match
ETagを使用してキャッシュ制御をしたいときに使います。
「ETag が一致しない場合」にAPIを実行します。
HTTPリクエストヘッダー例)
If-None-Match: "W/\"{過去に取得したレスポンスに含まれていたETag}\""Accept-Encoding: gzip
HTTPレスポンスをgzip圧縮したいときに使います。
YouTube Data APIは、「gzip圧縮」に対応しています。
HTTPリクエストヘッダー例)
Accept-Encoding: gzip
User-Agent: {プログラム名} (gzip)HTTPリクエストボディ
HTTPレスポンス
HTTPリクエストを送信すると、HTTPレスポンスが返ってきます。
HTTPレスポンスボディ
成功の場合
HTTPレスポンスボディは大きく分けて、以下の要素で構成されています。
- Searchリソースのlistメソッドのレスポンス全体(youtube#searchListResponseという種類のリソース)
※以降、「Search:listレスポンス」 と呼びます。 - 検索結果(youtube#searchResultという種類のリソース)
1つのSearch:listレスポンスの中に、1つ~複数の検索結果が含まれます。
以下のようなHTTPレスポンスボディが返ってきます。
{
"kind": "youtube#searchListResponse",
"etag": etag,
"nextPageToken": string,
"prevPageToken": string,
"regionCode": string,
"pageInfo": {
"totalResults": integer,
"resultsPerPage": integer
},
"items": [
{
"kind": "youtube#searchResult",
"etag": etag,
"id": {
"kind": string,
"videoId": string,
"channelId": string,
"playlistId": string
},
"snippet": {
"publishedAt": datetime,
"channelId": string,
"title": string,
"description": string,
"thumbnails": {
"default": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"medium": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"high": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"standard": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
"maxres": {
"url": string,
"width": unsigned integer,
"height": unsigned integer
},
},
"channelTitle": string,
"liveBroadcastContent": string
}
}
]
}失敗(エラー)の場合
HTTPリクエストに失敗すると以下のようにHTTPレスポンスボディが返ってきます。
以下はAPIキーを設定しなかった場合のHTTPレスポンスボディです。
{
"error": {
"code": 403,
"message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.",
"errors": [
{
"message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.",
"domain": "global",
"reason": "forbidden"
}
],
"status": "PERMISSION_DENIED"
}
}youtube#searchListResponseリソースのプロパティ
| プロパティ | 値の型と例 | 概要 |
|---|---|---|
| kind | 文字列(string) 例:”youtube#searchListResponse” | HTTPレスポンスボディのリソース種類。 固定値。 |
| etag | 文字列(string) 例:”pV8eQZStdeClPWW92xVaB4piKe8″ | リソースのEtag。 ※Etagは、キャッシュ制御や変更検出に使う識別子のこと。 |
| nextPageToken | 文字列(string) 例:”CGQQAA” | 次のページを取得するときに指定するトークン。 |
| prevPageToken | 文字列(string) 例:”CDIQAQ” | 前のページを取得するときに指定するトークン。 |
| regionCode | 文字列(string) 例:”JP” ※既定値は「US」。 | 検索時に指定された国コード。 オプションパラメータ「regionCode」に指定した値。 |
| pageInfo | オブジェクト(object) 例: { “totalResults”: 1000000, “resultsPerPage”: 50 } | ページ情報。 以下のプロパティを含むオブジェクト。 ・totalResults ・resultsPerPage |
| pageInfo.totalResults | 数値(integer) 例:1000000 | 検索結果の総件数(近似値)。 最大値は、1,000,000。 |
| pageInfo.resultsPerPage | 数値(integer) 例:50 | 検索結果1ページあたりの件数。 HTTPリクエストで指定したオプションパラメータ「maxResults」で制御される。 |
| items | リスト(list) 例: [ { “kind”: “youtube#searchResult”, (省略) }, { “kind”: “youtube#searchResult”, (省略) }, (省略) ] | 検索結果(youtube#searchResultリソース)のリスト。 動画/チャンネル/再生リストごとの情報が含まれる。 |
youtube#searchResultリソースのプロパティ
| プロパティ | 値の型と例 | 概要 |
|---|---|---|
| kind | 文字列(string) 例:”youtube#searchResult” | 検索結果のリソース種類。 固定値。 |
| etag | 文字列(string) 例:”hcqmUk7eiRuvRxF9tP89uH4c4NA” | リソースのEtag。 ※Etagは、キャッシュ制御や変更検出に使う識別子のこと。 |
| id | オブジェクト(object) 例: { “kind”: “youtube#video”, “videoId”: “p6h57WqRRl8” } | ID情報。 以下のプロパティを含むオブジェクト。 ・kind ・videoId、channelId、playlistIdのいずれか |
| id.kind | 文字列(string) 例:”youtube#video” 例:”youtube#channel” 例:”youtube#playlist” | 検索結果のリソース種類。 固定値。 動画、チャンネル、再生リストごとに値が変わる。 |
| id.videoId | 文字列(string) 例:”p6h57WqRRl8″ | 動画ID。 ※このプロパティは、id.kindプロパティの値が「”youtube#video”」の場合に存在する。 |
| id.channelId | 文字列(string) 例:”UCTDMT3aL30noTVFgNPA9XtQ” | チャンネルID。 ※このプロパティは、id.kindプロパティの値が「”youtube#channel”」の場合に存在する。 |
| id.playlistId | 文字列(string) 例:”PLmnMiSXtJEB1MLExnImqhHsHG6MevUrG-“ | 再生リストID。 ※このプロパティは、id.kindプロパティの値が「”youtube#playlist”」の場合に存在する。 |
| snippet | オブジェクト(object) 例: { “publishedAt”: “2024-12-04T15:00:58Z”, “channelId”: “UCTDMT3aL30noTVFgNPA9XtQ”, “title”: “劇場版『名探偵コナン 隻眼の残像(せきがんのフラッシュバック)』特報【2025年4月18日(金)公開】”, “description”: “ついてくるな、遊びじゃねえんだー。 劇場版『名探偵コナン』シリーズ28作目、遂に始動…!! 見えない左眼を押さえ …”, “thumbnails”: { “default”: { “url”: “https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg”, “width”: 120, “height”: 90 }, “medium”: { “url”: “https://i.ytimg.com/vi/p6h57WqRRl8/mqdefault.jpg”, “width”: 320, “height”: 180 }, “high”: { “url”: “https://i.ytimg.com/vi/p6h57WqRRl8/hqdefault.jpg”, “width”: 480, “height”: 360 } }, “channelTitle”: “東宝MOVIEチャンネル”, “liveBroadcastContent”: “none”, “publishTime”: “2024-12-04T15:00:58Z” } | 検索結果の基本情報。 以下のプロパティを含むオブジェクト。 ・publishedAt ・channelId ・title ・description ・thumbnails ・channelTitle ・liveBroadcastContent ・publishTime |
| snippet.publishedAt | RFC 3339形式の日時(datetime) 例:2024-12-31T15:00:00Z (日本時間の2025-01-01 00:00:00) | 公開日時。 |
| snippet.channelId | 文字列(string) 例:”UCTDMT3aL30noTVFgNPA9XtQ” | チャンネルID。 |
| snippet.title | 文字列(string) 例:”劇場版『名探偵コナン 隻眼の残像(せきがんのフラッシュバック)』特報【2025年4月18日(金)公開】” | タイトル。 |
| snippet.description | 文字列(string) 例:”ついてくるな、遊びじゃねえんだー。 劇場版『名探偵コナン』シリーズ28作目、遂に始動…!! 見えない左眼を押さえ …” | 説明。 |
| snippet.thumbnails | オブジェクト(object) 例: { “default”: { “url”: “https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg”, “width”: 120, “height”: 90 }, “medium”: { “url”: “https://i.ytimg.com/vi/p6h57WqRRl8/mqdefault.jpg”, “width”: 320, “height”: 180 }, “high”: { “url”: “https://i.ytimg.com/vi/p6h57WqRRl8/hqdefault.jpg”, “width”: 480, “height”: 360 } } | サムネイル情報。 以下のプロパティを含むオブジェクト。 ・default ・medium ・high ・standard ・maxres ※default・medium・highは必ず含まれるが、standard・maxresは高解像度サムネイルがアップロードされている場合のみ含まれる。 |
| snippet.thumbnails.default | オブジェクト(object) 例: { “url”: “https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg”, “width”: 120, “height”: 90 } | 既定のサムネイル情報。 |
| snippet.thumbnails.default.url | 文字列(string) 例:”https://i.ytimg.com/vi/p6h57WqRRl8/default.jpg” | 既定のサムネイルのURL。 |
| snippet.thumbnails.default.width | 符号なし整数値(unsigned integer) 例:120 例:88 | 既定のサムネイルの横幅。 ※動画とチャンネルでサイズが異なる。動画は120px、チャンネルは88px。 |
| snippet.thumbnails.default.height | 符号なし整数値(unsigned integer) 例:90 例:88 | 既定のサムネイルの高さ。 ※動画とチャンネルでサイズが異なる。動画は90px、チャンネルは88px。 |
| snippet.thumbnails.medium.url | 文字列(string) 例:”https://i.ytimg.com/vi/4Uh02uy3Tlk/mqdefault.jpg” | 中画質のサムネイルのURL。 |
| snippet.thumbnails.medium.width | 符号なし整数値(unsigned integer) 例:320 例:240 | 中画質のサムネイルの横幅。 ※動画とチャンネルでサイズが異なる。動画は320px、チャンネルは240px。 |
| snippet.thumbnails.medium.height | 符号なし整数値(unsigned integer) 例:180 例:240 | 中画質のサムネイルの高さ。 ※動画とチャンネルでサイズが異なる。動画は90px、チャンネルは88px。 |
| snippet.thumbnails.high.url | 文字列(string) 例:”https://i.ytimg.com/vi/4Uh02uy3Tlk/hqdefault.jpg” | 高画質のサムネイルのURL。 |
| snippet.thumbnails.high.width | 符号なし整数値(unsigned integer) 例:480 例:800 | 高画質のサムネイルの横幅。 ※動画とチャンネルでサイズが異なる。動画は480px、チャンネルは800px。 |
| snippet.thumbnails.high.height | 符号なし整数値(unsigned integer) 例:360 例:800 | 高画質のサムネイルの横幅。 ※動画とチャンネルでサイズが異なる。動画は360px、チャンネルは800px。 |
| snippet.thumbnails.standard.url | 文字列(string) 例:”https://i.ytimg.com/vi/Ks-_Mh1QhMc/sddefault.jpg” | 標準画質のサムネイルのURL。 ※高解像度サムネイルがアップロードされている場合のみ含まれる。 ※動画のみ。 |
| snippet.thumbnails.standard.width | 符号なし整数値(unsigned integer) 例:640 | 標準画質のサムネイルの横幅。 ※高解像度サムネイルがアップロードされている場合のみ含まれる。 ※動画のみ。640px。 |
| snippet.thumbnails.standard.height | 符号なし整数値(unsigned integer) 例:480 | 標準画質のサムネイルの横幅。 ※高解像度サムネイルがアップロードされている場合のみ含まれる。 ※動画のみ。480px。 |
| snippet.thumbnails.maxres.url | 文字列(string) 例:”https://i.ytimg.com/vi/Ks-_Mh1QhMc/maxresdefault.jpg” | 最高画質のサムネイルのURL。 ※高解像度サムネイルがアップロードされている場合のみ含まれる。 ※動画のみ。 |
| snippet.thumbnails.maxres.width | 符号なし整数値(unsigned integer) 例:1280 | 最高画質のサムネイルの横幅。 ※高解像度サムネイルがアップロードされている場合のみ含まれる。 ※動画のみ。1,280px。 |
| snippet.thumbnails.maxres.height | 符号なし整数値(unsigned integer) 例:720 | 最高画質のサムネイルの横幅。 ※高解像度サムネイルがアップロードされている場合のみ含まれる。 ※動画のみ。720px。 |
| snippet.channelTitle | 文字列(string) 例:”東宝MOVIEチャンネル” | チャンネルのタイトル。 |
| snippet.liveBroadcastContent | 文字列(string) 以下のいずれかの値が含まれる。 ・upcoming (動画の場合はライブ配信予定の動画、チャンネルの場合はライブ配信予定の動画があること) ・live (動画の場合はライブ配信中の動画、チャンネルの場合はライブ配信中の動画があること) ・none (ライブ配信との関連性なし) | ライブ配信コンテンツとの関連性を示す。 |
| publishTime | RFC 3339形式の日時(datetime) 例:2024-12-31T15:00:00Z (日本時間の2025-01-01 00:00:00) | 公開時間(?)。 publishedAtプロパティと同値(?)。 ※APIを使うと含まれていることが確認できるが、公式リファレンスに明記なし。 ※将来的にどうなるか不明なため、使わない方が良いと思います。 |
無料かつコードなしでAPIを試す
Googleは、APIを無料かつコードなしで試せるように公式ツールを用意してくれています。
その名も「API Explorer」。
YouTube Data APIに限らず、Googleが提供している各種APIを無料かつコードなしで試すことができます。
無制限にAPIを実行できるわけではないですが、お試しやテストに最適のツールなので、ぜひ利用していきましょう。
このブログでも使い方の記事を書いているので、見て試してみてください。
おすすめの関連記事
参考
- Google Cloud公式サイト(Cloud APIs > HTTP ガイドライン)
- Google for Developers公式サイト(ホーム > プロダクト > YouTube > Data API > ガイド)
- Google for Developers公式サイト(ホーム > プロダクト > YouTube > Data API > ガイド > YouTube Data API の概要 > パフォーマンスの最適化)
- Google for Developers公式サイト(ホーム > プロダクト > YouTube > Data API > リファレンス > Search)
- Google for Developers公式サイト(ホーム >プロダクト > Google APIs Explorer)
- IETF Datatracker(RFC 3339)
- Wikipedia(ISO 8601)
- ISO公式サイト(ISO 3166 Country Codes)
- ISO公式サイト(Online Browsing Platform (OBP))
※Country codesラジオボタンを選択後、検索テキストボックスに右側の言語プルダウンに合う言語を入力し、SEARCHボタンを押して検索する。 - Wikipedia(ISO 3166-1)
- ISO公式サイト(ISO 639 Language code)
- アメリカ合衆国議会図書館公式サイト(ISO 639-2 Codes for the Representation of Names of Languages)
- Wikipedia(ISO 639-1コード一覧)






