Muestra una colección de resultados de la búsqueda que coinciden con los parámetros de consulta especificados en la solicitud de la API. De forma predeterminada, un conjunto de resultados de búsqueda identifica los recursos video, channel y playlist coincidentes, pero también puedes configurar consultas para que recuperen solo 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 la 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á dirigido 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 configura como verdadero, la solicitud también debe cumplir con estos requisitos:
|
|
forDeveloper |
booleanEste parámetro solo se puede usar en una solicitud autorizada debidamente. El parámetro forDeveloper restringe la búsqueda para recuperar solo los videos subidos mediante la aplicación o el sitio web del desarrollador. El servidor de la API utiliza las credenciales de autorización de la solicitud para identificar al desarrollador. Se puede usar el parámetro forDeveloper junto con los parámetros de búsqueda opcionales, como q.Para esta función, cada video subido se etiqueta automáticamente con el número de proyecto que está 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, el desarrollador puede restringir los resultados a los videos subidos mediante el sitio web o la app del desarrollador, pero no a los videos subidos mediante otras apps o sitios. |
|
forMine |
booleanEste parámetro solo se puede usar 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 type también debe establecerse en video. Además, ninguno de los siguientes parámetros se puede configurar 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 establece el valor del parámetro type en video, pero no establece 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 la 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.Los valores aceptables son los siguientes:
|
|
location |
stringEl parámetro location, junto con el parámetro locationRadius, define un área geográfica circular y también restringe una búsqueda a videos que especifiquen, en sus metadatos, una ubicación geográfica que se encuentre dentro de esa área. El valor del parámetro es una cadena que especifica las coordenadas de latitud y longitud, p.ej., (37.42307,-122.08427).
location, pero no especifica también 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 válidos del parámetro incluyen 1500m, 5km, 10000ft y 0.75mi. La API no admite valores del parámetro locationRadius superiores a 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 usar 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 del 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 a partir del momento especificado. 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 "barco" o "navegación", establece el valor del parámetro q en boating|sailing. De manera similar, para buscar videos que coincidan con "barco" 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 con escape de URL para el carácter de barra vertical es %7C. |
|
regionCode |
stringEl parámetro regionCode le indica a la API que muestre los resultados de la búsqueda de los videos que se pueden mirar 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. Ten en cuenta que se seguirán mostrando resultados en otros idiomas 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 o 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 que Freebase y la API de Freebase dejaron de estar disponibles, el parámetro topicId comenzó a funcionar de manera diferente a partir del 27 de febrero de 2017. En ese momento, YouTube comenzó a admitir un conjunto pequeño de IDs de temas seleccionados, y solo puedes usar ese conjunto más pequeño de IDs como valores para este parámetro. |
|
type |
stringEl parámetro type restringe una búsqueda para recuperar solo un tipo de recurso específico. 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 videos 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.Los valores aceptables son los siguientes:
|
|
videoCategoryId |
stringEl parámetro videoCategoryId filtra los resultados de la búsqueda de videos en función de 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 los videos en alta definición (HD) o 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.Los valores aceptables son los siguientes:
|
|
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.Los valores aceptables son los siguientes:
|
|
videoDuration |
stringEl parámetro videoDuration filtra los resultados de la búsqueda de videos en función de su duración. 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:
|
|
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.Los valores aceptables son los siguientes:
|
|
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.Los valores aceptables son los siguientes:
|
|
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 incluir solo los videos que se pueden reproducir fuera de youtube.com. 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:
|
|
videoType |
stringEl parámetro videoType te permite restringir una búsqueda para incluir un tipo de video específico. 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:
|
|
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 la API. El valor será youtube#searchListResponse. |
etag |
etagLa 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 regional 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 devuelve una lista de regiones compatibles. El valor predeterminado es US. Si se especifica una región no admitida, es posible que YouTube seleccione otra región para administrar la consulta en lugar del valor predeterminado. |
pageInfo |
objectEl objeto pageInfo contiene información de paginación para el conjunto de resultados. |
pageInfo.totalResults |
integerEs la cantidad total de resultados en el conjunto de resultados.Ten en cuenta que el valor es una aproximación y es posible que no represente 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 deben mostrar vínculos de paginación. |
pageInfo.resultsPerPage |
integerCantidad de resultados incluidos en la respuesta de la API. |
items[] |
listUna lista 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 de 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 títulos y los IDs de video de los resultados de la búsqueda se registran en Apps Script.Ten en cuenta que esta muestra limita los resultados a 25. Para que se muestren 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 la búsqueda asociados con una palabra clave en particular.
En este ejemplo, se utiliza 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
La siguiente muestra de código llama al métodosearch.list de la API para recuperar los resultados de la búsqueda asociados con una palabra clave en particular.
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)));
}
}
}
Rita
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 en particular.
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 formato del valor de los parámetros location o locationRadius no es correcto. |
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 estableces un valor para los parámetros eventType, videoCaption, videoCategoryId, videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoSyndicated o videoType. |
Pruébalo
Usa APIs Explorer para llamar a esta API y ver la solicitud y la respuesta a la API.