Restituisce una raccolta di risultati di ricerca che corrispondono ai parametri di ricerca specificati nella richiesta API. Per impostazione predefinita, un set di risultati di ricerca identifica le risorse video, channel e playlist corrispondenti, ma puoi anche configurare query per recuperare solo un tipo specifico di risorsa.
Impatto della quota:una chiamata a questo metodo ha un costo della quota di 100 unità.
Casi d'uso comuni
Richiesta
Richiesta HTTP
GET https://www.googleapis.com/youtube/v3/search
Parametri
La tabella seguente elenca i parametri supportati da questa query. Tutti i parametri elencati sono parametri di ricerca.
| Parametri | ||
|---|---|---|
| Parametri obbligatori | ||
part |
stringIl parametro part specifica un elenco separato da virgole di una o più proprietà search delle risorse che la risposta dell'API includerà. Imposta il valore del parametro su snippet.
|
|
| Filtri (specifica 0 o 1 dei seguenti parametri) | ||
forContentOwner |
booleanQuesto parametro può essere utilizzato solo in una richiesta autorizzata correttamente ed è destinato esclusivamente ai partner di contenuti di YouTube. Il parametro forContentOwner limita la ricerca solo per recuperare i video di proprietà del proprietario dei contenuti identificati dal parametro onBehalfOfContentOwner. Se forContentOwner è impostato su true, la richiesta deve soddisfare anche i seguenti requisiti:
|
|
forDeveloper |
booleanQuesto parametro può essere utilizzato solo in una richiesta autorizzata correttamente. Il parametro forDeveloper consente alla ricerca di recuperare solo i video caricati tramite il sito web o l'applicazione dello sviluppatore. Il server API utilizza le credenziali di autorizzazione della richiesta per identificare lo sviluppatore. Il parametro forDeveloper può essere utilizzato in combinazione con i parametri di ricerca facoltativi come il parametro q.Per questa funzionalità, ogni video caricato viene codificato automaticamente con il numero di progetto associato all'applicazione dello sviluppatore nella Console per gli sviluppatori di Google. Quando una richiesta di ricerca imposta il parametro forDeveloper successivamente su true, il server API utilizza le credenziali di autorizzazione della richiesta per identificare lo sviluppatore. Pertanto, uno sviluppatore può limitare i risultati ai video caricati tramite l'app o il sito web dello sviluppatore stesso, ma non ai video caricati tramite altre app o altri siti. |
|
forMine |
booleanQuesto parametro può essere utilizzato solo in una richiesta autorizzata correttamente. Il parametro forMine limita la ricerca solo per recuperare i video di proprietà dell'utente autenticato. Se imposti questo parametro su true, anche il valore del parametro type deve essere impostato su video. Inoltre, nessuno dei seguenti altri parametri può essere impostato nella stessa richiesta: videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoPaidProductPlacement, videoSyndicated, videoType. |
|
| Parametri facoltativi | ||
channelId |
stringIl parametro channelId indica che la risposta dell'API deve contenere solo risorse create dal canale. Nota: i risultati di ricerca sono limitati a un massimo di 500 video se la tua richiesta specifica un valore per il parametro channelId e il valore del parametro type viene impostato su video, ma non viene impostato anche uno dei filtri forContentOwner, forDeveloper o forMine. |
|
channelType |
stringIl parametro channelType ti consente di limitare una ricerca a un determinato tipo di canale.I valori accettati sono:
|
|
eventType |
stringIl parametro eventType limita una ricerca agli eventi di trasmissione. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
location |
stringIl parametro location, in combinazione con il parametro locationRadius, definisce un'area geografica circolare e limita la ricerca a video che specificano, nei relativi metadati, una posizione geografica che rientra in quell'area. Il valore parametro è una stringa che specifica le coordinate di latitudine/longitudine, ad esempio 37.42307,-122.08427.
location, ma non specifica anche un valore per il parametro locationRadius.Nota: se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.
| |
locationRadius |
stringIl parametro locationRadius, in combinazione con il parametro location, definisce un'area geografica circolare.Il valore del parametro deve essere un numero in virgola mobile seguito da un'unità di misura. Le unità di misura valide sono m, km, ft e mi. Ad esempio, i valori parametro validi includono 1500m, 5km, 10000ft e 0.75mi. L'API non supporta valori di parametri locationRadius superiori a 1000 chilometri.Nota: per ulteriori informazioni, consulta la definizione del parametro location. |
|
maxResults |
unsigned integerIl parametro maxResults specifica il numero massimo di elementi che devono essere restituiti nel set di risultati. I valori accettati sono da 0 a 50 (inclusi). Il valore predefinito è 5. |
|
onBehalfOfContentOwner |
stringQuesto parametro può essere utilizzato solo in una richiesta autorizzata correttamente. Nota: questo parametro è destinato esclusivamente ai partner di contenuti YouTube. Il parametro onBehalfOfContentOwner indica che le credenziali di autorizzazione della richiesta identificano un utente del CMS YouTube che agisce per conto del proprietario dei contenuti specificato nel valore del parametro. Questo parametro è destinato ai partner di contenuti YouTube che possiedono e gestiscono molti canali YouTube diversi. Permette ai proprietari dei contenuti di eseguire l'autenticazione una sola volta e di accedere a tutti i dati relativi a video e canali, senza dover fornire credenziali di autenticazione per ogni singolo canale. L'account CMS con cui l'utente si autentica deve essere collegato al proprietario dei contenuti di YouTube specificato. |
|
order |
stringIl parametro order specifica il metodo che verrà utilizzato per ordinare le risorse nella risposta dell'API. Il valore predefinito è relevance.I valori accettati sono:
|
|
pageToken |
stringIl parametro pageToken identifica una pagina specifica nel set di risultati che deve essere restituita. In una risposta API, le proprietà nextPageToken e prevPageToken identificano altre pagine che potrebbero essere recuperate. |
|
publishedAfter |
datetimeIl parametro publishedAfter indica che la risposta dell'API deve contenere solo risorse create a partire dalla data e dall'ora specificate. Il valore è un valore data/ora formattato RFC 3339 (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetimeIl parametro publishedBefore indica che la risposta dell'API deve contenere solo risorse create prima o al momento specificato. Il valore è un valore data/ora formattato RFC 3339 (1970-01-01T00:00:00Z). |
|
q |
stringIl parametro q specifica il termine di ricerca da cercare.La richiesta può anche utilizzare gli operatori booleani NOT ( -) e OR (|) per escludere video o trovare video associati a uno dei vari termini di ricerca. Ad esempio, per cercare video che corrispondono a "barca" o "barca a vela", imposta il valore del parametro q su boating|sailing. Allo stesso modo, per cercare video che corrispondono a "barca" o "barca a vela" ma non a "pesca", imposta il valore del parametro q su boating|sailing -fishing. Tieni presente che il carattere della barra verticale deve essere sottoposto a escape tramite URL quando viene inviato nella richiesta API. Il valore di escape del carattere barra verticale è %7C. |
|
regionCode |
stringIl parametro regionCode indica all'API di restituire risultati di ricerca per i video che possono essere visualizzati nel paese specificato. Il valore del parametro è un codice paese ISO 3166-1 alpha-2. |
|
relevanceLanguage |
stringIl parametro relevanceLanguage indica all'API di restituire i risultati di ricerca più pertinenti per la lingua specificata. Il valore del parametro è solitamente un codice lingua di due lettere ISO 639-1. Tuttavia, devi utilizzare i valori zh-Hans per il cinese semplificato e zh-Hant per il cinese tradizionale. Tieni presente che i risultati in altre lingue verranno restituiti se sono molto pertinenti al termine della query di ricerca. |
|
safeSearch |
stringIl parametro safeSearch indica se i risultati di ricerca devono includere sia contenuti standard sia contenuti standard.I valori accettati sono:
|
|
topicId |
stringIl parametro topicId indica che la risposta dell'API deve contenere solo risorse associate all'argomento specificato. Il valore identifica un ID argomento Freebase.Importante: a causa del ritiro di Freebase e dell'API Freebase, il parametro topicId ha iniziato a funzionare in modo diverso a partire dal 27 febbraio 2017. In quel momento, YouTube ha iniziato a supportare un piccolo gruppo di ID argomento curati e tu puoi utilizzare solo questo piccolo insieme di ID come valori per questo parametro. |
|
type |
stringIl parametro type limita una query di ricerca per recuperare solo un determinato tipo di risorsa. Il valore è un elenco di tipi di risorse separati da virgole. Il valore predefinito è video,channel,playlist.I valori accettati sono:
|
|
videoCaption |
stringIl parametro videoCaption indica se l'API deve filtrare i risultati di ricerca dei video a seconda che dispongano o meno di sottotitoli. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
videoCategoryId |
stringIl parametro videoCategoryId filtra i risultati di ricerca dei video in base alla loro categoria. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video. |
|
videoDefinition |
stringIl parametro videoDefinition consente di limitare la ricerca in modo da includere solo i video in alta definizione (HD) o standard (SD). I video HD sono disponibili per la riproduzione ad almeno 720p, anche se potrebbero essere disponibili risoluzioni più elevate, ad esempio 1080p. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
videoDimension |
stringIl parametro videoDimension consente di limitare la ricerca solo ai video 2D o 3D. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
videoDuration |
stringIl parametro videoDuration filtra i risultati di ricerca dei video in base alla loro durata. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
videoEmbeddable |
stringIl parametro videoEmbeddable consente di limitare la ricerca solo ai video che possono essere incorporati in una pagina web. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
videoLicense |
stringIl parametro videoLicense filtra i risultati di ricerca per includere solo i video con una licenza specifica. YouTube consente agli utenti che caricano video di allegare la licenza Creative Commons o la licenza YouTube standard a ciascuno dei loro video. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
videoPaidProductPlacement |
stringIl parametro videoPaidProductPlacement filtra i risultati di ricerca per includere solo i video che il creator ha identificato come promozione a pagamento. Se specifichi un valore per questo parametro, devi anche impostare il valore del parametro type su video.I valori accettati sono:
|
|
videoSyndicated |
stringIl parametro videoSyndicated ti consente di limitare la ricerca solo ai video che possono essere riprodotti al di fuori di youtube.com. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
videoType |
stringIl parametro videoType consente di limitare una ricerca a un determinato tipo di video. Se specifichi un valore per questo parametro, devi impostare anche il valore del parametro type su video.I valori accettati sono:
|
|
Corpo della richiesta
Non fornire un corpo della richiesta quando chiami questo metodo.
Risposta
In caso di esito positivo, questo metodo restituisce un corpo di risposta con la seguente struttura:
{
"kind": "youtube#searchListResponse",
"etag": etag,
"nextPageToken": string,
"prevPageToken": string,
"regionCode": string,
"pageInfo": {
"totalResults": integer,
"resultsPerPage": integer
},
"items": [
search Resource
]
}
Proprietà
La tabella seguente definisce le proprietà visualizzate in un risultato di ricerca:
| Proprietà | |
|---|---|
kind |
stringIdentifica il tipo di risorsa API. Il valore sarà youtube#searchListResponse. |
etag |
etagL'Etag di questa risorsa. |
nextPageToken |
stringIl token che può essere utilizzato come valore del parametro pageToken per recuperare la pagina successiva nel set di risultati. |
prevPageToken |
stringIl token che può essere utilizzato come valore del parametro pageToken per recuperare la pagina precedente nel set di risultati. |
regionCode |
stringIl codice regione utilizzato per la query di ricerca. Il valore della proprietà è un codice paese ISO di due lettere che identifica la regione. Il metodo i18nRegions.list restituisce un elenco di regioni supportate. Il valore predefinito è US. Se è specificata una regione non supportata, YouTube potrebbe comunque selezionare un'altra regione anziché il valore predefinito per gestire la query. |
pageInfo |
objectL'oggetto pageInfo incapsula le informazioni di paging per il set di risultati. |
pageInfo.totalResults |
integerIl numero totale di risultati nel set di risultati.Tieni presente che il valore è un'approssimazione e potrebbe non rappresentare un valore esatto. Inoltre, il valore massimo è 1.000.000. Non devi utilizzare questo valore per creare link di impaginazione. Utilizza invece i valori delle proprietà nextPageToken e prevPageToken per determinare se mostrare i link di impaginazione. |
pageInfo.resultsPerPage |
integerIl numero di risultati inclusi nella risposta dell'API. |
items[] |
listUn elenco di risultati che corrispondono ai criteri di ricerca. |
Esempi
Nota: i seguenti esempi di codice potrebbero non rappresentare tutti i linguaggi di programmazione supportati. Consulta la documentazione delle librerie client per un elenco delle lingue supportate.
Apps Script
Questa funzione consente di cercare video correlati alla parola chiave "cani". Gli ID e i titoli dei risultati di ricerca vengono registrati nel log di Apps Script.Tieni presente che questo campione limita i risultati a 25. Per restituire altri risultati, trasmetti parametri aggiuntivi come documentato qui: 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);
}
}
Vai
Questo esempio di codice chiama il metodosearch.list dell'API per recuperare i risultati di ricerca associati a una determinata parola chiave.
In questo esempio viene utilizzata la libreria client di 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
Il seguente esempio di codice chiama il metodosearch.list dell'API per recuperare i risultati di ricerca associati a una determinata parola chiave.
Questo esempio utilizza la libreria client.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
Questo esempio chiama il metodosearch.list dell'API per recuperare i risultati della ricerca associati a una determinata parola chiave.
In questo esempio viene utilizzata la libreria client di 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
Errori
La tabella seguente identifica i messaggi di errore che l'API potrebbe restituire in risposta a una chiamata a questo metodo. Per ulteriori dettagli, consulta la documentazione del messaggio di errore.
| Tipo di errore | Dettagli errore | Descrizione |
|---|---|---|
badRequest (400) |
invalidChannelId |
Il parametro channelId ha specificato un ID canale non valido. |
badRequest (400) |
invalidLocation |
Il formato del parametro location e/o locationRadius non è corretto. |
badRequest (400) |
invalidRelevanceLanguage |
Il formato del parametro relevanceLanguage è errato. |
badRequest (400) |
invalidSearchFilter |
La richiesta contiene una combinazione non valida di filtri di ricerca e/o limitazioni. Tieni presente che devi impostare il parametro type su video se imposti i parametri forContentOwner o forMine su true. Devi anche impostare il parametro type su video se imposti un valore per i parametri eventType, videoCaption, videoCategoryId, videoDefinition, videoDimension, videoDuration, videoEmbeddable, videoLicense, videoSyndicated o videoType. |
Prova.
Usa il APIs Explorer per chiamare questa API e visualizzare la richiesta e la risposta dell'API.