API リクエストで指定されたクエリ パラメータに一致する検索結果のコレクションを返します。デフォルトでは、検索結果セットにより一致する video、channel、playlist リソースが識別されますが、特定の種類のリソースのみを取得するようにクエリを構成することもできます。
割り当てへの影響: このメソッドを呼び出すと、100 ユニットの割り当てコストが発生します。
一般的なユースケース
リクエスト
HTTP リクエスト
GET https://www.googleapis.com/youtube/v3/search
パラメータ
次の表に、このクエリでサポートされているパラメータを示します。このリストのパラメータはすべてクエリ パラメータです。
| パラメータ | ||
|---|---|---|
| 必須パラメータ | ||
| part | stringpartパラメータは、API レスポンスに含める 1 つ以上のsearchリソース プロパティをカンマ区切りのリストで指定します。パラメータ値をsnippetに設定します。 | |
| フィルタ(次のパラメータの 0 または 1 を指定) | ||
| forContentOwner | booleanこのパラメータは、適切に承認されたリクエストでのみ使用できます。YouTube コンテンツ パートナー専用です。 forContentOwnerパラメータは、onBehalfOfContentOwnerパラメータで識別されるコンテンツ所有者が所有する動画のみを検索するように制限します。forContentOwnerが true に設定されている場合、リクエストは次の要件も満たしている必要があります。
 | |
| forDeveloper | booleanこのパラメータは、適切に承認されたリクエストでのみ使用できます。 forDeveloperパラメータは、デベロッパーのアプリケーションまたはウェブサイト経由でアップロードされた動画のみを取得するように検索を制限します。API サーバーはリクエストの承認認証情報を使用してデベロッパーを識別します。forDeveloperパラメータは、qパラメータなどのオプションの検索パラメータと組み合わせて使用できます。この機能では、アップロードされた各動画には、Google Developers Console でデベロッパーのアプリケーションに関連付けられているプロジェクト番号が自動的にタグ付けされます。 その後、検索リクエストで forDeveloperパラメータがtrueに設定されると、API サーバーはリクエストの承認認証情報を使用してデベロッパーを識別します。そのため、デベロッパーは、検索結果をデベロッパー自身のアプリやウェブサイト経由でアップロードされた動画に限定できますが、他のアプリやサイト経由でアップロードされた動画に限定することはできません。 | |
| forMine | booleanこのパラメータは、適切に承認されたリクエストでのみ使用できます。 forMineパラメータは、認証されたユーザーが所有する動画のみを取得するように検索を制限します。このパラメータをtrueに設定する場合は、typeパラメータの値もvideoに設定する必要があります。また、他のパラメータvideoDefinition、videoDimension、videoDuration、videoEmbeddable、videoLicense、videoPaidProductPlacement、videoSyndicated、videoTypeを同じリクエストで設定することはできません。 | |
| オプション パラメータ | ||
| channelId | stringchannelIdパラメータは、API レスポンスにチャンネルによって作成されたリソースのみが含まれることを示します。注: リクエストで channelIdパラメータの値を指定し、typeパラメータ値をvideoに設定した場合、forContentOwner、forDeveloper、forMineフィルタのいずれも設定しない場合、検索結果は最大 500 本に制限されます。 | |
| channelType | stringchannelTypeパラメータを使用すると、検索を特定の種類のチャネルに制限できます。有効な値は次のとおりです。 
 | |
| eventType | stringeventTypeパラメータは、検索対象をブロードキャスト イベントに制限します。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| location | stringlocationパラメータはlocationRadiusパラメータと組み合わせて円形の地理的エリアを定義します。また、検索対象を、そのエリア内の地理的位置をメタデータで指定している動画に限定します。パラメータ値は、緯度と経度の座標を指定する文字列です(例:37.42307,-122.08427)。
 locationパラメータの値が指定されていて、locationRadiusパラメータの値も指定されていない場合、API はエラーを返します。注: このパラメータに値を指定する場合は、 typeパラメータの値もvideoに設定する必要があります。 | |
| locationRadius | stringlocationRadiusパラメータはlocationパラメータと組み合わせて円形の地理的エリアを定義します。パラメータ値は、浮動小数点数の後に測定単位を付けて指定する必要があります。有効な測定単位は m、km、ft、miです。たとえば、有効なパラメータ値には1500m、5km、10000ft、0.75miがあります。この API では、1,000 キロメートルを超えるlocationRadiusパラメータ値はサポートされません。注: 詳しくは、 locationパラメータの定義をご覧ください。 | |
| maxResults | unsigned integermaxResultsパラメータは、結果セットで返されるアイテムの最大数を指定します。有効な値は0~50です。デフォルト値は5です。 | |
| onBehalfOfContentOwner | stringこのパラメータは、適切に承認されたリクエストでのみ使用できます。注: このパラメータは YouTube コンテンツ パートナー専用です。 onBehalfOfContentOwnerパラメータは、リクエストの認証情報が、パラメータ値で指定されたコンテンツ所有者の代理である YouTube CMS ユーザーを識別することを示します。このパラメータは、複数の YouTube チャンネルを所有、管理している YouTube コンテンツ パートナーを対象にしています。このパラメータを使用すると、コンテンツ所有者は一度認証されれば、すべての動画やチャンネル データにアクセスできるようになります。チャンネルごとに認証情報を指定する必要はありません。ユーザー認証に使用する CMS アカウントは、指定された YouTube コンテンツ所有者にリンクされていなければなりません。 | |
| order | stringorderパラメータは、API レスポンス内のリソースを並べ替えるために使用するメソッドを指定します。デフォルト値はrelevanceです。指定できる値は次のとおりです。 
 | |
| pageToken | stringpageTokenパラメータは、結果セットの特定のページを返します。API レスポンスでは、nextPageTokenプロパティとprevPageTokenプロパティは取得可能な他のページを示します。 | |
| publishedAfter | datetimepublishedAfterパラメータは、指定した時刻以降に作成されたリソースのみが API レスポンスに含まれることを示します。この値は RFC 3339 形式の date-time 値です(1970-01-01T00:00:00Z)。 | |
| publishedBefore | datetimepublishedBeforeパラメータは、指定した時刻より前または指定した時刻に作成されたリソースのみが API レスポンスに含まれることを示します。この値は RFC 3339 形式の date-time 値です(1970-01-01T00:00:00Z)。 | |
| q | stringqパラメータは、検索する検索キーワードを指定します。リクエストでは、ブール演算子の NOT( -)と OR(|)を使用して、動画を除外したり、複数の検索キーワードのいずれかに関連付けられている動画を検索したりすることもできます。たとえば、「ボート」または「セーリング」のいずれかに一致する動画を検索するには、qパラメータの値をboating|sailingに設定します。同様に、「ボート」または「セーリング」に一致し、「釣り」には一致しない動画を検索するには、qパラメータの値をboating|sailing -fishingに設定します。パイプ文字を API リクエストで送信するときには、URL エスケープする必要があります。パイプ文字の URL エスケープ値は%7Cです。 | |
| regionCode | stringregionCodeパラメータは、指定した国で視聴できる動画の検索結果を返すように API に指示します。パラメータ値は ISO 3166-1 alpha-2 国コードです。 | |
| relevanceLanguage | stringrelevanceLanguageパラメータは、指定された言語に最も関連性のある検索結果を返すように API に指示します。パラメータ値は通常、ISO 639-1 で規定されている 2 文字の言語コードです。ただし、簡体字中国語にはzh-Hans、繁体字中国語にはzh-Hantという値を使用する必要があります。検索キーワードとの関連性が高い場合、他の言語の検索結果も引き続き返されます。 | |
| safeSearch | stringsafeSearchパラメータは、検索結果に標準のコンテンツと制限付きコンテンツのどちらを含めるかを示します。有効な値は次のとおりです。 
 | |
| topicId | stringtopicIdパラメータは、指定したトピックに関連付けられたリソースのみが API レスポンスに含まれることを示します。この値は Freebase トピック ID を識別します。重要: Freebase と Freebase API のサポート終了に伴い、2017 年 2 月 27 日より topicIdパラメータの動作が変わりました。その時点で、YouTube は厳選された少数のトピック ID のサポートを開始しました。このパラメータの値として使用できるのは、その一部の ID のみです。 | |
| type | stringtypeパラメータは、特定の種類のリソースのみを取得するように検索クエリを制限します。値はカンマで区切られたリソースのタイプのリストです。デフォルト値はvideo,channel,playlistです。指定できる値は次のとおりです。 
 | |
| videoCaption | stringvideoCaptionパラメータは、API が字幕の有無に基づいて動画検索結果をフィルタするかどうかを示します。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoCategoryId | stringvideoCategoryIdパラメータは、カテゴリに基づいて動画の検索結果をフィルタリングします。このパラメータの値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。 | |
| videoDefinition | stringvideoDefinitionパラメータを使用すると、高解像度(HD)または標準画質(SD)の動画のみが含まれるように検索を制限できます。HD 動画は 720p 以上で再生できますが、1080p など、より高い解像度を利用できる場合もあります。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoDimension | stringvideoDimensionパラメータを使用すると、2D または 3D 動画のみを取得するように検索を制限できます。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoDuration | stringvideoDurationパラメータは、動画の検索結果を再生時間に基づいてフィルタします。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoEmbeddable | stringvideoEmbeddableパラメータを使用すると、ウェブページに埋め込むことができる動画のみに検索対象を制限できます。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoLicense | stringvideoLicenseパラメータは、特定のライセンスを持つ動画のみが含まれるように検索結果をフィルタします。YouTube では、動画をアップロードするユーザーが各動画にクリエイティブ・コモンズ ライセンスまたは標準の YouTube ライセンスを適用できます。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoPaidProductPlacement | stringvideoPaidProductPlacementパラメータは、クリエイターが有料プロモーションがあると指定した動画のみを含むように検索結果をフィルタリングします。このパラメータの値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoSyndicated | stringvideoSyndicatedパラメータを使用すると、検索対象を youtube.com 以外で再生できる動画のみに制限できます。このパラメータの値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
| videoType | stringvideoTypeパラメータを使用すると、検索を特定のタイプの動画に制限できます。このパラメータに値を指定する場合は、typeパラメータの値もvideoに設定する必要があります。有効な値は次のとおりです。 
 | |
リクエスト本文
このメソッドを呼び出す場合は、リクエストの本文を指定しないでください。
レスポンス
成功すると、このメソッドは次の構造を含むレスポンスの本文を返します。
{
  "kind": "youtube#searchListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "regionCode": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    search Resource
  ]
}
プロパティ
次の表は、検索結果で使用されているプロパティの定義を示したものです。
| プロパティ | |
|---|---|
| kind | stringAPI リソースのタイプを識別します。値は youtube#searchListResponseです。 | 
| etag | etagこのリソースの Etag。 | 
| nextPageToken | string結果セットで次のページを取得するために、 pageTokenパラメータの値として使用できるトークン。 | 
| prevPageToken | string結果セット内の前のページを取得するために、 pageTokenパラメータの値として使用できるトークン。 | 
| regionCode | string検索クエリに使用された地域コード。プロパティ値は、地域を識別する 2 文字の ISO 国コードです。 i18nRegions.listメソッドは、サポートされているリージョンのリストを返します。デフォルト値はUSです。サポートされていない地域が指定されていても、YouTube はクエリを処理するため、デフォルト値ではなく別の地域を選択することがあります。 | 
| pageInfo | objectpageInfoオブジェクトは、結果セットのページング情報をカプセル化します。 | 
| pageInfo.totalResults | integer結果セット内の結果の合計数。この値は近似値であり、正確な値ではない場合があります。また、最大値は 1,000,000 です。 ページ設定リンクの作成にこの値を使用しないでください。代わりに、 nextPageTokenプロパティ値とprevPageTokenプロパティ値を使用して、ページネーション リンクを表示するかどうかを決定します。 | 
| pageInfo.resultsPerPage | integerAPI レスポンスに含まれる結果の数。 | 
| items[] | list検索条件に一致する結果のリスト。 | 
例
注: 次のコードサンプルは、サポートされているプログラミング言語の一部を示しているわけではありません。サポートされている言語の一覧については、クライアント ライブラリのドキュメントをご覧ください。
Apps Script
この関数は、キーワード「dogs」に関連する動画を検索します。検索結果の動画 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 のリクエストとレスポンスを確認します。