Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching video, channel, and playlist resources, but you can also configure queries to only retrieve a specific type of resource.
Quota impact: A call to this method has a quota cost of 100 units.
Common use cases
Request
HTTP request
GET https://www.googleapis.com/youtube/v3/search
Parameters
The following table lists the parameters that this query supports. All of the parameters listed are query parameters.
| Parameters | ||
|---|---|---|
| Required parameters | ||
| part | stringThe partparameter specifies a comma-separated list of one or moresearchresource properties that the API response will include. Set the parameter value tosnippet. | |
| Filters (specify 0 or 1 of the following parameters) | ||
| forContentOwner | booleanThis parameter can only be used in a properly authorized request, and it is intended exclusively for YouTube content partners. The forContentOwnerparameter restricts the search to only retrieve videos owned by the content owner identified by theonBehalfOfContentOwnerparameter. IfforContentOwneris set to true, the request must also meet these requirements:
 | |
| forDeveloper | booleanThis parameter can only be used in a properly authorized request. The forDeveloperparameter restricts the search to only retrieve videos uploaded via the developer's application or website. The API server uses the request's authorization credentials to identify the developer. TheforDeveloperparameter can be used in conjunction with optional search parameters like theqparameter.For this feature, each uploaded video is automatically tagged with the project number that is associated with the developer's application in the Google Developers Console. When a search request subsequently sets the forDeveloperparameter totrue, the API server uses the request's authorization credentials to identify the developer. Therefore, a developer can restrict results to videos uploaded through the developer's own app or website but not to videos uploaded through other apps or sites. | |
| forMine | booleanThis parameter can only be used in a properly authorized request. The forMineparameter restricts the search to only retrieve videos owned by the authenticated user. If you set this parameter totrue, then thetypeparameter's value must also be set tovideo. In addition, none of the following other parameters can be set in the same request:videoDefinition,videoDimension,videoDuration,videoEmbeddable,videoLicense,videoPaidProductPlacement,videoSyndicated,videoType. | |
| Optional parameters | ||
| channelId | stringThe channelIdparameter indicates that the API response should only contain resources created by the channel.Note: Search results are constrained to a maximum of 500 videos if your request specifies a value for the channelIdparameter and sets thetypeparameter value tovideo, but it does not also set one of theforContentOwner,forDeveloper, orforMinefilters. | |
| channelType | stringThe channelTypeparameter lets you restrict a search to a particular type of channel.Acceptable values are: 
 | |
| eventType | stringThe eventTypeparameter restricts a search to broadcast events. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| location | stringThe locationparameter, in conjunction with thelocationRadiusparameter, defines a circular geographic area and also restricts a search to videos that specify, in their metadata, a geographic location that falls within that area. The parameter value is a string that specifies latitude/longitude coordinates e.g. (37.42307,-122.08427).
 locationparameter but does not also specify a value for thelocationRadiusparameter.Note: If you specify a value for this parameter, you must also set the typeparameter's value tovideo. | |
| locationRadius | stringThe locationRadiusparameter, in conjunction with thelocationparameter, defines a circular geographic area.The parameter value must be a floating point number followed by a measurement unit. Valid measurement units are m,km,ft, andmi. For example, valid parameter values include1500m,5km,10000ft, and0.75mi. The API does not supportlocationRadiusparameter values larger than 1000 kilometers.Note: See the definition of the locationparameter for more information. | |
| maxResults | unsigned integerThe maxResultsparameter specifies the maximum number of items that should be returned in the result set. Acceptable values are0to50, inclusive. The default value is5. | |
| onBehalfOfContentOwner | stringThis parameter can only be used in a properly authorized request. Note: This parameter is intended exclusively for YouTube content partners. The onBehalfOfContentOwnerparameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | |
| order | stringThe orderparameter specifies the method that will be used to order resources in the API response. The default value isrelevance.Acceptable values are: 
 | |
| pageToken | stringThe pageTokenparameter identifies a specific page in the result set that should be returned. In an API response, thenextPageTokenandprevPageTokenproperties identify other pages that could be retrieved. | |
| publishedAfter | datetimeThe publishedAfterparameter indicates that the API response should only contain resources created at or after the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z). | |
| publishedBefore | datetimeThe publishedBeforeparameter indicates that the API response should only contain resources created before or at the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z). | |
| q | stringThe qparameter specifies the query term to search for.Your request can also use the Boolean NOT ( -) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set theqparameter value toboating|sailing. Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set theqparameter value toboating|sailing -fishing. Note that the pipe character must be URL-escaped when it is sent in your API request. The URL-escaped value for the pipe character is%7C. | |
| regionCode | stringThe regionCodeparameter instructs the API to return search results for videos that can be viewed in the specified country. The parameter value is an ISO 3166-1 alpha-2 country code. | |
| relevanceLanguage | stringThe relevanceLanguageparameter instructs the API to return search results that are most relevant to the specified language. The parameter value is typically an ISO 639-1 two-letter language code. However, you should use the valueszh-Hansfor simplified Chinese andzh-Hantfor traditional Chinese. Please note that results in other languages will still be returned if they are highly relevant to the search query term. | |
| safeSearch | stringThe safeSearchparameter indicates whether the search results should include restricted content as well as standard content.Acceptable values are: 
 | |
| topicId | stringThe topicIdparameter indicates that the API response should only contain resources associated with the specified topic. The value identifies a Freebase topic ID.Important: Due to the deprecation of Freebase and the Freebase API, the topicIdparameter started working differently as of February 27, 2017. At that time, YouTube started supporting a small set of curated topic IDs, and you can only use that smaller set of IDs as values for this parameter. | |
| type | stringThe typeparameter restricts a search query to only retrieve a particular type of resource. The value is a comma-separated list of resource types. The default value isvideo,channel,playlist.Acceptable values are: 
 | |
| videoCaption | stringThe videoCaptionparameter indicates whether the API should filter video search results based on whether they have captions. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoCategoryId | stringThe videoCategoryIdparameter filters video search results based on their category. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo. | |
| videoDefinition | stringThe videoDefinitionparameter lets you restrict a search to only include either high definition (HD) or standard definition (SD) videos. HD videos are available for playback in at least 720p, though higher resolutions, like 1080p, might also be available. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoDimension | stringThe videoDimensionparameter lets you restrict a search to only retrieve 2D or 3D videos. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoDuration | stringThe videoDurationparameter filters video search results based on their duration. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoEmbeddable | stringThe videoEmbeddableparameter lets you to restrict a search to only videos that can be embedded into a webpage. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoLicense | stringThe videoLicenseparameter filters search results to only include videos with a particular license. YouTube lets video uploaders choose to attach either the Creative Commons license or the standard YouTube license to each of their videos. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoPaidProductPlacement | stringThe videoPaidProductPlacementparameter filters search results
      to only include videos that the creator has denoted as having a paid promotion. If you specify
      a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoSyndicated | stringThe videoSyndicatedparameter lets you to restrict a search to only videos that can be played outside youtube.com. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
| videoType | stringThe videoTypeparameter lets you restrict a search to a particular type of videos. If you specify a value for this parameter, you must also set thetypeparameter's value tovideo.Acceptable values are: 
 | |
Request body
Do not provide a request body when calling this method.
Response
If successful, this method returns a response body with the following structure:
{
  "kind": "youtube#searchListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "regionCode": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    search Resource
  ]
}Properties
The following table defines the properties that appear in a search result:
| Properties | |
|---|---|
| kind | stringIdentifies the API resource's type. The value will be youtube#searchListResponse. | 
| etag | etagThe Etag of this resource. | 
| nextPageToken | stringThe token that can be used as the value of the pageTokenparameter to retrieve the next page in the result set. | 
| prevPageToken | stringThe token that can be used as the value of the pageTokenparameter to retrieve the previous page in the result set. | 
| regionCode | stringThe region code that was used for the search query. The property value is a two-letter ISO country code that identifies the region. The i18nRegions.listmethod returns a list of supported regions. The default value isUS. If a non-supported region is specified, YouTube might still select another region, rather than the default value, to handle the query. | 
| pageInfo | objectThe pageInfoobject encapsulates paging information for the result set. | 
| pageInfo.totalResults | integerThe total number of results in the result set.Please note that the value is an approximation and may not represent an exact value. In addition, the maximum value is 1,000,000. You should not use this value to create pagination links. Instead, use the nextPageTokenandprevPageTokenproperty values to determine whether to show pagination links. | 
| pageInfo.resultsPerPage | integerThe number of results included in the API response. | 
| items[] | listA list of results that match the search criteria. | 
Examples
Note: The following code samples may not represent all supported programming languages. See the client libraries documentation for a list of supported languages.
Apps Script
This function searches for videos related to the keyword 'dogs'. The video IDs and titles of the search results are logged to Apps Script's log.Note that this sample limits the results to 25. To return more results, pass additional parameters as documented here: 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
This code sample calls the API'ssearch.list method to retrieve search results associated
with a particular keyword.
  This example uses the Go client library.
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
The following code sample calls the API'ssearch.list method to retrieve search results
associated with a particular keyword.
  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
This sample calls the API'ssearch.list method to retrieve search results
associated with a particular keyword.
  This example uses the Ruby client library.
#!/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
Errors
The following table identifies error messages that the API could return in response to a call to this method. Please see the error message documentation for more detail.
| Error type | Error detail | Description | 
|---|---|---|
| badRequest (400) | invalidChannelId | The channelIdparameter specified an invalid channel ID. | 
| badRequest (400) | invalidLocation | The locationand/orlocationRadiusparameter value was formatted incorrectly. | 
| badRequest (400) | invalidRelevanceLanguage | The relevanceLanguageparameter value was formatted incorrectly. | 
| badRequest (400) | invalidSearchFilter | The request contains an invalid combination of search filters and/or restrictions. Note that you must set the typeparameter tovideoif you set either theforContentOwnerorforMineparameters totrue. You must also set thetypeparameter tovideoif you set a value for theeventType,videoCaption,videoCategoryId,videoDefinition,videoDimension,videoDuration,videoEmbeddable,videoLicense,videoSyndicated, orvideoTypeparameters. | 
Try it!
Use the APIs Explorer to call this API and see the API request and response.