Возвращает коллекцию результатов поиска, соответствующих параметрам запроса, указанным в запросе API. По умолчанию набор результатов поиска определяет соответствующие ресурсы video
, channel
и playlist
, но вы также можете настроить запросы на получение только определенного типа ресурса.
Влияние квоты. Стоимость вызова этого метода составляет 100 единиц.
Распространенные случаи использования
Запрос
HTTP-запрос
GET https://www.googleapis.com/youtube/v3/search
Параметры
В следующей таблице перечислены параметры, которые поддерживает этот запрос. Все перечисленные параметры являются параметрами запроса.
Параметры | ||
---|---|---|
Обязательные параметры | ||
part | string Параметр part указывает разделенный запятыми список одного или нескольких свойств search ресурса, которые будут включены в ответ API. Установите значение параметра snippet . | |
Фильтры (укажите 0 или 1 из следующих параметров) | ||
forContentOwner | boolean Этот параметр можно использовать только в должным образом авторизованном запросе и он предназначен исключительно для контент-партнеров YouTube. Параметр forContentOwner ограничивает поиск только поиском видео, принадлежащих владельцу контента, указанному параметром onBehalfOfContentOwner . Если forContentOwner установлено значение true, запрос также должен соответствовать этим требованиям:
| |
forDeveloper | boolean Этот параметр можно использовать только в должным образом авторизованном запросе . Параметр forDeveloper ограничивает поиск только поиском видео, загруженных через приложение или веб-сайт разработчика. Сервер API использует учетные данные авторизации запроса для идентификации разработчика. Параметр forDeveloper можно использовать в сочетании с дополнительными параметрами поиска, такими как параметр q .Для этой функции каждое загруженное видео автоматически помечается номером проекта, который связан с приложением разработчика в консоли разработчиков Google . Когда поисковый запрос впоследствии устанавливает для параметра forDeveloper значение true , сервер API использует учетные данные авторизации запроса для идентификации разработчика. Таким образом, разработчик может ограничить результаты только видео, загруженными через собственное приложение или веб-сайт разработчика, но не видео, загруженными через другие приложения или сайты. | |
forMine | boolean Этот параметр можно использовать только в должным образом авторизованном запросе . Параметр forMine ограничивает поиск только поиском видео, принадлежащих аутентифицированному пользователю. Если для этого параметра установлено значение true , то для параметра type также должно быть установлено значение video . Кроме того, в одном запросе нельзя задать ни один из следующих параметров: videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoPaidProductPlacement , videoSyndicated , videoType . | |
Дополнительные параметры | ||
channelId | string Параметр channelId указывает, что ответ API должен содержать только ресурсы, созданные каналом.Примечание. Результаты поиска ограничены максимум 500 видео, если в вашем запросе указано значение параметра channelId и задано значение параметра type video , но при этом не задается ни один из фильтров forContentOwner , forDeveloper или forMine . | |
channelType | string Параметр channelType позволяет ограничить поиск определенным типом канала.Приемлемые значения:
| |
eventType | string Параметр eventType ограничивает поиск широковещательными событиями. Если вы укажете значение для этого параметра, вы также должны установить значение параметра type video .Приемлемые значения:
| |
location | string Параметр location в сочетании с параметром locationRadius определяет круговую географическую область, а также ограничивает поиск видео, в метаданных которых указано географическое местоположение, попадающее в эту область. Значение параметра представляет собой строку, определяющую координаты широты и долготы, например ( 37.42307,-122.08427 ).
location , но не указано значение параметра locationRadius .Примечание. Если вы укажете значение для этого параметра, вам также необходимо установить значение параметра type video . | |
locationRadius | string Параметр locationRadius в сочетании с параметром location определяет круглую географическую область.Значение параметра должно быть числом с плавающей запятой, за которым следует единица измерения. Допустимые единицы измерения: m , km , ft и mi . Например, допустимые значения параметра включают 1500m , 5km , 10000ft и 0.75mi . API не поддерживает значения параметра locationRadius , превышающие 1000 километров.Примечание. Для получения дополнительной информации см. определение параметра 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 (1970-01-01T00:00:00Z). | |
publishedBefore | datetime publishedBefore указывает, что ответ API должен содержать только ресурсы, созданные до или в указанное время. Значение представляет собой значение даты и времени в формате RFC 3339 (1970-01-01T00:00:00Z). | |
q | string Параметр q указывает термин запроса для поиска.В вашем запросе также можно использовать логические операторы NOT ( - ) и OR ( | ), чтобы исключить видео или найти видео, связанные с одним из нескольких условий поиска. Например, для поиска видео, соответствующих запросу «катание на лодке» или «парусный спорт», установите для параметра q значение boating|sailing . Аналогичным образом, чтобы найти видео, соответствующие «катанию на лодке» или «парусному спорту», но не «рыбалке», установите для параметра q значение boating|sailing -fishing . Обратите внимание, что символ вертикальной черты должен быть экранирован URL-адресом при отправке в запросе API. Экранированное URL-адресом значение символа вертикальной черты — %7C . | |
regionCode | string Параметр regionCode указывает API возвращать результаты поиска видео, которые можно просмотреть в указанной стране. Значением параметра является код страны ISO 3166-1 альфа-2 . | |
relevanceLanguage | string Параметр relevanceLanguage указывает API возвращать результаты поиска, которые наиболее релевантны указанному языку. Значением параметра обычно является двухбуквенный код языка ISO 639-1 . Однако вам следует использовать значения zh-Hans для упрощенного китайского и zh-Hant для традиционного китайского языка. Обратите внимание, что результаты на других языках по-прежнему будут возвращаться, если они очень релевантны поисковому запросу. | |
safeSearch | string Параметр safeSearch указывает, должны ли результаты поиска включать ограниченный контент, а также стандартный контент.Приемлемые значения:
| |
topicId | string Параметр topicId указывает, что ответ API должен содержать только ресурсы, связанные с указанной темой. Значение идентифицирует идентификатор темы Freebase.Важно! Из-за прекращения поддержки Freebase и Freebase API параметр topicId начал работать по-другому с 27 февраля 2017 г. В то время YouTube начал поддерживать небольшой набор идентификаторов курируемых тем, и вы можете использовать только этот меньший набор идентификаторов. Идентификаторы в качестве значений для этого параметра. | |
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 позволяет пользователям, загружающим видео, прикрепить к каждому из своих видео либо лицензию Creative Commons, либо стандартную лицензию 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 Код региона, который использовался для поискового запроса. Значение свойства представляет собой двухбуквенный код страны ISO, идентифицирующий регион. Метод i18nRegions.list возвращает список поддерживаемых регионов. Значение по умолчанию — US . Если указан неподдерживаемый регион, YouTube все равно может выбрать другой регион вместо значения по умолчанию для обработки запроса. |
pageInfo | object Объект pageInfo инкапсулирует информацию о подкачке для набора результатов. |
pageInfo. totalResults | integer Общее количество результатов в наборе результатов. Обратите внимание, что это значение является приблизительным и может не отражать точное значение. Кроме того, максимальное значение составляет 1 000 000. Не следует использовать это значение для создания ссылок на страницы. Вместо этого используйте значения свойств nextPageToken и prevPageToken чтобы определить, следует ли отображать ссылки на страницы. |
pageInfo. resultsPerPage | integer Количество результатов, включенных в ответ API. |
items[] | list Список результатов, соответствующих критериям поиска. |
Примеры
Примечание. Следующие примеры кода могут представлять не все поддерживаемые языки программирования. Список поддерживаемых языков см. в документации клиентских библиотек .
Скрипт приложений
Эта функция ищет видео, связанные с ключевым словом «собаки». Идентификаторы видео и заголовки результатов поиска записываются в журнал 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); } }
Идти
В этом примере кода вызывается метод APIsearch.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") }
.СЕТЬ
В следующем примере кода вызывается метод APIsearch.list
для получения результатов поиска, связанных с определенным ключевым словом.В этом примере используется клиентская библиотека .NET .
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))); } } }
Рубин
В этом примере вызывается метод APIsearch.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 указал недопустимый идентификатор канала. |
badRequest (400) | invalidLocation | Значение параметра location и/или locationRadius было отформатировано неправильно. |
badRequest (400) | invalidRelevanceLanguage | Значение параметра relevanceLanguage было отформатировано неправильно. |
badRequest (400) | invalidSearchFilter | Запрос содержит недопустимую комбинацию поисковых фильтров и/или ограничений. Обратите внимание: вам необходимо установить для параметра type значение video , если для параметра forContentOwner или forMine установлено значение true . Вы также должны установить параметр type на video , если вы установили значение для параметров eventType , videoCaption , videoCategoryId , videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoSyndicated или videoType . |
Попробуй это!
Используйте APIs Explorer для вызова этого API и просмотра запроса и ответа API.