Menampilkan kumpulan hasil penelusuran yang cocok dengan parameter kueri yang ditentukan dalam permintaan API. Secara default, kumpulan hasil penelusuran mengidentifikasi resource video
, channel
, dan playlist
yang cocok, tetapi Anda juga dapat mengonfigurasi kueri untuk hanya mengambil jenis resource tertentu.
Dampak kuota: Panggilan ke metode ini memiliki biaya kuota sebesar 100 unit.
Kasus penggunaan umum
Permintaan
Permintaan HTTP
GET https://www.googleapis.com/youtube/v3/search
Parameter
Tabel berikut mencantumkan parameter yang didukung kueri ini. Semua parameter yang tercantum adalah parameter kueri.
Parameter | ||
---|---|---|
Parameter yang diperlukan | ||
part |
string Parameter part menentukan daftar yang dipisahkan koma untuk satu atau beberapa properti resource search yang akan disertakan oleh respons API. Tetapkan parameter value ke snippet .
|
|
Filter (tentukan 0 atau 1 dari parameter berikut) | ||
forContentOwner |
boolean Parameter ini hanya dapat digunakan dalam permintaan resmi yang benar, dan hanya ditujukan untuk partner konten YouTube. Parameter forContentOwner membatasi penelusuran agar hanya mengambil video yang dimiliki oleh pemilik konten yang diidentifikasi oleh parameter onBehalfOfContentOwner . Jika forContentOwner disetel ke benar (true), permintaan juga harus memenuhi persyaratan berikut:
|
|
forDeveloper |
boolean Parameter ini hanya dapat digunakan dalam permintaan resmi dengan benar. Parameter forDeveloper membatasi penelusuran agar hanya mengambil video yang diupload melalui aplikasi atau situs developer. Server API menggunakan kredensial otorisasi permintaan untuk mengidentifikasi developer. Parameter forDeveloper dapat digunakan bersama dengan parameter penelusuran opsional seperti parameter q .Untuk fitur ini, setiap video yang diupload akan otomatis diberi tag dengan nomor project yang dikaitkan dengan aplikasi developer di Google Developers Console. Saat permintaan penelusuran menetapkan parameter forDeveloper ke true , server API menggunakan kredensial otorisasi permintaan untuk mengidentifikasi developer. Oleh karena itu, developer dapat membatasi hasil ke video yang diupload melalui aplikasi atau situs developer sendiri, tetapi tidak ke video yang diupload melalui aplikasi atau situs lain. |
|
forMine |
boolean Parameter ini hanya dapat digunakan dalam permintaan resmi dengan benar. Parameter forMine membatasi penelusuran agar hanya mengambil video yang dimiliki oleh pengguna yang diautentikasi. Jika Anda menyetel parameter ini ke true , nilai parameter type juga harus ditetapkan ke video . Selain itu, tidak ada parameter lain berikut yang dapat ditetapkan dalam permintaan yang sama: videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoPaidProductPlacement , videoSyndicated , videoType . |
|
Parameter opsional | ||
channelId |
string Parameter channelId menunjukkan bahwa respons API hanya boleh berisi resource yang dibuat oleh saluran. Catatan: Hasil penelusuran dibatasi hingga maksimum 500 video jika permintaan Anda menentukan nilai untuk parameter channelId dan menyetel nilai parameter type ke video , tetapi tidak menetapkan salah satu filter forContentOwner , forDeveloper , atau forMine . |
|
channelType |
string Parameter channelType memungkinkan Anda membatasi penelusuran ke jenis saluran tertentu.Nilai yang dapat diterima adalah:
|
|
eventType |
string Parameter eventType membatasi penelusuran ke peristiwa siaran. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
location |
string Parameter location , bersama dengan parameter locationRadius , menentukan area geografis melingkar dan juga membatasi penelusuran ke video yang menentukan, dalam metadatanya, lokasi geografis yang berada dalam area tersebut. Nilai parameter adalah string yang menentukan koordinat lintang/bujur, misalnya (37.42307,-122.08427 ).
location , tetapi tidak menentukan nilai untuk parameter locationRadius .Catatan: Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .
| |
locationRadius |
string Parameter locationRadius , bersama dengan parameter location , menentukan area geografis melingkar.Nilai parameter harus berupa bilangan floating point yang diikuti dengan unit pengukuran. Unit pengukuran yang valid adalah m , km , ft , dan mi . Misalnya, nilai parameter yang valid mencakup 1500m , 5km , 10000ft , dan 0.75mi . API tidak mendukung nilai parameter locationRadius yang lebih besar dari 1.000 kilometer.Catatan: Lihat definisi parameter location untuk informasi selengkapnya. |
|
maxResults |
unsigned integer Parameter maxResults menentukan jumlah item maksimum yang harus ditampilkan di set hasil. Nilai yang dapat diterima adalah 0 hingga 50 , inklusif. Nilai default-nya adalah 5 . |
|
onBehalfOfContentOwner |
string Parameter ini hanya dapat digunakan dalam permintaan resmi dengan benar. Catatan: Parameter ini ditujukan secara eksklusif untuk partner konten YouTube. Parameter onBehalfOfContentOwner menunjukkan bahwa kredensial otorisasi permintaan mengidentifikasi pengguna CMS YouTube yang bertindak atas nama pemilik konten yang ditentukan dalam nilai parameter. Parameter ini ditujukan untuk partner konten YouTube yang memiliki dan mengelola berbagai channel YouTube. Tindakan ini memungkinkan pemilik konten mengautentikasi satu kali dan mendapatkan akses ke semua data video dan channel mereka, tanpa harus memberikan kredensial autentikasi untuk setiap channel. Akun CMS yang diautentikasi pengguna harus ditautkan ke pemilik konten YouTube yang ditentukan. |
|
order |
string Parameter order menentukan metode yang akan digunakan untuk mengurutkan resource dalam respons API. Nilai defaultnya adalah relevance .Nilai yang dapat diterima adalah:
|
|
pageToken |
string Parameter pageToken mengidentifikasi halaman tertentu dalam set hasil yang harus ditampilkan. Dalam respons API, properti nextPageToken dan prevPageToken mengidentifikasi halaman lain yang dapat diambil. |
|
publishedAfter |
datetime Parameter publishedAfter menunjukkan bahwa respons API hanya boleh berisi resource yang dibuat pada atau setelah waktu yang ditentukan. Nilainya adalah nilai tanggal dan waktu berformat RFC 3339 (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetime Parameter publishedBefore menunjukkan bahwa respons API hanya boleh berisi resource yang dibuat sebelum atau pada waktu yang ditentukan. Nilainya adalah nilai tanggal dan waktu berformat RFC 3339 (1970-01-01T00:00:00Z). |
|
q |
string Parameter q menentukan istilah kueri yang akan ditelusuri.Permintaan Anda juga dapat menggunakan operator Boolean NOT ( - ) dan OR (| ) untuk mengecualikan video atau untuk menemukan video yang terkait dengan salah satu dari beberapa istilah penelusuran. Misalnya, untuk menelusuri video yang cocok dengan "berlayar" atau "berlayar", tetapkan nilai parameter q ke boating|sailing . Demikian pula, untuk menelusuri video yang cocok dengan "berlayar" atau "berlayar", tetapi bukan "memancing", tetapkan nilai parameter q ke boating|sailing -fishing . Perhatikan bahwa karakter pipa harus di-escape melalui URL saat dikirim dalam permintaan API Anda. Nilai yang di-escape URL untuk karakter pipa adalah %7C . |
|
regionCode |
string Parameter regionCode menginstruksikan API untuk menampilkan hasil penelusuran video yang dapat dilihat di negara yang ditentukan. Nilai parameternya adalah kode negara ISO 3166-1 alpha-2. |
|
relevanceLanguage |
string Parameter relevanceLanguage menginstruksikan API untuk menampilkan hasil penelusuran yang paling relevan dengan bahasa yang ditentukan. Nilai parameter biasanya adalah kode bahasa dua huruf ISO 639-1. Namun, Anda harus menggunakan nilai zh-Hans untuk bahasa China yang disederhanakan, dan zh-Hant untuk bahasa China tradisional. Perlu diketahui bahwa hasil dalam bahasa lain akan tetap ditampilkan jika sangat relevan dengan istilah kueri penelusuran. |
|
safeSearch |
string Parameter safeSearch menunjukkan apakah hasil penelusuran harus menyertakan konten yang dibatasi serta konten standar.Nilai yang dapat diterima adalah:
|
|
topicId |
string Parameter topicId menunjukkan bahwa respons API hanya boleh berisi resource yang terkait dengan topik yang ditentukan. Nilai ini mengidentifikasi ID topik Freebase.Penting: Karena penghentian Freebase dan Freebase API, parameter topicId mulai berfungsi secara berbeda mulai 27 Februari 2017. Pada saat itu, YouTube mulai mendukung sekumpulan kecil ID topik hasil seleksi, dan Anda hanya dapat menggunakan kumpulan ID yang lebih kecil tersebut sebagai nilai untuk parameter ini. |
|
type |
string Parameter type membatasi kueri penelusuran untuk hanya mengambil jenis resource tertentu. Nilainya berupa daftar jenis resource yang dipisahkan koma. Nilai defaultnya adalah video,channel,playlist .Nilai yang dapat diterima adalah:
|
|
videoCaption |
string Parameter videoCaption menunjukkan apakah API harus memfilter hasil penelusuran video berdasarkan apakah video tersebut memiliki teks atau tidak. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
videoCategoryId |
string Parameter videoCategoryId memfilter hasil penelusuran video berdasarkan kategori. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video . |
|
videoDefinition |
string Parameter videoDefinition memungkinkan Anda membatasi penelusuran agar hanya menyertakan video definisi tinggi (HD) atau definisi standar (SD). Video HD dapat diputar minimal dalam 720p, meskipun resolusi yang lebih tinggi, seperti 1080p, mungkin juga tersedia. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
videoDimension |
string Parameter videoDimension memungkinkan Anda membatasi penelusuran untuk hanya mengambil video 2D atau 3D. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
videoDuration |
string Parameter videoDuration memfilter hasil penelusuran video berdasarkan durasinya. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
videoEmbeddable |
string Parameter videoEmbeddable memungkinkan Anda membatasi penelusuran hanya pada video yang dapat disematkan ke halaman web. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
videoLicense |
string Parameter videoLicense memfilter hasil penelusuran agar hanya menyertakan video dengan lisensi tertentu. YouTube memungkinkan uploader video untuk melampirkan lisensi Creative Commons atau lisensi YouTube standar ke setiap videonya. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
videoPaidProductPlacement |
string Parameter videoPaidProductPlacement memfilter hasil penelusuran
agar hanya menyertakan video yang telah ditandai oleh kreator sebagai promosi berbayar. Jika menetapkan
nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter
type ke video .Nilai yang dapat diterima adalah:
|
|
videoSyndicated |
string Parameter videoSyndicated memungkinkan Anda membatasi penelusuran hanya pada video yang dapat diputar di luar youtube.com. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
|
videoType |
string Parameter videoType memungkinkan Anda membatasi penelusuran ke jenis video tertentu. Jika menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video .Nilai yang dapat diterima adalah:
|
Isi permintaan
Jangan sediakan isi permintaan saat memanggil metode ini.
Respons
Jika berhasil, metode ini akan menampilkan isi respons dengan struktur berikut:
{ "kind": "youtube#searchListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "regionCode": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ search Resource ] }
Properti
Tabel berikut menentukan properti yang muncul dalam hasil penelusuran:
Properti | |
---|---|
kind |
string Mengidentifikasi jenis resource API. Nilai akan menjadi youtube#searchListResponse . |
etag |
etag Etag resource ini. |
nextPageToken |
string Token yang dapat digunakan sebagai nilai parameter pageToken untuk mengambil halaman berikutnya dalam kumpulan hasil. |
prevPageToken |
string Token yang dapat digunakan sebagai nilai parameter pageToken untuk mengambil halaman sebelumnya dalam kumpulan hasil. |
regionCode |
string Kode wilayah yang digunakan untuk kueri penelusuran. Nilai properti adalah kode negara ISO dua huruf yang mengidentifikasi wilayah. Metode i18nRegions.list menampilkan daftar region yang didukung. Nilai defaultnya adalah US . Jika wilayah yang tidak didukung ditentukan, YouTube mungkin masih memilih wilayah lain, bukan nilai default, untuk menangani kueri. |
pageInfo |
object Objek pageInfo mengenkapsulasi informasi paging untuk kumpulan hasil. |
pageInfo.totalResults |
integer Jumlah total hasil dalam kumpulan hasil.Harap perhatikan bahwa nilai ini merupakan perkiraan dan mungkin tidak mewakili nilai yang tepat. Selain itu, nilai maksimum adalah 1.000.000. Anda tidak boleh menggunakan nilai ini untuk membuat link penomoran halaman. Sebagai gantinya, gunakan nilai properti nextPageToken dan prevPageToken untuk menentukan apakah akan menampilkan link penomoran halaman atau tidak. |
pageInfo.resultsPerPage |
integer Jumlah hasil yang disertakan dalam respons API. |
items[] |
list Daftar hasil yang cocok dengan kriteria penelusuran. |
Contoh
Catatan: Contoh kode berikut mungkin tidak mewakili semua bahasa pemrograman yang didukung. Lihat dokumentasi library klien untuk mengetahui daftar bahasa yang didukung.
Apps Script
Fungsi ini menelusuri video yang terkait dengan kata kunci 'dogs'. ID dan judul video hasil penelusuran dicatat ke log Apps Script.Perhatikan bahwa contoh ini membatasi hasil hingga 25. Untuk menampilkan lebih banyak hasil, teruskan parameter tambahan seperti yang didokumentasikan di sini: 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
Contoh kode ini memanggil metodesearch.list
API untuk mengambil hasil penelusuran yang terkait
dengan kata kunci tertentu.
Contoh ini menggunakan library klien 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
Contoh kode berikut memanggil metodesearch.list
API untuk mengambil hasil penelusuran yang terkait dengan kata kunci tertentu.
Contoh ini menggunakan library klien.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
Contoh ini memanggil metodesearch.list
API untuk mengambil hasil penelusuran
yang terkait dengan kata kunci tertentu.
Contoh ini menggunakan library klien 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
Error
Tabel berikut mengidentifikasi pesan error yang dapat ditampilkan API sebagai respons terhadap panggilan untuk metode ini. Lihat dokumentasi pesan error untuk detail selengkapnya.
Jenis error | Detail error | Deskripsi |
---|---|---|
badRequest (400) |
invalidChannelId |
Parameter channelId menentukan ID saluran yang tidak valid. |
badRequest (400) |
invalidLocation |
Nilai parameter location dan/atau locationRadius tidak diformat dengan benar. |
badRequest (400) |
invalidRelevanceLanguage |
Nilai parameter relevanceLanguage tidak diformat dengan benar. |
badRequest (400) |
invalidSearchFilter |
Permintaan berisi kombinasi filter penelusuran dan/atau pembatasan yang tidak valid. Perhatikan bahwa Anda harus menetapkan parameter type ke video jika Anda menetapkan parameter forContentOwner atau forMine ke true . Anda juga harus menetapkan parameter type ke video jika Anda menetapkan nilai untuk parameter eventType , videoCaption , videoCategoryId , videoDefinition , videoDimension , videoDuration , videoEmbeddable , videoLicense , videoSyndicated , atau videoType . |
Cobalah!
Gunakan APIs Explorer untuk memanggil API ini dan lihat permintaan dan respons API.