Renvoie une collection de résultats de recherche qui correspondent aux paramètres de requête spécifiés dans la requête API. Par défaut, un ensemble de résultats de recherche identifie les ressources video
, channel
et playlist
correspondantes, mais vous pouvez également configurer des requêtes pour ne récupérer qu'un type spécifique de ressources.
Quota:un appel à cette méthode applique un coût de quota de 100 unités.
Cas d'utilisation courants
Demande
Requête HTTP :
GET https://www.googleapis.com/youtube/v3/search
Paramètres
Le tableau suivant répertorie les paramètres compatibles avec cette requête. Tous les paramètres listés sont des paramètres de requête.
Paramètres | ||
---|---|---|
Paramètres obligatoires | ||
part |
string Le paramètre part spécifie une liste d'une ou de plusieurs propriétés de ressources search séparées par une virgule, que la réponse de l'API inclura. Définissez la valeur du paramètre sur snippet .
|
|
Filtres (spécifiez 0 ou 1 des paramètres suivants) | ||
forContentOwner |
boolean Ce paramètre ne peut être utilisé que dans une demande autorisée. Il est destiné exclusivement aux partenaires de contenu YouTube. Le paramètre forContentOwner limite la recherche à récupérer uniquement les vidéos appartenant au propriétaire de contenu identifié par le paramètre onBehalfOfContentOwner . Si forContentOwner est défini sur "true", la requête doit également répondre aux exigences suivantes:
|
|
forDeveloper |
boolean Ce paramètre ne peut être utilisé que dans une requête autorisée appropriée. Le paramètre forDeveloper limite la recherche aux vidéos mises en ligne uniquement via l'application ou le site Web du développeur. Le serveur d'API utilise les identifiants d'autorisation de la requête pour identifier le développeur. Le paramètre forDeveloper peut être utilisé conjointement avec des paramètres de recherche facultatifs comme le paramètre q .Pour cette fonctionnalité, chaque vidéo importée est automatiquement taguée avec le numéro de projet associé à l'application du développeur dans la Google Developers Console. Lorsqu'une requête de recherche définit le paramètre forDeveloper sur true , le serveur d'API utilise les identifiants d'autorisation de la requête pour identifier le développeur. Par conséquent, un développeur peut limiter les résultats aux vidéos mises en ligne sur son propre site ou application, mais pas sur celles importées via d'autres applications ou sites. |
|
forMine |
boolean Ce paramètre ne peut être utilisé que dans une requête autorisée appropriée. Le paramètre forMine limite la recherche à ne récupérer que les vidéos appartenant à l'utilisateur authentifié. Si vous définissez ce paramètre sur true , la valeur du paramètre type doit également être définie sur video . De plus, aucun des autres paramètres suivants ne peut être défini dans la même requête: videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoPaidProductPlacement , videoSyndicated , videoType . |
|
Paramètres facultatifs | ||
channelId |
string Le paramètre channelId indique que la réponse de l'API ne doit contenir que des ressources créées par le canal. Remarque:Les résultats de recherche sont limités à 500 vidéos si votre requête spécifie une valeur pour le paramètre channelId et définit la valeur type sur video , mais ne définit pas non plus l'un des filtres forContentOwner , forDeveloper ou forMine . |
|
channelType |
string Le paramètre channelType vous permet de limiter les recherches à un type de canal particulier.Les valeurs acceptées sont les suivantes :
|
|
eventType |
string Le paramètre eventType limite la recherche aux événements de diffusion. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
location |
string Le paramètre location , associé au paramètre locationRadius , définit une zone géographique circulaire et limite la recherche aux vidéos qui spécifient, dans leurs métadonnées, un emplacement géographique compris dans cette zone. La valeur du paramètre est une chaîne spécifiant des coordonnées de latitude/longitude, par exemple (37.42307,-122.08427 ).
location , mais pas pour le paramètre locationRadius .Remarque:Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .
| |
locationRadius |
string Le paramètre locationRadius , associé au paramètre location , définit une zone géographique circulaire.La valeur du paramètre doit être un nombre à virgule flottante suivi d'une unité de mesure. Les unités de mesure valides sont m , km , ft et mi . Par exemple, les valeurs valides pour les paramètres sont 1500m , 5km , 10000ft et 0.75mi . L'API n'accepte pas les valeurs de paramètre locationRadius supérieures à 1 000 kilomètres.Remarque:Pour en savoir plus, consultez la définition du paramètre location . |
|
maxResults |
unsigned integer Le paramètre maxResults spécifie le nombre maximal d'éléments à renvoyer dans l'ensemble de résultats. Les valeurs autorisées vont de 0 à 50 , inclus. La valeur par défaut est 5 . |
|
onBehalfOfContentOwner |
string Ce paramètre ne peut être utilisé que dans une requête autorisée appropriée. Remarque:Ce paramètre est réservé aux partenaires de contenu YouTube. Le paramètre onBehalfOfContentOwner indique que les identifiants d'autorisation de la demande identifient un utilisateur du CMS YouTube qui agit au nom du propriétaire de contenu spécifié dans la valeur du paramètre. Ce paramètre est destiné aux partenaires de contenu YouTube qui possèdent et gèrent de nombreuses chaînes YouTube différentes. Elle permet aux propriétaires de contenu de s'authentifier une seule fois et d'accéder à toutes les données vidéo et de chaîne, sans avoir à fournir d'identifiants pour chaque chaîne. Le compte CMS avec lequel l'utilisateur s'authentifie doit être associé au propriétaire de contenu YouTube spécifié. |
|
order |
string Le paramètre order spécifie la méthode qui sera utilisée pour commander les ressources dans la réponse de l'API. La valeur par défaut est relevance .Les valeurs acceptées sont les suivantes :
|
|
pageToken |
string Le paramètre pageToken identifie une page spécifique à afficher dans l'ensemble de résultats. Dans une réponse de l'API, les propriétés nextPageToken et prevPageToken identifient d'autres pages qui pourraient être récupérées. |
|
publishedAfter |
datetime Le paramètre publishedAfter indique que la réponse de l'API ne doit contenir que des ressources créées à partir du moment spécifié. La valeur est une valeur de date-heure au format RFC 3339 (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetime Le paramètre publishedBefore indique que la réponse de l'API ne doit contenir que des ressources créées avant ou à l'heure spécifiée. La valeur est une valeur de date-heure au format RFC 3339 (1970-01-01T00:00:00Z). |
|
q |
string Le paramètre q spécifie le terme de requête à rechercher.Votre requête peut également utiliser les opérateurs booléens NOT ( - ) et OR (| ) pour exclure des vidéos ou pour trouver des vidéos associées à l'un de ces termes de recherche. Par exemple, pour rechercher des vidéos correspondant à "bateau" ou à "voilier", définissez la valeur du paramètre q sur boating|sailing . De même, pour rechercher les vidéos correspondant à "bateau" ou à "voile", mais pas à "pêche", définissez la valeur du paramètre q sur boating|sailing -fishing . Notez que la barre verticale doit inclure des caractères d'échappement lorsqu'elle est envoyée dans votre requête API. La valeur avec échappement de l'URL pour la barre verticale est %7C . |
|
regionCode |
string Le paramètre regionCode indique à l'API de renvoyer les résultats de recherche pour les vidéos pouvant être visionnées dans le pays indiqué. La valeur du paramètre correspond à un code pays ISO 3166-1 alpha-2. |
|
relevanceLanguage |
string Le paramètre relevanceLanguage indique à l'API de renvoyer les résultats de recherche les plus pertinents pour la langue spécifiée. La valeur du paramètre correspond généralement à un code de langue ISO 639-1 à deux lettres. Cependant, vous devez utiliser les valeurs zh-Hans pour le chinois simplifié et zh-Hant pour le chinois traditionnel. Veuillez noter que les résultats dans d'autres langues s'afficheront toujours s'ils sont très pertinents par rapport au terme de la requête de recherche. |
|
safeSearch |
string Le paramètre safeSearch indique si les résultats de recherche doivent inclure du contenu soumis à des restrictions ainsi que du contenu standard.Les valeurs acceptées sont les suivantes :
|
|
topicId |
string Le paramètre topicId indique que la réponse de l'API ne doit contenir que des ressources associées au sujet spécifié. La valeur identifie un ID de sujet Freebase.Important:En raison de l'abandon de Freebase et de l'API Freebase, le paramètre topicId a commencé à fonctionner différemment à compter du 27 février 2017. À partir de cette date, YouTube a commencé à proposer une sélection limitée d'ID de thèmes. Vous ne pouvez utiliser que cet ID réduit comme valeurs pour ce paramètre. |
|
type |
string Le paramètre type limite une requête de recherche afin de ne récupérer qu'un type de ressource particulier. La valeur est une liste de types de ressources séparés par une virgule. La valeur par défaut est video,channel,playlist .Les valeurs acceptées sont les suivantes :
|
|
videoCaption |
string Le paramètre videoCaption indique si l'API doit filtrer les résultats de recherche vidéo selon qu'ils contiennent ou non des sous-titres. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
videoCategoryId |
string Le paramètre videoCategoryId filtre les résultats de la recherche vidéo en fonction de leur catégorie. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video . |
|
videoDefinition |
string Le paramètre videoDefinition vous permet de limiter la recherche à des vidéos en haute définition (HD) ou en définition standard (SD). Les vidéos HD peuvent être lues en 720p au minimum, mais des résolutions supérieures, comme 1080p, peuvent être disponibles. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
videoDimension |
string Le paramètre videoDimension vous permet de limiter la recherche aux vidéos 2D ou 3D. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
videoDuration |
string Le paramètre videoDuration filtre les résultats de recherche de vidéos en fonction de leur durée. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
videoEmbeddable |
string Le paramètre videoEmbeddable vous permet de limiter votre recherche aux vidéos qui peuvent être intégrées à une page Web. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
videoLicense |
string Le paramètre videoLicense filtre les résultats de recherche pour n'inclure que les vidéos disposant d'une licence spécifique. YouTube permet aux utilisateurs mettant en ligne des vidéos d'associer la licence Creative Commons ou la licence YouTube standard à chacune de leurs vidéos. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
videoPaidProductPlacement |
string Le paramètre videoPaidProductPlacement filtre les résultats de recherche pour n'inclure que les vidéos signalées comme étant des communications commerciales par le créateur. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
|
videoSyndicated |
string Le paramètre videoSyndicated vous permet de limiter votre recherche aux vidéos pouvant être lues en dehors de youtube.com. Si vous spécifiez une valeur pour ce paramètre, vous devez également lui attribuer la valeur video .Les valeurs acceptées sont les suivantes :
type
|
|
videoType |
string Le paramètre videoType vous permet de limiter les recherches à un type de vidéo particulier. Si vous spécifiez une valeur pour ce paramètre, vous devez également définir la valeur du paramètre type sur video .Les valeurs acceptées sont les suivantes :
|
Corps de la requête
Ne fournissez pas de corps de requête lorsque vous appelez cette méthode.
Réponse
Si la requête aboutit, cette méthode renvoie un corps de réponse présentant la structure suivante :
{ "kind": "youtube#searchListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "regionCode": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ search Resource ] }
Propriétés
Le tableau suivant définit les propriétés qui apparaissent dans un résultat de recherche:
Propriétés | |
---|---|
kind |
string Identifie le type de la ressource API. La valeur sera youtube#searchListResponse . |
etag |
etag ETag de cette ressource. |
nextPageToken |
string Jeton pouvant être utilisé comme valeur du paramètre pageToken pour récupérer la page suivante dans l'ensemble de résultats. |
prevPageToken |
string Jeton pouvant être utilisé comme valeur du paramètre pageToken pour récupérer la page précédente dans l'ensemble de résultats. |
regionCode |
string Code régional utilisé pour la requête de recherche. La valeur de la propriété est un code pays ISO à deux lettres qui identifie la région. La méthode i18nRegions.list renvoie la liste des régions acceptées. La valeur par défaut est US . Si une région non acceptée est spécifiée, il se peut que YouTube en sélectionne une autre plutôt que la valeur par défaut pour gérer la requête. |
pageInfo |
object L'objet pageInfo encapsule les informations de pagination pour l'ensemble de résultats. |
pageInfo.totalResults |
integer Nombre total de résultats dans l'ensemble de résultats.Notez que cette valeur est approximative et peut ne pas correspondre à une valeur exacte. De plus, la valeur maximale est de 1 000 000. Vous ne devez pas utiliser cette valeur pour créer des liens de pagination. Utilisez plutôt les valeurs des propriétés nextPageToken et prevPageToken pour déterminer si les liens de pagination doivent être affichés. |
pageInfo.resultsPerPage |
integer Nombre de résultats inclus dans la réponse de l'API. |
items[] |
list Liste de résultats correspondant aux critères de recherche. |
Exemples
Remarque:Les exemples de code suivants peuvent ne pas représenter tous les langages de programmation compatibles. Consultez la documentation sur les bibliothèques clientes pour connaître la liste des langages compatibles.
Apps Script
Cette fonction recherche les vidéos associées au mot clé "chiens". Les ID vidéo et les titres des résultats de recherche sont consignés dans le journal Apps Script.Notez que cet exemple limite les résultats à 25. Pour renvoyer plus de résultats, transmettez des paramètres supplémentaires comme indiqué sur la page suivante: 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
Cet exemple de code appelle la méthodesearch.list
de l'API pour récupérer les résultats de recherche associés à un mot clé particulier.
Cet exemple utilise la bibliothèque 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
L'exemple de code suivant appelle la méthodesearch.list
de l'API pour récupérer les résultats de recherche associés à un mot clé particulier.
Cet exemple utilise la bibliothèque 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
Cet exemple appelle la méthodesearch.list
de l'API pour récupérer les résultats de recherche associés à un mot clé particulier.
Cet exemple utilise la bibliothèque 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
Erreurs
Le tableau suivant identifie les messages d'erreur que l'API peut renvoyer en réponse à un appel à cette méthode. Consultez les messages d'erreur pour en savoir plus.
Type d'erreur | Détails de l'erreur | Description |
---|---|---|
badRequest (400) |
invalidChannelId |
Le paramètre channelId spécifie un ID de chaîne non valide. |
badRequest (400) |
invalidLocation |
Le format des valeurs location et/ou locationRadius n'est pas correct. |
badRequest (400) |
invalidRelevanceLanguage |
La mise en forme de la valeur du paramètre relevanceLanguage est incorrecte. |
badRequest (400) |
invalidSearchFilter |
La requête contient une combinaison non valide de filtres de recherche et/ou de restrictions. Notez que vous devez définir le paramètre type sur video si vous définissez le paramètre forContentOwner ou forMine sur true . Vous devez également définir le paramètre type sur video si vous avez défini une valeur pour les paramètres eventType , videoCaption , videoCategoryId , videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoSyndicated ou videoType . |
Essayer
Utilisez APIs Explorer pour appeler cette API, et consultez la requête et la réponse de l'API.