Muestra una colección de resultados de la búsqueda que coinciden con los parámetros de búsqueda especificados en la solicitud a la API. De forma predeterminada, un conjunto de resultados de búsqueda identifica los recursos video, channel y playlist que coinciden, pero también puedes configurar las consultas para que solo recuperen un tipo específico de recurso.
Impacto de la cuota: Una llamada a este método tiene un costo de cuota de 100 unidades.
Casos de uso habituales
Solicitud
Solicitud HTTP
GET https://www.googleapis.com/youtube/v3/search
Parámetros
En la siguiente tabla, se enumeran los parámetros que admite esta consulta. Todos los parámetros mencionados son parámetros de consulta.
| Parámetros | ||
|---|---|---|
| Parámetros obligatorios | ||
part |
stringEl parámetro part especifica una lista separada por comas de una o más propiedades de recursos de search que la respuesta de API va a incluir. Establece el valor del parámetro en snippet.
|
|
| Filtros (especifica 0 o 1 de los siguientes parámetros) | ||
forContentOwner |
booleanEste parámetro solo se puede utilizar en una solicitud autorizada debidamente y está destinado exclusivamente a socios de contenido de YouTube. El parámetro forContentOwner restringe la búsqueda para recuperar solo los videos que pertenecen al propietario del contenido identificado por el parámetro onBehalfOfContentOwner. Si forContentOwner se establece como verdadero, la solicitud también debe cumplir con estos requisitos:
|
|
forDeveloper |
booleanEste parámetro solo se puede utilizar en una solicitud autorizada debidamente. El parámetro forDeveloper restringe la búsqueda para recuperar solo los videos subidos a través de la aplicación o el sitio web del desarrollador. El servidor de la API usa las credenciales de autorización de la solicitud para identificar al desarrollador. El parámetro forDeveloper se puede usar junto con parámetros de búsqueda opcionales, como el parámetro q.Para esta función, cada video subido se etiqueta automáticamente con el número de proyecto asociado con la aplicación del desarrollador en Google Developers Console. Cuando una solicitud de búsqueda establece el parámetro forDeveloper en true, el servidor de la API usa las credenciales de autorización de la solicitud para identificar al desarrollador. Por lo tanto, un desarrollador puede restringir los resultados a los videos subidos mediante la app o el sitio web del desarrollador, pero no a los videos subidos a través de otras apps o sitios. |
|
forMine |
booleanEste parámetro solo se puede utilizar en una solicitud autorizada debidamente. El parámetro forMine restringe la búsqueda para recuperar solo los videos que pertenecen al usuario autenticado. Si estableces este parámetro en true, el valor del parámetro de type también debe establecerse en video. Además, no se puede establecer ninguno de los siguientes parámetros en la misma solicitud: videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoPaidProductPlacement, videoSyndicated, videoType. |
|
| Parámetros opcionales | ||
channelId |
stringEl parámetro channelId indica que la respuesta de la API solo debe contener recursos creados por el canal. Nota: Los resultados de la búsqueda están limitados a un máximo de 500 videos si tu solicitud especifica un valor para el parámetro channelId y el valor del parámetro type establecido en video, pero no configura uno de los filtros forContentOwner, forDeveloper o forMine. |
|
channelType |
stringEl parámetro channelType te permite restringir una búsqueda a un tipo de canal específico.Los valores aceptables son los siguientes:
|
|
eventType |
stringEl parámetro eventType restringe una búsqueda a los eventos de transmisión. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
location |
stringEl parámetro location, junto con el parámetro locationRadius, define un área geográfica circular y también restringe la búsqueda a videos que especifican, en sus metadatos, una ubicación geográfica que se ubica dentro de esa área. El valor del parámetro es una string que especifica las coordenadas de latitud y longitud, p.ej., (37.42307,-122.08427).
location, pero no especifica un valor para el parámetro locationRadius.Nota: Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.
| |
locationRadius |
stringEl parámetro locationRadius, junto con el parámetro location, define un área geográfica circular.El valor del parámetro debe ser un número de punto flotante seguido de una unidad de medida. Las unidades de medida válidas son m, km, ft y mi. Por ejemplo, los valores de parámetros válidos incluyen 1500m, 5km, 10000ft y 0.75mi. La API no admite valores de parámetros de locationRadius que superen los 1,000 kilómetros.Nota: Consulta la definición del parámetro location para obtener más información. |
|
maxResults |
unsigned integerEl parámetro maxResults especifica la cantidad máxima de elementos que se deben mostrar en el conjunto de resultados. Los valores aceptables son 0 a 50, ambos inclusive. El valor predeterminado es 5. |
|
onBehalfOfContentOwner |
stringEste parámetro solo se puede utilizar en una solicitud autorizada debidamente. Nota: Este parámetro está dirigido exclusivamente a socios de contenido de YouTube. El parámetro onBehalfOfContentOwner indica que las credenciales de autorización de la solicitud identifican a un usuario de CMS de YouTube que actúa en nombre del propietario de contenido especificado en el valor del parámetro. Este parámetro está dirigido a socios de contenido de YouTube que poseen y administran varios canales de YouTube diferentes. Permite a los propietarios del contenido autenticarse una vez y tener acceso a todos los datos de sus videos y canales, sin tener que proporcionar credenciales de autenticación para cada canal. La cuenta de CMS con la que se autentica el usuario debe estar relacionada con el propietario del contenido de YouTube especificado. |
|
order |
stringEl parámetro order especifica el método que se usará para ordenar los recursos en la respuesta de la API. El valor predeterminado es relevance.Los valores aceptables son los siguientes:
|
|
pageToken |
stringEl parámetro pageToken identifica una página específica en el conjunto de resultados que se debe mostrar. En una respuesta de la API, las propiedades nextPageToken y prevPageToken identifican otras páginas que se podrían recuperar. |
|
publishedAfter |
datetimeEl parámetro publishedAfter indica que la respuesta de la API solo debe contener recursos creados en el momento especificado o después. Se trata de un valor de fecha y hora con formato RFC 3339 (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetimeEl parámetro publishedBefore indica que la respuesta de la API solo debe contener recursos creados antes o en el momento especificado. Se trata de un valor de fecha y hora con formato RFC 3339 (1970-01-01T00:00:00Z). |
|
q |
stringEl parámetro q especifica el término de búsqueda que se debe buscar.Tu solicitud también puede usar los operadores booleanos NOT ( -) y OR (|) para excluir videos o buscar videos asociados con uno de varios términos de búsqueda. Por ejemplo, para buscar videos que coincidan con “bote” o “vela”, establece el valor del parámetro q en boating|sailing. Del mismo modo, para buscar videos que coincidan con “bote” o “vela”, pero no con “pesca”, establece el valor del parámetro q en boating|sailing -fishing. Ten en cuenta que el carácter de barra vertical debe tener escape de URL cuando se envíe en tu solicitud a la API. El valor de escape de URL para el carácter de barra es %7C. |
|
regionCode |
stringEl parámetro regionCode indica a la API que muestre los resultados de la búsqueda de los videos que se pueden ver en el país especificado. El valor del parámetro es un código de país ISO 3166-1 alpha-2. |
|
relevanceLanguage |
stringEl parámetro relevanceLanguage le indica a la API que muestre los resultados de la búsqueda más relevantes para el idioma especificado. Por lo general, el valor del parámetro es un código de idioma ISO 639-1 de dos letras. Sin embargo, debes usar los valores zh-Hans para el chino simplificado y zh-Hant para el chino tradicional. Tenga en cuenta que los resultados en otros idiomas se mostrarán si son muy relevantes para el término de búsqueda. |
|
safeSearch |
stringEl parámetro safeSearch indica si los resultados de la búsqueda deben incluir contenido restringido además de contenido estándar.Los valores aceptables son los siguientes:
|
|
topicId |
stringEl parámetro topicId indica que la respuesta de la API solo debe contener recursos asociados con el tema especificado. El valor identifica un ID de tema de Freebase.Importante: Debido a la baja de Freebase y de la API de Freebase, el parámetro topicId comenzó a funcionar de manera diferente desde el 27 de febrero de 2017. En ese momento, YouTube comenzó a admitir un pequeño conjunto de ID de temas seleccionados, y solo puedes usar ese conjunto más pequeño de ID como valores para este parámetro. |
|
type |
stringEl parámetro type restringe una búsqueda para recuperar solo un tipo de recurso en particular. El valor es una lista separada por comas de los tipos de recursos. El valor predeterminado es video,channel,playlist.Los valores aceptables son los siguientes:
|
|
videoCaption |
stringEl parámetro videoCaption indica si la API debe filtrar los resultados de la búsqueda de video en función de si tienen subtítulos. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
videoCategoryId |
stringEl parámetro videoCategoryId filtra los resultados de búsqueda de videos según su categoría. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video. |
|
videoDefinition |
stringEl parámetro videoDefinition te permite restringir una búsqueda para incluir solo videos de alta definición (HD) o de definición estándar (SD). Los videos de alta definición están disponibles para reproducirse en por lo menos 720 píxeles, aunque también puede que estén disponibles resoluciones mayores, como 1080 píxeles. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
videoDimension |
stringEl parámetro videoDimension te permite restringir una búsqueda para recuperar solo videos en 2D o 3D. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
videoDuration |
stringEl parámetro videoDuration filtra los resultados de búsqueda de videos según su duración. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
videoEmbeddable |
stringEl parámetro videoEmbeddable te permite restringir una búsqueda para incluir solo los videos que se pueden incorporar en una página web. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
videoLicense |
stringEl parámetro videoLicense filtra los resultados de la búsqueda para incluir solo los videos con una licencia en particular. YouTube permite a los usuarios que suben videos incluir la licencia de Creative Commons o la licencia estándar de YouTube en cada uno de sus videos. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
videoPaidProductPlacement |
stringEl parámetro videoPaidProductPlacement filtra los resultados de la búsqueda para incluir solo los videos que el creador indicó que tienen una promoción pagada. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Los valores aceptables son los siguientes:
|
|
videoSyndicated |
stringEl parámetro videoSyndicated te permite restringir una búsqueda para que se muestre únicamente a los videos que se puedan reproducir fuera de youtube.com. Si especificas un valor para este parámetro, también debes definir el valor del parámetro type en video.Los valores aceptables son los siguientes:
|
|
videoType |
stringEl parámetro videoType te permite restringir una búsqueda a un tipo específico de videos. Si especificas un valor para este parámetro, también debes establecer el valor del parámetro type en video.Se aceptan los siguientes valores:
|
|
Cuerpo de la solicitud
No proporciones un cuerpo de solicitud cuando invoques este método.
Respuesta
Si se aplica correctamente, este método muestra un cuerpo de respuesta con la siguiente estructura:
{
"kind": "youtube#searchListResponse",
"etag": etag,
"nextPageToken": string,
"prevPageToken": string,
"regionCode": string,
"pageInfo": {
"totalResults": integer,
"resultsPerPage": integer
},
"items": [
search Resource
]
}
Propiedades
La siguiente tabla define las propiedades que aparecen en el resultado de una búsqueda:
| Propiedades | |
|---|---|
kind |
stringIdentifica el tipo de recurso de API. El valor será youtube#searchListResponse. |
etag |
etagEs la etiqueta Etag de este recurso. |
nextPageToken |
stringEs el token que se puede usar como valor del parámetro pageToken para recuperar la página siguiente en el conjunto de resultados. |
prevPageToken |
stringEs el token que se puede usar como valor del parámetro pageToken para recuperar la página anterior en el conjunto de resultados. |
regionCode |
stringEs el código de región que se usó para la búsqueda. El valor de la propiedad es un código de país ISO de dos letras que identifica la región. El método i18nRegions.list muestra una lista de regiones admitidas. El valor predeterminado es US. Si se especifica una región no admitida, es posible que YouTube seleccione otra región (en lugar del valor predeterminado) para controlar la consulta. |
pageInfo |
objectEl objeto pageInfo encapsula la información de paginación del conjunto de resultados. |
pageInfo.totalResults |
integerEs la cantidad total de resultados en el conjunto de resultados.Ten en cuenta que el valor es aproximado y puede no representar un valor exacto. Además, el valor máximo es 1,000,000. No debes usar este valor para crear vínculos de paginación. En su lugar, usa los valores de propiedad nextPageToken y prevPageToken para determinar si se muestran vínculos de paginación. |
pageInfo.resultsPerPage |
integerEs la cantidad de resultados incluidos en la respuesta de la API. |
items[] |
listLista de resultados que coinciden con los criterios de búsqueda. |
Ejemplos
Nota: Es posible que las siguientes muestras de código no representen todos los lenguajes de programación admitidos. Consulta la documentación sobre bibliotecas cliente para obtener una lista de los lenguajes admitidos.
Apps Script
Esta función busca los videos relacionados con la palabra clave "perros". Los ID de video y los títulos de los resultados de la búsqueda se registran en Apps Script.Ten en cuenta que este ejemplo limita los resultados a 25. Para obtener más resultados, pasa parámetros adicionales como se documenta aquí: 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
Esta muestra de código llama al métodosearch.list de la API para recuperar los resultados de búsqueda asociados con una palabra clave específica.
En este ejemplo, se usa la biblioteca cliente de 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
En la siguiente muestra de código, se llama al métodosearch.list de la API para recuperar los resultados de la búsqueda asociados con una palabra clave específica.
En este ejemplo se utiliza la 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
En esta muestra, se llama al métodosearch.list de la API para recuperar los resultados de la búsqueda asociados con una palabra clave específica.
En este ejemplo se utiliza la 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
Errores
En la siguiente tabla, se identifican los mensajes de error que la API podría mostrar en respuesta a una llamada a este método. Consulta la documentación sobre mensajes de error para obtener más información.
| Tipo de error | Detalle del error | Descripción |
|---|---|---|
badRequest (400) |
invalidChannelId |
El parámetro channelId especificó un ID de canal no válido. |
badRequest (400) |
invalidLocation |
El valor del parámetro location o locationRadius tiene un formato incorrecto. |
badRequest (400) |
invalidRelevanceLanguage |
El valor del parámetro relevanceLanguage tiene un formato incorrecto. |
badRequest (400) |
invalidSearchFilter |
La solicitud contiene una combinación no válida de filtros de búsqueda o restricciones. Ten en cuenta que debes establecer el parámetro type en video si estableces los parámetros forContentOwner o forMine en true. También debes establecer el parámetro type en video si configuras un valor para los parámetros eventType, videoCaption, videoCategoryId, videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoSyndicated o videoType. |
Pruébala
Usa APIs Explorer para llamar a esta API y ver la solicitud y la respuesta de la API.