Возвращает набор результатов поиска, соответствующих параметрам запроса, указанным в запросе к API. По умолчанию набор результатов поиска определяет соответствующие ресурсы video, channel и playlist, но вы также можете настроить запросы так, чтобы получать только определенный тип ресурса.
Влияние на квоту: 100 вызовов в день. Вызов этого метода расходует 1 единицу квоты на поисковые запросы.
Примеры использования
Запрос
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, 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 не поддерживает значения параметра locationRadius, превышающие 1000 км.Примечание. Подробнее о параметре location… |
|
maxResults |
unsigned integerПараметр maxResults определяет максимальное количество элементов, которые должны быть возвращены в наборе результатов. Допустимые значения: от 0 до 50 включительно. Значение по умолчанию – 5. |
|
onBehalfOfContentOwner |
stringЭтот параметр можно использовать только в авторизованном запросе. Примечание. Этот параметр предназначен исключительно для партнеров YouTube. Параметр onBehalfOfContentOwner указывает, что учетные данные, которые используются для авторизации запроса, идентифицируют пользователя системы управления контентом 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 задает поисковый запрос.В запросе также можно использовать логические операторы НЕ ( -) и ИЛИ (|), чтобы исключить видео или найти видео, связанные с одним из нескольких поисковых запросов. Например, чтобы найти видео, соответствующие запросу "boating" или "sailing", задайте для параметра q значение boating|sailing. Аналогично, чтобы найти видео, соответствующие запросу "boating" или "sailing", но не "fishing", задайте для параметра q значение boating|sailing -fishing. Обратите внимание, что при отправке в запросе к API символ вертикальной черты должен быть экранирован в URL. 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 и Freebase API с 27 февраля 2017 года параметр topicId работает иначе. С этого момента YouTube поддерживает только небольшой набор идентификаторов тем, и в качестве значений этого параметра можно использовать только идентификаторы из этого набора. |
|
type |
stringПараметр type позволяет ограничить поисковый запрос, чтобы получить только определенный тип ресурса. Значение представляет собой список типов ресурсов, разделенных запятыми. Значение по умолчанию – video,channel,playlist.Допустимые значения:
|
|
videoCaption |
stringПараметр videoCaption указывает, нужно ли фильтровать результаты поиска видео по наличию субтитров. Если вы задаете значение для этого параметра, то также должны задать для параметра type значение video.Допустимые значения:
|
|
videoCategoryId |
stringПараметр videoCategoryId позволяет фильтровать результаты поиска видео по категории. Если вы зададите значение для этого параметра, то также должны присвоить параметру type значение video. |
|
videoDefinition |
stringПараметр videoDefinition позволяет ограничить поиск видео только в высоком (HD) или стандартном (SD) разрешении. HD-видео доступны для воспроизведения в разрешении не ниже 720p, а иногда и выше, например 1080p. Если вы указываете значение для этого параметра, то также должны задать значение video для параметра type.Допустимые значения:
|
|
videoDimension |
stringПараметр videoDimension позволяет ограничить поиск только 2D- или 3D-видео. Если вы задаете значение для этого параметра, то также должны задать для параметра type значение video.Допустимые значения:
|
|
videoDuration |
stringПараметр videoDuration позволяет фильтровать результаты поиска видео по их продолжительности. Если вы указываете значение для этого параметра, то также должны задать значение video для параметра type.Допустимые значения:
|
|
videoEmbeddable |
stringПараметр videoEmbeddable позволяет ограничить поиск только видео, которые можно встроить в веб-страницу. Если вы указываете значение для этого параметра, то также должны задать значение video для параметра type.Допустимые значения:
|
|
videoLicense |
stringПараметр videoLicense позволяет отфильтровать результаты поиска, чтобы в них были представлены только видео с определенной лицензией. При загрузке видео на YouTube можно выбрать стандартную лицензию YouTube или лицензию Creative Commons. Если вы указываете значение для этого параметра, то также должны задать значение video для параметра type.Допустимые значения:
|
|
videoPaidProductPlacement |
stringПараметр videoPaidProductPlacement позволяет отфильтровать результаты поиска и оставить только видео, в которых автор отметил наличие прямой рекламы или продакт-плейсмента. Если вы указываете значение для этого параметра, то также должны задать значение video для параметра type.Допустимые значения:
|
|
videoSyndicated |
stringПараметр videoSyndicated позволяет ограничить поиск только теми видео, которые можно воспроизводить за пределами youtube.com. Если вы указываете значение для этого параметра, вы также должны установить значение параметра type равным video.Допустимые значения:
|
|
videoType |
stringПараметр videoType позволяет ограничить поиск определенным типом видео. Если вы указываете значение для этого параметра, то также должны задать значение video для параметра type.Допустимые значения:
|
|
Тело запроса
При вызове этого метода не указывайте тело запроса.
Ответ
В случае успеха метод возвращает тело ответа со следующей структурой:
{
"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
Эта функция ищет видео, связанные с ключевым словом "собаки". Идентификаторы и названия видео из результатов поиска записываются в журнал Apps Script.Обратите внимание, что в этом примере количество результатов ограничено 25. Чтобы получить больше результатов, передайте дополнительные параметры, как описано здесь: https://developers.google.com/youtube/data/reference/rest/v3/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") }
.NET
В приведенном ниже примере кода вызывается методsearch.list API, чтобы получить результаты поиска, связанные с определенным ключевым словом.
В этом примере используется клиентская библиотека.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))); } } }
Ruby
В этом примере вызывается методsearch.list API, чтобы получить результаты поиска, связанные с определенным ключевым словом.
В этом примере используется клиентская библиотека 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 |
Запрос содержит недопустимую комбинацию фильтров поиска и/или ограничений. Обратите внимание, что если для параметра forContentOwner или forMine задано значение true, то для параметра type необходимо задать значение video. Если вы задаете значение для параметров eventType, videoCaption, videoCategoryId, videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoSyndicated или videoType, то также необходимо задать для параметра type значение video. |
Попробовать
Используйте APIs Explorer, чтобы вызвать этот API и посмотреть запрос к API и ответ.