Retorna um conjunto de resultados de pesquisa que correspondem aos parâmetros de consulta especificados na solicitação de API. Por padrão, um conjunto de resultados da pesquisa identifica os recursos video
, channel
e playlist
correspondentes, mas também é possível configurar consultas para recuperar apenas um tipo específico de recurso.
Impacto da cota: uma chamada para esse método tem um custo de cota de 100 unidades.
Casos de uso comuns
Solicitação
Solicitação HTTP
GET https://www.googleapis.com/youtube/v3/search
Parâmetros
A tabela a seguir lista os parâmetros compatíveis com esta consulta. Todos os parâmetros listados são os parâmetros de consulta.
Parâmetros | ||
---|---|---|
Parâmetros obrigatórios | ||
part |
string O parâmetro part especifica uma lista separada por vírgulas de uma ou mais propriedades de recurso search que serão incluídas pela resposta da API. Defina o valor do parâmetro como snippet .
|
|
Filtros (especifique 0 ou 1 dos seguintes parâmetros) | ||
forContentOwner |
boolean Esse parâmetro só pode ser usado em uma solicitação autorizada adequadamente e se destina exclusivamente a parceiros de conteúdo do YouTube. O parâmetro forContentOwner restringe a pesquisa para recuperar apenas vídeos de propriedade do proprietário do conteúdo identificados pelo parâmetro onBehalfOfContentOwner . Se forContentOwner for definida como verdadeira, a solicitação também precisará atender a estes requisitos:
|
|
forDeveloper |
boolean Esse parâmetro só pode ser usado em uma solicitação autorizada corretamente. O parâmetro forDeveloper restringe a pesquisa para recuperar apenas vídeos enviados pelo aplicativo ou site do desenvolvedor. O servidor da API usa as credenciais de autorização da solicitação para identificar o desenvolvedor. O parâmetro forDeveloper pode ser usado com parâmetros de pesquisa opcionais, como o parâmetro q .Para esse recurso, cada vídeo enviado é marcado automaticamente com o número do projeto associado ao aplicativo do desenvolvedor no Google Developers Console. Quando uma solicitação de pesquisa define o parâmetro forDeveloper como true , o servidor de API usa as credenciais de autorização da solicitação para identificar o desenvolvedor. Portanto, um desenvolvedor pode restringir os resultados a vídeos enviados pelo próprio app ou site, mas não aos vídeos enviados por outros apps ou sites. |
|
forMine |
boolean Esse parâmetro só pode ser usado em uma solicitação autorizada corretamente. O parâmetro forMine restringe a pesquisa para recuperar apenas vídeos de propriedade do usuário autenticado. Se você definir esse parâmetro como true , o valor do parâmetro type também precisará ser definido como video . Além disso, nenhum dos outros parâmetros a seguir pode ser definido na mesma solicitação: videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoPaidProductPlacement , videoSyndicated , videoType . |
|
Parâmetros opcionais | ||
channelId |
string O parâmetro channelId indica que a resposta da API deve conter apenas os recursos criados pelo canal. Observação:os resultados da pesquisa vão ser limitados a 500 vídeos se a solicitação especificar um valor para o parâmetro channelId e definir o valor do parâmetro type como video , mas não definir um dos filtros forContentOwner , forDeveloper ou forMine . |
|
channelType |
string O parâmetro channelType permite restringir uma pesquisa a um tipo específico de canal.Os valores aceitáveis são:
|
|
eventType |
string O parâmetro eventType restringe uma pesquisa para transmitir eventos. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
location |
string O parâmetro location , em conjunto com o parâmetro locationRadius , define uma área geográfica circular e também restringe uma pesquisa a vídeos que especificam, nos metadados deles, uma localização geográfica dentro dessa área. O valor do parâmetro é uma string que especifica coordenadas de latitude/longitude, por exemplo, (37.42307,-122.08427 ).
location , mas também não especificar um valor para o parâmetro locationRadius .Observação:se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .
| |
locationRadius |
string O parâmetro locationRadius , em conjunto com o parâmetro location , define uma área geográfica circular.O valor do parâmetro precisa ser um número de ponto flutuante seguido por uma unidade de medida. As unidades de medida válidas são m , km , ft e mi . Por exemplo, os valores de parâmetro válidos incluem 1500m , 5km , 10000ft e 0.75mi . A API não é compatível com valores de parâmetros locationRadius maiores que 1.000 quilômetros.Observação:para mais informações, consulte a definição do parâmetro location . |
|
maxResults |
unsigned integer O parâmetro maxResults especifica o número máximo de itens que precisam ser retornados no conjunto de resultados. Os valores aceitos são de 0 a 50 . O valor padrão é 5 . |
|
onBehalfOfContentOwner |
string Esse parâmetro só pode ser usado em uma solicitação autorizada corretamente. Observação:esse parâmetro é destinado exclusivamente a parceiros de conteúdo do YouTube. O parâmetro onBehalfOfContentOwner indica que as credenciais de autorização da solicitação identificam um usuário do CMS do YouTube que age em nome do proprietário do conteúdo especificado no valor do parâmetro. Este parâmetro destina-se a parceiros de conteúdo do YouTube que possuem e gerenciam vários canais do YouTube diferentes. Ele permite que os proprietários de conteúdo autentiquem uma vez e tenham acesso a todos os dados de seu canal e de seus vídeos sem ter que fornecer credenciais de autenticação para cada canal. A conta do CMS com a qual o usuário autentica deve estar vinculada ao proprietário do conteúdo do YouTube especificado. |
|
order |
string O parâmetro order especifica o método que será usado para ordenar recursos na resposta da API. O valor padrão é relevance .Os valores aceitáveis são os seguintes:
|
|
pageToken |
string O parâmetro pageToken identifica uma página específica no conjunto de resultados que precisa ser retornada. Em uma resposta da API, as propriedades nextPageToken e prevPageToken identificam outras páginas que podem ser recuperadas. |
|
publishedAfter |
datetime O parâmetro publishedAfter indica que a resposta da API precisa conter apenas os recursos criados no horário especificado ou depois dele. O valor está no formato RFC 3339 de dia/hora (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetime O parâmetro publishedBefore indica que a resposta da API precisa conter apenas os recursos criados antes ou no momento especificado. O valor está no formato RFC 3339 de dia/hora (1970-01-01T00:00:00Z). |
|
q |
string O parâmetro q especifica o termo de consulta a ser pesquisado.Sua solicitação também pode usar os operadores booleanos NOT ( - ) e OR (| ) para excluir vídeos ou para encontrar vídeos associados a um dos vários termos de pesquisa. Por exemplo, para pesquisar vídeos correspondentes a "remo" ou "veleiro", defina o valor do parâmetro q como boating|sailing . Da mesma forma, para pesquisar vídeos que correspondam a "barco" ou "vela", mas não a "pesca", defina o valor do parâmetro q como boating|sailing -fishing . O caractere de barra vertical precisa ter escape de URL quando for enviado na solicitação de API. O valor com escape do URL para a barra vertical é %7C . |
|
regionCode |
string O parâmetro regionCode instrui a API a retornar resultados de pesquisa para vídeos que podem ser visualizados no país especificado. O valor do parâmetro é um código de país ISO 3166-1 alpha-2. |
|
relevanceLanguage |
string O parâmetro relevanceLanguage instrui a API a retornar os resultados da pesquisa mais relevantes para o idioma especificado. O valor do parâmetro normalmente é um código de idioma de duas letras do ISO 639-1. No entanto, use os valores zh-Hans para chinês simplificado e zh-Hant para chinês tradicional. Os resultados em outros idiomas ainda serão retornados se forem altamente relevantes para o termo da consulta de pesquisa. |
|
safeSearch |
string O parâmetro safeSearch indica se os resultados da pesquisa precisam incluir conteúdo restrito e conteúdo padrão.Os valores aceitáveis são os seguintes:
|
|
topicId |
string O parâmetro topicId indica que a resposta da API precisa conter apenas recursos associados ao tópico especificado. O valor identifica um ID de tópico do Freebase.Importante: devido à descontinuação do Freebase e da API do Freebase, o parâmetro topicId começou a funcionar de maneira diferente em 27 de fevereiro de 2017. Naquela época, o YouTube começou a oferecer suporte a um pequeno conjunto de códigos de tópicos selecionados, e você só pode usar esse conjunto menor de códigos como valores para esse parâmetro. |
|
type |
string O parâmetro type restringe uma consulta de pesquisa para recuperar apenas um determinado tipo de recurso. O valor é uma lista separada por vírgulas dos tipos de recursos. O valor padrão é video,channel,playlist .Os valores aceitáveis são os seguintes:
|
|
videoCaption |
string O parâmetro videoCaption indica se a API deve filtrar os resultados da pesquisa de vídeo com base na presença de legendas ou não. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoCategoryId |
string O parâmetro videoCategoryId filtra os resultados da pesquisa de vídeo com base na categoria. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video . |
|
videoDefinition |
string O parâmetro videoDefinition permite restringir uma pesquisa para incluir apenas vídeos de alta definição (HD) ou definição padrão (SD). Vídeos em HD estão disponíveis para reprodução com, pelo menos, 720 p, embora resoluções mais altas, como 1.080 p, também estejam disponíveis. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoDimension |
string O parâmetro videoDimension permite restringir uma pesquisa para recuperar apenas vídeos em 2D ou 3D. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoDuration |
string O parâmetro videoDuration filtra os resultados da pesquisa de vídeo com base na duração. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoEmbeddable |
string O parâmetro videoEmbeddable permite restringir uma pesquisa apenas aos vídeos que podem ser incorporados a uma página da Web. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoLicense |
string O parâmetro videoLicense filtra os resultados da pesquisa para incluir apenas vídeos com uma licença específica. O YouTube permite que os usuários que fazem upload anexem a licença Creative Commons ou a licença padrão do YouTube a cada um de seus vídeos. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoPaidProductPlacement |
string O parâmetro videoPaidProductPlacement filtra os resultados da pesquisa
para incluir apenas os vídeos que o criador de conteúdo indicou como promoção paga. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoSyndicated |
string Com o parâmetro videoSyndicated , é possível restringir uma pesquisa apenas aos vídeos que podem ser reproduzidos fora do youtube.com. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
|
videoType |
string O parâmetro videoType permite restringir uma pesquisa a um tipo específico de vídeo. Se você especificar um valor para esse parâmetro, defina também o valor do parâmetro type como video .Os valores aceitáveis são os seguintes:
|
Corpo da solicitação
Não forneça um corpo de solicitação ao chamar este método.
Resposta
Se for bem-sucedido, esse método retornará um corpo de resposta com esta estrutura:
{ "kind": "youtube#searchListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "regionCode": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ search Resource ] }
Propriedades
A tabela a seguir define as propriedades que aparecem no resultado da busca:
Propriedades | |
---|---|
kind |
string Identifica o tipo do recurso da API. O valor será youtube#searchListResponse . |
etag |
etag A Etag desse recurso. |
nextPageToken |
string O token que pode ser usado como o valor do parâmetro pageToken para recuperar a próxima página no conjunto de resultados. |
prevPageToken |
string O token que pode ser usado como o valor do parâmetro pageToken para recuperar a página anterior do conjunto de resultados. |
regionCode |
string O código de região que foi usado para a consulta de pesquisa. O valor da propriedade é um código ISO de duas letras do país que identifica a região. O método i18nRegions.list retorna uma lista de regiões compatíveis. O valor padrão é US . Se uma região não suportada for especificada, o YouTube ainda poderá selecionar outra região, em vez do valor padrão, para processar a consulta. |
pageInfo |
object O objeto pageInfo encapsula informações de paginação para o conjunto de resultados. |
pageInfo.totalResults |
integer O número total de resultados no conjunto de resultados.O valor é uma aproximação e pode não representar um valor exato. Além disso, o valor máximo é 1.000.000. Não use esse valor para criar links de paginação. Em vez disso, use os valores de propriedade nextPageToken e prevPageToken para determinar se os links de paginação serão exibidos ou não. |
pageInfo.resultsPerPage |
integer O número de resultados incluídos na resposta da API. |
items[] |
list Uma lista de resultados que correspondem aos critérios de pesquisa. |
Exemplos
Observação: os exemplos de código a seguir podem não representar todas as linguagens de programação compatíveis. Consulte a documentação bibliotecas cliente para uma lista das linguagens suportadas.
Apps Script
Esta função procura vídeos relacionados à palavra-chave "cachorros". Os IDs de vídeo e os títulos dos resultados de pesquisa são registrados no registro do Google Script.Essa amostra limita os resultados a 25. Para retornar mais resultados, transmita parâmetros adicionais, conforme documentado aqui: 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
Esse exemplo de código chama o métodosearch.list
da API para recuperar resultados da pesquisa associados a uma palavra-chave específica.
Este exemplo usa a biblioteca de cliente 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
O exemplo de código a seguir chama o métodosearch.list
da API para recuperar os resultados da pesquisa associados a uma determinada palavra-chave.
Este exemplo usa a biblioteca cliente .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
Este exemplo chama o métodosearch.list
da API para recuperar resultados da pesquisa associados a uma palavra-chave específica.
Este exemplo utiliza a biblioteca cliente 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
Erros
A tabela a seguir identifica mensagens de erro que a API pode retornar em resposta a uma chamada a este método. Consulte a documentação mensagem de erro para mais detalhes.
Tipo de erro | Detalhe do erro | Descrição |
---|---|---|
badRequest (400) |
invalidChannelId |
O parâmetro channelId especificou um ID de canal inválido. |
badRequest (400) |
invalidLocation |
O valor do parâmetro location e/ou locationRadius foi formatado incorretamente. |
badRequest (400) |
invalidRelevanceLanguage |
O valor do parâmetro relevanceLanguage foi formatado incorretamente. |
badRequest (400) |
invalidSearchFilter |
A solicitação contém uma combinação inválida de filtros de pesquisa e/ou restrições. É necessário definir o parâmetro type como video se você definir os parâmetros forContentOwner ou forMine como true . Também será necessário definir o parâmetro type como video se você definir um valor para os parâmetros eventType , videoCaption , videoCategoryId , videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoSyndicated ou videoType . |
Confira!
Use o APIs Explorer para chamar essa API e ver a solicitação e a resposta da API.