API リクエストで指定されたクエリ パラメータに一致する検索結果のコレクションを返します。デフォルトでは、検索結果セットは一致する video
、channel
、playlist
のリソースを識別しますが、特定のタイプのリソースのみを取得するようにクエリを構成することもできます。
割り当ての影響: このメソッドを呼び出すと、割り当てコストが 100 単位になります。
一般的なユースケース
リクエスト
HTTP リクエスト
GET https://www.googleapis.com/youtube/v3/search
パラメータ
次の表に、このクエリでサポートされているパラメータを示します。このリストのパラメータはすべてクエリ パラメータです。
パラメータ | ||
---|---|---|
必須パラメータ | ||
part |
string part パラメータには、API レスポンスに含める 1 つ以上の search リソース プロパティのカンマ区切りリストを指定します。パラメータ値を snippet に設定します。 |
|
フィルタ(次のパラメータのいずれかまたは 1 つを指定) | ||
forContentOwner |
boolean boolean このパラメータは、適切に承認されたリクエストでのみ使用できます。YouTube コンテンツ パートナー専用です。forContentOwner パラメータは、onBehalfOfContentOwner パラメータで指定されたコンテンツ所有者が所有する動画のみを取得するように検索を制限します。forContentOwner が true に設定されている場合、リクエストは次の要件も満たしている必要があります。
|
|
forDeveloper |
boolean このパラメータは、適切に承認されたリクエストでのみ使用できます。 forDeveloper パラメータは、デベロッパーのアプリケーションまたはウェブサイトからアップロードされた動画のみを検索するように制限します。API サーバーは、リクエストの承認認証情報を使用してデベロッパーを識別します。forDeveloper パラメータは、q パラメータなどのオプションの検索パラメータと組み合わせて使用できます。この機能では、アップロードした各動画に Google Cloud Console でデベロッパーのアプリケーションに関連付けられたプロジェクト番号が自動的にタグ付けされます。 その後、検索リクエストで forDeveloper パラメータが true に設定されると、API サーバーがリクエストの認証情報を使用します。そのため、デベロッパーは、自身のアプリまたはウェブサイトからアップロードされた動画のみに結果を絞り込めます。ただし、他のアプリやウェブサイトからアップロードされた動画に限定することはできません。 |
|
forMine |
boolean このパラメータは、適切に承認されたリクエストでのみ使用できます。 forMine パラメータは、認証済みユーザーが所有する動画のみを取得するように検索を制限します。このパラメータを true に設定する場合は、type パラメータの値も video に設定する必要があります。また、同じリクエストに videoDefinition 、videoDimension 、videoDuration 、videoEmbeddable 、videoLicense 、videoPaidProductPlacement 、videoSyndicated 、videoType のパラメータを設定することはできません。 |
|
オプション パラメータ | ||
channelId |
string channelId パラメータは、API レスポンスにチャネルによって作成されたリソースのみが含まれることを示します。注: リクエストで channelId パラメータの値を指定し、type パラメータ値を video に設定した場合、forContentOwner 、forDeveloper 、forMine のフィルタは設定されず、最大 500 本の動画に制限されます。 |
|
channelType |
string channelType パラメータを使用すると、検索対象を特定のタイプのチャンネルに制限できます。有効な値は次のとおりです。
|
|
eventType |
string eventType パラメータは、検索をブロードキャスト イベントに制限します。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
location |
string location パラメータは locationRadius パラメータと組み合わせて、円形のエリアを定義します。さらに、その領域に含まれる地理的位置をメタデータに指定している動画への検索を制限します。パラメータ値は緯度/経度座標を指定する文字列です(例: 37.42307,-122.08427 )。
location パラメータの値が指定されているものの、locationRadius パラメータの値も指定されていない場合、API はエラーを返します。注: このパラメータの値を指定する場合は、 type パラメータの値を video に設定する必要もあります。 | |
locationRadius |
string locationRadius パラメータは location パラメータと組み合わせて使用し、円形の地理的領域を定義します。パラメータ値には、浮動小数点数の後に測定単位を付加する必要があります。有効な測定単位は m 、km 、ft 、mi です。たとえば、有効なパラメータ値には 1500m 、5km 、10000ft 、0.75mi があります。この API は、1,000 km を超える locationRadius パラメータ値をサポートしていません。注: 詳細については、 location パラメータの定義をご覧ください。 |
|
maxResults |
unsigned integer maxResults パラメータは、結果セットで返されるアイテムの最大数を指定します。指定できる値は 0 ~50 です。デフォルト値は 5 です。 |
|
onBehalfOfContentOwner |
string このパラメータは、適切に承認されたリクエストでのみ使用できます。注: このパラメータは YouTube コンテンツ パートナー専用です。 onBehalfOfContentOwner パラメータは、リクエストで指定された認証情報が、パラメータ値で指定されたコンテンツ所有者の代理として操作する YouTube CMS ユーザーであることを示します。このパラメータは、複数の YouTube チャンネルを所有、管理している YouTube コンテンツ パートナーを対象にしています。このパラメータを使用すると、コンテンツ所有者は一度認証されれば、すべての動画やチャンネル データにアクセスできるようになります。チャンネルごとに認証情報を指定する必要はありません。ユーザー認証に使用する CMS アカウントは、指定された YouTube コンテンツ所有者にリンクされていなければなりません。 |
|
order |
string order パラメータは、API レスポンス内のリソースの並べ替えに使用されるメソッドを指定します。デフォルト値は relevance です。有効な値は次のとおりです。
|
|
pageToken |
string pageToken パラメータは、結果セットで返す必要がある特定のページを示します。API レスポンスでは、nextPageToken プロパティと prevPageToken プロパティは取得可能な他のページを識別します。 |
|
publishedAfter |
datetime publishedAfter パラメータは、指定した時刻以降に作成されたリソースのみを API レスポンスに含める必要があることを示します。この値は RFC 3339 形式の date-time 値です(1970-01-01T00:00:00Z)。 |
|
publishedBefore |
datetime publishedBefore パラメータは、API レスポンスに、指定した日時より前に作成されたリソースのみを含めることを示します。この値は RFC 3339 形式の date-time 値です(1970-01-01T00:00:00Z)。 |
|
q |
string q パラメータでは、検索するクエリ語句を指定します。このリクエストでは、ブール値の NOT( - )演算子と OR(| )演算子を使用して、動画を除外したり、複数の検索キーワードのいずれかに関連付けられている動画を検索したりすることもできます。たとえば、「ボート」または「セーリング」のいずれかに一致する動画を検索するには、q パラメータの値を boating|sailing に設定します。同様に、「ボート」または「セーリング」のいずれかに一致するが「釣り」ではない動画を検索するには、q パラメータの値を boating|sailing -fishing に設定します。API リクエストで送信されたパイプ文字は、URL エスケープする必要があります。パイプ文字の URL エスケープ値は %7C です。 |
|
regionCode |
string regionCode パラメータは、指定した国で視聴可能な動画の検索結果を返すように API に指示します。パラメータ値は ISO 3166-1 alpha-2 国コードです。 |
|
relevanceLanguage |
string relevanceLanguage パラメータは、指定した言語に最も関連性の高い検索結果を返すように API に指示します。通常、パラメータ値は ISO 639-1 の 2 文字の言語コードです。ただし、簡体字中国語の場合は zh-Hans 、繁体字中国語の場合は zh-Hant を使用する必要があります。なお、検索クエリとの関連性が高い場合、他の言語の結果が返されます。 |
|
safeSearch |
string safeSearch パラメータは、検索結果に標準コンテンツに加えて制限付きコンテンツも含めるかどうかを示します。有効な値は次のとおりです。
|
|
topicId |
string topicId パラメータは、API レスポンスに、指定したトピックに関連するリソースのみを含める必要があることを示します。この値は Freebase トピック ID を識別します。重要: Freebase と Freebase API のサポート終了に伴い、2017 年 2 月 27 日から topicId パラメータの動作が変更されました。その時点で、YouTube は厳選された少数のトピック ID のセットをサポートし、このパラメータの値として使用できるようになりました。 |
|
type |
string type パラメータは、検索クエリを特定のタイプのリソースのみに制限します。値はカンマで区切られたリソースのタイプのリストです。デフォルト値は video,channel,playlist です。有効な値は次のとおりです。
|
|
videoCaption |
string videoCaption パラメータは、API が字幕の有無に基づいて動画検索結果をフィルタするかどうかを示します。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
videoCategoryId |
string videoCategoryId パラメータは、カテゴリに基づいて動画検索結果をフィルタします。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要もあります。 |
|
videoDefinition |
string videoDefinition パラメータを使用すると、検索対象を高画質(HD)または標準画質(SD)の動画に限定できます。HD 動画は 720p 以上で視聴できますが、1080p などの高い解像度の場合もあります。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
videoDimension |
string videoDimension パラメータを使用すると、検索対象を 2D 動画または 3D 動画のみに制限できます。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
videoDuration |
string videoDuration パラメータは、再生時間に基づいて動画検索結果をフィルタします。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
videoEmbeddable |
string videoEmbeddable パラメータを使用すると、検索をウェブページに埋め込める動画のみに制限できます。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
videoLicense |
string videoLicense パラメータは、特定のライセンスを持つ動画のみが含まれるように検索結果をフィルタリングします。YouTube では、動画をアップロードするユーザーがそれぞれの動画にクリエイティブ・コモンズ ライセンスまたは標準の YouTube ライセンスのいずれかを選択できるようになっています。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
videoPaidProductPlacement |
string videoPaidProductPlacement パラメータは、検索結果をフィルタして、クリエイターが有料プロモーションであることを示している動画のみを表示します。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
|
videoSyndicated |
string videoSyndicated パラメータを使用すると、youtube.com の外部で再生できる動画のみに検索を制限できます。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定可能な値は次のとおりです。
|
|
videoType |
string videoType パラメータを使用すると、検索対象を特定の種類の動画に限定できます。このパラメータの値を指定する場合は、type パラメータの値を video に設定する必要があります。指定できる値は次のとおりです。
|
リクエスト本文
このメソッドを呼び出す場合は、リクエストの本文を指定しないでください。
レスポンス
成功すると、このメソッドは次の構造を含むレスポンスの本文を返します。
{ "kind": "youtube#searchListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "regionCode": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ search Resource ] }
プロパティ
次の表は、検索結果で使用されているプロパティの定義を示したものです。
プロパティ | |
---|---|
kind |
string API リソースのタイプを示します。値は youtube#searchListResponse です。 |
etag |
etag このリソースの ETag。 |
nextPageToken |
string 結果セットの次のページを取得するために pageToken パラメータの値として使用できるトークン。 |
prevPageToken |
string pageToken パラメータの値として使用できるトークン。結果セットの前のページを取得できます。 |
regionCode |
string 検索クエリに使用された地域コード。プロパティ値は、地域を識別する 2 文字の ISO 国コードです。 i18nRegions.list メソッドは、サポートされているリージョンのリストを返します。デフォルト値は US です。サポートされていないリージョンが指定された場合でも、YouTube はデフォルト値の代わりに、別のリージョンを選択してクエリを処理する可能性があります。 |
pageInfo |
object pageInfo オブジェクトは、結果セットのページ分け情報をカプセル化します。 |
pageInfo.totalResults |
integer 結果セットの合計結果数。値は概算値であり、正確な値ではない場合があります。また、最大値は 1,000,000 です。 ページネーション リンクの作成にはこの値を使用しないでください。代わりに nextPageToken プロパティ値と prevPageToken プロパティ値を使用して、ページネーション リンクを表示するかどうかを決定します。 |
pageInfo.resultsPerPage |
integer API レスポンスに含まれる結果の数。 |
items[] |
list 検索条件と一致する結果のリスト。 |
例
注: 以下のコードサンプルは、サポートされているすべてのプログラミング言語を表しているわけではありません。サポートされている言語の一覧については、クライアント ライブラリのドキュメントをご覧ください。
Apps Script
キーワード「犬」に関連する動画を検索します。検索結果の動画 ID とタイトルは Apps Script のログに記録されます。このサンプルでは、結果が 25 個に制限されています。その他の検索結果を表示するには、https://developers.google.com/youtube/v3/docs/search/list にあるパラメータを追加してください。
function searchByKeyword() { var results = YouTube.Search.list('id,snippet', {q: 'dogs', maxResults: 25}); for(var i in results.items) { var item = results.items[i]; Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title); } }
Go
このコードサンプルは、API のsearch.list
メソッドを呼び出して、特定のキーワードに関連付けられた検索結果を取得します。この例では、Go クライアント ライブラリを使用します。
package main import ( "flag" "fmt" "log" "net/http" "google.golang.org/api/googleapi/transport" "google.golang.org/api/youtube/v3" ) var ( query = flag.String("query", "Google", "Search term") maxResults = flag.Int64("max-results", 25, "Max YouTube results") ) const developerKey = "YOUR DEVELOPER KEY" func main() { flag.Parse() client := &http.Client{ Transport: &transport.APIKey{Key: developerKey}, } service, err := youtube.New(client) if err != nil { log.Fatalf("Error creating new YouTube client: %v", err) } // Make the API call to YouTube. call := service.Search.List("id,snippet"). Q(*query). MaxResults(*maxResults) response, err := call.Do() handleError(err, "") // Group video, channel, and playlist results in separate lists. videos := make(map[string]string) channels := make(map[string]string) playlists := make(map[string]string) // Iterate through each item and add it to the correct list. for _, item := range response.Items { switch item.Id.Kind { case "youtube#video": videos[item.Id.VideoId] = item.Snippet.Title case "youtube#channel": channels[item.Id.ChannelId] = item.Snippet.Title case "youtube#playlist": playlists[item.Id.PlaylistId] = item.Snippet.Title } } printIDs("Videos", videos) printIDs("Channels", channels) printIDs("Playlists", playlists) } // Print the ID and title of each result in a list as well as a name that // identifies the list. For example, print the word section name "Videos" // above a list of video search results, followed by the video ID and title // of each matching video. func printIDs(sectionName string, matches map[string]string) { fmt.Printf("%v:\n", sectionName) for id, title := range matches { fmt.Printf("[%v] %v\n", id, title) } fmt.Printf("\n\n") }
.NET
次のコードサンプルは、API のsearch.list
メソッドを呼び出して、特定のキーワードに関連付けられた検索結果を取得します。This example uses the .NET client library.
using System; using System.Collections.Generic; using System.IO; using System.Reflection; using System.Threading; using System.Threading.Tasks; using Google.Apis.Auth.OAuth2; using Google.Apis.Services; using Google.Apis.Upload; using Google.Apis.Util.Store; using Google.Apis.YouTube.v3; using Google.Apis.YouTube.v3.Data; namespace Google.Apis.YouTube.Samples { /// <summary> /// YouTube Data API v3 sample: search by keyword. /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher. /// See https://developers.google.com/api-client-library/dotnet/get_started /// /// Set ApiKey to the API key value from the APIs & auth > Registered apps tab of /// https://cloud.google.com/console /// Please ensure that you have enabled the YouTube Data API for your project. /// </summary> internal class Search { [STAThread] static void Main(string[] args) { Console.WriteLine("YouTube Data API: Search"); Console.WriteLine("========================"); try { new Search().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("Error: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { var youtubeService = new YouTubeService(new BaseClientService.Initializer() { ApiKey = "REPLACE_ME", ApplicationName = this.GetType().ToString() }); var searchListRequest = youtubeService.Search.List("snippet"); searchListRequest.Q = "Google"; // Replace with your search term. searchListRequest.MaxResults = 50; // Call the search.list method to retrieve results matching the specified query term. var searchListResponse = await searchListRequest.ExecuteAsync(); List<string> videos = new List<string>(); List<string> channels = new List<string>(); List<string> playlists = new List<string>(); // Add each result to the appropriate list, and then display the lists of // matching videos, channels, and playlists. foreach (var searchResult in searchListResponse.Items) { switch (searchResult.Id.Kind) { case "youtube#video": videos.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.VideoId)); break; case "youtube#channel": channels.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.ChannelId)); break; case "youtube#playlist": playlists.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.PlaylistId)); break; } } Console.WriteLine(String.Format("Videos:\n{0}\n", string.Join("\n", videos))); Console.WriteLine(String.Format("Channels:\n{0}\n", string.Join("\n", channels))); Console.WriteLine(String.Format("Playlists:\n{0}\n", string.Join("\n", playlists))); } } }
Ruby
このサンプルは、API のsearch.list
メソッドを呼び出して、特定のキーワードに関連付けられた検索結果を取得します。この例では、Ruby クライアント ライブラリを使用しています。
#!/usr/bin/ruby require 'rubygems' gem 'google-api-client', '>0.7' require 'google/api_client' require 'trollop' # Set DEVELOPER_KEY to the API key value from the APIs & auth > Credentials # tab of # {{ Google Cloud Console }} <{{ https://cloud.google.com/console }}> # Please ensure that you have enabled the YouTube Data API for your project. DEVELOPER_KEY = 'REPLACE_ME' YOUTUBE_API_SERVICE_NAME = 'youtube' YOUTUBE_API_VERSION = 'v3' def get_service client = Google::APIClient.new( :key => DEVELOPER_KEY, :authorization => nil, :application_name => $PROGRAM_NAME, :application_version => '1.0.0' ) youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION) return client, youtube end def main opts = Trollop::options do opt :q, 'Search term', :type => String, :default => 'Google' opt :max_results, 'Max results', :type => :int, :default => 25 end client, youtube = get_service begin # Call the search.list method to retrieve results matching the specified # query term. search_response = client.execute!( :api_method => youtube.search.list, :parameters => { :part => 'snippet', :q => opts[:q], :maxResults => opts[:max_results] } ) videos = [] channels = [] playlists = [] # Add each result to the appropriate list, and then display the lists of # matching videos, channels, and playlists. search_response.data.items.each do |search_result| case search_result.id.kind when 'youtube#video' videos << "#{search_result.snippet.title} (#{search_result.id.videoId})" when 'youtube#channel' channels << "#{search_result.snippet.title} (#{search_result.id.channelId})" when 'youtube#playlist' playlists << "#{search_result.snippet.title} (#{search_result.id.playlistId})" end end puts "Videos:\n", videos, "\n" puts "Channels:\n", channels, "\n" puts "Playlists:\n", playlists, "\n" rescue Google::APIClient::TransmissionError => e puts e.result.body end end main
エラー
次の表に、このメソッドを呼び出す際に API が返すエラー メッセージを示します。詳細については、エラー メッセージのドキュメントを参照してください。
エラーのタイプ | エラーの詳細 | 説明 |
---|---|---|
badRequest (400) |
invalidChannelId |
channelId パラメータで無効なチャンネル ID が指定されています。 |
badRequest (400) |
invalidLocation |
location または locationRadius (あるいはその両方)のパラメータ値の形式が正しくありません。 |
badRequest (400) |
invalidRelevanceLanguage |
relevanceLanguage パラメータ値の形式が正しくありません。 |
badRequest (400) |
invalidSearchFilter |
リクエストに検索フィルタや制限の組み合わせが無効です。forContentOwner パラメータまたは forMine パラメータを true に設定する場合は、type パラメータを video に設定する必要があります。また、eventType 、videoCaption 、videoCategoryId 、videoDefinition 、videoDimension 、videoDuration 、videoEmbeddable 、videoLicense 、videoSyndicated または videoType パラメータの値を設定する場合は、type パラメータを video に設定する必要があります。 |
実習
APIs Explorer を使用してこの API を呼び出し、API リクエストとレスポンスを確認します。