Возвращает набор результатов поиска, соответствующих параметрам запроса, указанным в запросе 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 Developers Console . Когда поисковый запрос впоследствии устанавливает для параметра forDeveloper значение true , сервер API использует учетные данные авторизации запроса для идентификации разработчика. Таким образом, разработчик может ограничить результаты видео, загруженными через собственное приложение или веб-сайт разработчика, но не видео, загруженными через другие приложения или сайты. | |
forMine | boolean Этот параметр можно использовать только в правильно авторизованном запросе . Параметр forMine ограничивает поиск только теми видео, которые принадлежат аутентифицированному пользователю. Если вы установите для этого параметра значение true , то значение параметра type также должно быть установлено на video . Кроме того, в одном и том же запросе нельзя задать ни один из следующих параметров: videoDefinition , videoDimension , videoDuration , videoLicense , videoEmbeddable , videoSyndicated , videoType . | |
relatedToVideoId | string Параметр relatedToVideoId извлекает список видео, связанных с видео, которое идентифицирует значение параметра. В качестве значения параметра должен быть задан идентификатор видео YouTube, и, если вы используете этот параметр, для параметра type должно быть установлено значение video .Обратите внимание, что если установлен параметр relatedToVideoId , единственными другими поддерживаемыми параметрами являются part , maxResults , pageToken , regionCode , relevanceLanguage , safeSearch , type (который должен быть установлен на video ) и fields . | |
Дополнительные параметры | ||
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 указывает, что учетные данные авторизации запроса идентифицируют пользователя CMS YouTube, который действует от имени владельца контента, указанного в значении параметра. Этот параметр предназначен для контент-партнеров 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 указывает условие запроса для поиска.В вашем запросе также могут использоваться логические операторы НЕ ( - ) и ИЛИ ( | ), чтобы исключить видео или найти видео, связанные с одним из нескольких условий поиска. Например, чтобы найти видео, соответствующие словам «катание на лодке» или «парусный спорт», задайте для параметра q значение boating|sailing . Точно так же, чтобы найти видео, соответствующие словам «катание на лодке» или «парусный спорт», но не «рыбалка», задайте для параметра q значение boating|sailing -fishing . Обратите внимание, что символ вертикальной черты должен быть экранирован URL-адресом, когда он отправляется в запросе API. Значение с экранированием URL для символа вертикальной черты — %7C . | |
regionCode | string Параметр regionCode указывает API возвращать результаты поиска видео, которые можно просмотреть в указанной стране. Значением параметра является код страны ISO 3166-1 alpha-2 . | |
relevanceLanguage | string Параметр relevanceLanguage предписывает API возвращать результаты поиска, наиболее релевантные указанному языку. Значение параметра обычно представляет собой двухбуквенный код языка ISO 639-1 . Однако следует использовать значения zh-Hans для упрощенного китайского и zh-Hant для традиционного китайского. Обратите внимание, что результаты на других языках все равно будут возвращены, если они очень релевантны условиям поискового запроса. | |
safeSearch | string Параметр safeSearch указывает, должны ли результаты поиска включать ограниченное содержимое, а также стандартное содержимое.Допустимые значения:
| |
topicId | string Параметр topicId указывает, что ответ API должен содержать только ресурсы, связанные с указанной темой. Значение определяет идентификатор темы Freebase.Важно! В связи с прекращением поддержки Freebase и API Freebase с 27 февраля 2017 года параметр topicId начал работать по-другому. В то время 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 .Допустимые значения:
| |
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); } }
Идти
Этот пример кода вызывает методsearch.list
API для получения результатов поиска, связанных с определенным ключевым словом.В этом примере используется клиентская библиотека 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 . |
badRequest (400) | invalidVideoId | В параметре relatedToVideo указан недопустимый идентификатор видео. |
Попробуй это!
Используйте APIs Explorer , чтобы вызвать этот API и просмотреть запрос и ответ API.