Restituisce una raccolta di risultati di ricerca che corrispondono ai parametri di query 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 le 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 query.
| Parametri | ||
|---|---|---|
| Parametri obbligatori | ||
part |
stringIl parametro part specifica un elenco separato da virgole di una o più proprietà delle risorse search che verranno incluse nella risposta dell'API. Imposta il valore del parametro su snippet.
|
|
| Filtri (specificare 0 o 1 dei seguenti parametri) | ||
forContentOwner |
booleanQuesto parametro può essere utilizzato solo in una richiesta autorizzata opportunamente ed è destinata esclusivamente ai partner dei contenuti di YouTube. Il parametro forContentOwner limita la ricerca di recuperare solo i video di proprietà del proprietario dei contenuti identificato 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 limita la ricerca al solo recupero dei video caricati tramite l'applicazione o il sito web dello sviluppatore. Il server API utilizza le credenziali di autorizzazione della richiesta per identificare lo sviluppatore. Il parametro forDeveloper può essere utilizzato insieme a parametri di ricerca facoltativi come il parametro q.Per questa funzionalità, a ogni video caricato viene assegnato automaticamente il numero di progetto associato all'applicazione dello sviluppatore in Google Developers Console. Quando una richiesta di ricerca in seguito imposta il parametro forDeveloper 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, ma non ai video caricati tramite altri siti o app. |
|
forMine |
booleanQuesto parametro può essere utilizzato solo in una richiesta autorizzata correttamente. Il parametro forMine limita la ricerca al solo recupero dei 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 vincolati a un massimo di 500 video se la tua richiesta specifica un valore per il parametro channelId e imposta il valore parametro type su video, ma non viene impostato anche uno dei filtri forContentOwner, forDeveloper o forMine. |
|
channelType |
stringIl parametro channelType consente di limitare una ricerca a un determinato tipo di canale.I valori accettati sono:
|
|
eventType |
stringIl parametro eventType limita la ricerca alla trasmissione di eventi. Se specifichi un valore per questo parametro, devi anche impostare 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 una ricerca ai video che specificano, nei metadati, una posizione geografica che rientra in quell'area. Il valore del 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, insieme al 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 i valori parametro locationRadius superiori a 1000 chilometri.Nota:per saperne di più, consulta la definizione del parametro location. |
|
maxResults |
unsigned integerIl parametro maxResults specifica il numero massimo di articoli che devono essere restituiti nel set di risultati. I valori accettati sono compresi tra 0 e 50. Il valore predefinito è 5. |
|
onBehalfOfContentOwner |
stringQuesto parametro può essere utilizzato solo in una richiesta autorizzata correttamente. Nota:questo parametro è destinato esclusivamente ai partner dei contenuti di YouTube. Il parametro onBehalfOfContentOwner indica che le credenziali di autorizzazione della richiesta identificano un utente di YouTube CMS che agisce per conto del proprietario dei contenuti specificato nel valore del parametro. Questo parametro è destinato ai partner per i contenuti di YouTube che possiedono e gestiscono molti canali YouTube diversi. Consente ai proprietari dei contenuti di effettuare l'autenticazione una volta sola e ottenere l'accesso 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 esegue l'autenticazione 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 da restituire del set di risultati. In una risposta dell'API, le proprietà nextPageToken e prevPageToken identificano altre pagine che è possibile recuperare. |
|
publishedAfter |
datetimeIl parametro publishedAfter indica che la risposta dell'API deve contenere solo risorse create entro l'orario specificato. Il valore è un valore di data e ora nel formato 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 di data e ora nel formato RFC 3339 (1970-01-01T00:00:00Z). |
|
q |
stringIl parametro q specifica il termine di query da cercare.La tua richiesta può utilizzare anche gli operatori booleani NOT ( -) e OR (|) per escludere i video o trovare quelli associati a uno dei vari termini di ricerca. Ad esempio, per cercare video che corrispondono a "barca" o "vela", imposta il valore parametro q su boating|sailing. Analogamente, per cercare video che corrispondono a "barca" o "vela", ma non a "pesca", imposta il valore del parametro q su boating|sailing -fishing. Tieni presente che il carattere barra verticale deve essere preceduto da URL di escape quando viene inviato nella richiesta API. Il valore URL con escape per il carattere barra verticale è %7C. |
|
regionCode |
stringIl parametro regionCode indica all'API di restituire i 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 è generalmente un codice lingua ISO 639-1 di due lettere. 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 comunque restituiti se sono molto pertinenti al termine della query di ricerca. |
|
safeSearch |
stringIl parametro safeSearch indica se i risultati di ricerca devono includere contenuti con limitazioni oltre a 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. Da allora, YouTube ha iniziato a supportare un piccolo insieme di ID argomento selezionati e tu puoi utilizzare solo quell'insieme più piccolo di ID come valori per questo parametro. |
|
type |
stringIl parametro type limita una query di ricerca a recuperare solo un determinato tipo di risorsa. Il valore è un elenco separato da virgole di tipi di risorse. Il valore predefinito è video,channel,playlist.I valori accettati sono:
|
|
videoCaption |
stringIl parametro videoCaption indica se l'API deve filtrare i risultati di ricerca video in base alla presenza di sottotitoli codificati. Se specifichi un valore per questo parametro, devi anche impostare 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 relativa 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 una ricerca in modo da includere solo i video in alta definizione (HD) o in definizione standard (SD). I video in HD sono disponibili per la riproduzione di almeno 720p, sebbene potrebbero essere disponibili anche risoluzioni più elevate, ad esempio 1080p. Se specifichi un valore per questo parametro, devi anche impostare il valore del parametro type su video.I valori accettati sono:
|
|
videoDimension |
stringIl parametro videoDimension consente di limitare una ricerca ai soli video in 2D o in 3D. Se specifichi un valore per questo parametro, devi anche impostare il valore del parametro type su video.I valori accettati sono:
|
|
videoDuration |
stringIl parametro videoDuration filtra i risultati di ricerca video in base alla durata. Se specifichi un valore per questo parametro, devi anche impostare il valore del parametro type su video.I valori accettati sono:
|
|
videoEmbeddable |
stringIl parametro videoEmbeddable ti consente di limitare una ricerca ai soli video che possono essere incorporati in una pagina web. Se specifichi un valore per questo parametro, devi anche impostare il valore del parametro type su video.I valori accettati sono:
|
|
videoLicense |
stringIl parametro videoLicense filtra i risultati di ricerca in modo da includere solo i video con una licenza specifica. YouTube consente agli utenti che caricano video di scegliere se allegare la licenza Creative Commons o la licenza YouTube standard a ogni video. Se specifichi un valore per questo parametro, devi anche impostare il valore del parametro type su video.I valori accettati sono:
|
|
videoPaidProductPlacement |
stringIl parametro videoPaidProductPlacement filtra i risultati di ricerca
in modo da includere solo i video che il creator ha contrassegnato come promozioni 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 una ricerca ai soli video riproducibili 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 la ricerca a un determinato tipo di video. Se specifichi un valore per questo parametro, devi anche impostare il valore del parametro type su video.I valori accettati sono:
|
|
Corpo della richiesta
Non fornire il corpo della richiesta quando chiami questo metodo.
Risposta
Se l'esito è positivo, questo metodo restituisce un corpo della 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 viene 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 sul 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 relativa alle librerie client per l'elenco dei linguaggi supportati.
Apps Script
Questa funzione cerca video correlati alla parola chiave "cani". Gli ID e i titoli dei video dei risultati di ricerca vengono registrati nel log di Apps Script.Tieni presente che questo campione limita i risultati a 25. Per ottenere più 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);
}
}
Go
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 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.
In questo esempio viene utilizzata 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 di 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 relativa ai messaggi 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 valore parametro location e/o locationRadius non è corretto. |
badRequest (400) |
invalidRelevanceLanguage |
Il formato del valore parametro relevanceLanguage non è corretto. |
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 APIs Explorer per chiamare questa API e visualizzare la richiesta e la risposta dell'API.