Menampilkan kumpulan hasil penelusuran yang cocok dengan parameter kueri yang ditentukan dalam permintaan API. Secara default, set hasil penelusuran mengidentifikasi resource video, channel, dan playlist yang cocok, tetapi Anda juga dapat mengonfigurasi kueri untuk hanya mengambil jenis resource tertentu.
Dampak kuota: 100 panggilan per hari. Panggilan ke metode ini memiliki biaya kuota sebesar 1 unit di bucket kuota Kueri Penelusuran.
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 |
stringParameter part menentukan daftar yang dipisahkan koma untuk satu atau beberapa properti resource search yang akan disertakan dalam respons API. Tetapkan nilai parameter ke snippet.
|
|
| Filter (tentukan 0 atau 1 parameter berikut) | ||
forContentOwner |
booleanParameter ini hanya dapat digunakan dalam permintaan yang diberi otorisasi dengan benar, dan ditujukan secara eksklusif untuk partner konten YouTube. Parameter forContentOwner membatasi penelusuran hanya untuk mengambil video yang dimiliki oleh pemilik konten yang diidentifikasi oleh parameter onBehalfOfContentOwner. Jika forContentOwner ditetapkan ke benar (true), permintaan juga harus memenuhi persyaratan berikut:
|
|
forDeveloper |
booleanParameter ini hanya dapat digunakan dalam permintaan yang diizinkan dengan benar. Parameter forDeveloper membatasi penelusuran hanya untuk 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 terkait dengan aplikasi developer di Konsol Developer Google. Saat permintaan penelusuran selanjutnya 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 itu sendiri, tetapi tidak ke video yang diupload melalui aplikasi atau situs lain. |
|
forMine |
booleanParameter ini hanya dapat digunakan dalam permintaan yang diberi otorisasi dengan benar. Parameter forMine membatasi penelusuran untuk hanya mengambil video milik pengguna yang diautentikasi. Jika Anda menetapkan 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 |
stringParameter channelId menunjukkan bahwa respons API hanya boleh berisi resource yang dibuat oleh channel. Catatan: Hasil penelusuran dibatasi hingga maksimum 500 video jika permintaan Anda menentukan nilai untuk parameter channelId dan menetapkan nilai parameter type ke video, tetapi tidak menetapkan salah satu filter forContentOwner, forDeveloper, atau forMine. |
|
channelType |
stringParameter channelType memungkinkan Anda membatasi penelusuran ke jenis channel tertentu.Nilai yang dapat diterima adalah:
|
|
eventType |
stringParameter eventType membatasi penelusuran ke acara siaran. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
location |
stringParameter 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 menyetel nilai parameter type ke video.
| |
locationRadius |
stringParameter locationRadius, bersama dengan parameter location, menentukan area geografis melingkar.Nilai parameter harus berupa angka floating point yang diikuti dengan satuan pengukuran. Satuan 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 mengetahui informasi selengkapnya. |
|
maxResults |
unsigned integerParameter maxResults menentukan jumlah maksimum item yang harus ditampilkan dalam kumpulan hasil. Nilai yang dapat diterima adalah 0 hingga 50, inklusif. Nilai defaultnya adalah 5. |
|
onBehalfOfContentOwner |
stringParameter ini hanya dapat digunakan dalam permintaan yang diberi otorisasi 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 banyak channel YouTube yang berbeda. Dengan begitu, pemilik konten dapat melakukan autentikasi satu kali dan mendapatkan akses ke semua data video dan channel mereka, tanpa harus memberikan kredensial autentikasi untuk setiap channel. Akun CMS yang digunakan pengguna untuk melakukan autentikasi harus ditautkan ke pemilik konten YouTube yang ditentukan. |
|
order |
stringParameter order menentukan metode yang akan digunakan untuk mengurutkan resource dalam respons API. Nilai defaultnya adalah relevance.Nilai yang dapat diterima adalah:
|
|
pageToken |
stringParameter pageToken mengidentifikasi halaman tertentu dalam set hasil yang harus ditampilkan. Dalam respons API, properti nextPageToken dan prevPageToken mengidentifikasi halaman lain yang dapat diambil. |
|
publishedAfter |
datetimeParameter publishedAfter menunjukkan bahwa respons API hanya boleh berisi resource yang dibuat pada atau setelah waktu yang ditentukan. Nilainya adalah nilai tanggal-waktu berformat RFC 3339 (1970-01-01T00:00:00Z). |
|
publishedBefore |
datetimeParameter 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 |
stringParameter q menentukan istilah kueri yang akan ditelusuri.Permintaan Anda juga dapat menggunakan operator Boolean NOT ( -) dan OR (|) untuk mengecualikan video atau menemukan video yang terkait dengan salah satu dari beberapa istilah penelusuran. Misalnya, untuk menelusuri video yang cocok dengan "boating" atau "sailing", tetapkan nilai parameter q ke boating|sailing. Demikian pula, untuk menelusuri video yang cocok dengan "berperahu" atau "berlayar", tetapi tidak dengan "memancing", tetapkan nilai parameter q ke boating|sailing -fishing. Perhatikan bahwa karakter pipa harus di-escape URL saat dikirim dalam permintaan API Anda. Nilai yang di-escape URL untuk karakter pipe adalah %7C. |
|
regionCode |
stringParameter regionCode menginstruksikan API untuk menampilkan hasil penelusuran video yang dapat dilihat di negara yang ditentukan. Nilai parameter adalah kode negara ISO 3166-1 alpha-2. |
|
relevanceLanguage |
stringParameter relevanceLanguage menginstruksikan API untuk menampilkan hasil penelusuran yang paling relevan dengan bahasa yang ditentukan. Nilai parameter biasanya berupa kode bahasa dua huruf ISO 639-1. Namun, Anda harus menggunakan nilai zh-Hans untuk bahasa China aksara sederhana dan zh-Hant untuk bahasa China aksara tradisional. Perhatikan bahwa hasil dalam bahasa lain akan tetap ditampilkan jika sangat relevan dengan istilah kueri penelusuran. |
|
safeSearch |
stringParameter safeSearch menunjukkan apakah hasil penelusuran harus menyertakan konten yang dibatasi serta konten standar.Nilai yang dapat diterima adalah:
|
|
topicId |
stringParameter topicId menunjukkan bahwa respons API hanya boleh berisi resource yang terkait dengan topik yang ditentukan. Nilai mengidentifikasi ID topik Freebase.Penting: Karena penghentian penggunaan Freebase dan Freebase API, parameter topicId mulai berfungsi secara berbeda sejak 27 Februari 2017. Pada saat itu, YouTube mulai mendukung sekumpulan kecil ID topik yang diseleksi, dan Anda hanya dapat menggunakan kumpulan ID yang lebih kecil tersebut sebagai nilai untuk parameter ini. |
|
type |
stringParameter type membatasi kueri penelusuran untuk hanya mengambil jenis resource tertentu. Nilainya adalah daftar jenis resource yang dipisahkan koma. Nilai defaultnya adalah video,channel,playlist.Nilai yang dapat diterima adalah:
|
|
videoCaption |
stringParameter videoCaption menunjukkan apakah API harus memfilter hasil penelusuran video berdasarkan apakah video tersebut memiliki teks atau tidak. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
videoCategoryId |
stringParameter videoCategoryId memfilter hasil penelusuran video berdasarkan kategori. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video. |
|
videoDefinition |
stringParameter videoDefinition memungkinkan Anda membatasi penelusuran agar hanya menyertakan video definisi tinggi (HD) atau definisi standar (SD). Video HD tersedia untuk diputar dalam resolusi minimal 720p, meskipun resolusi yang lebih tinggi, seperti 1080p, mungkin juga tersedia. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
videoDimension |
stringParameter videoDimension memungkinkan Anda membatasi penelusuran untuk hanya mengambil video 2D atau 3D. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
videoDuration |
stringParameter videoDuration memfilter hasil penelusuran video berdasarkan durasinya. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
videoEmbeddable |
stringParameter videoEmbeddable memungkinkan Anda membatasi penelusuran hanya pada video yang dapat disematkan ke halaman web. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
videoLicense |
stringParameter videoLicense memfilter hasil penelusuran agar hanya menyertakan video dengan lisensi tertentu. YouTube memungkinkan pengupload video memilih untuk melampirkan lisensi Creative Commons atau lisensi YouTube standar ke setiap videonya. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
videoPaidProductPlacement |
stringParameter videoPaidProductPlacement memfilter hasil penelusuran
untuk hanya menyertakan video yang telah ditandai oleh kreator sebagai video yang berisi promosi berbayar. Jika Anda menentukan
nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type
ke video.Nilai yang dapat diterima adalah:
|
|
videoSyndicated |
stringParameter 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 menyetel nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
videoType |
stringParameter videoType memungkinkan Anda membatasi penelusuran ke jenis video tertentu. Jika Anda menentukan nilai untuk parameter ini, Anda juga harus menetapkan nilai parameter type ke video.Nilai yang dapat diterima adalah:
|
|
Isi permintaan
Jangan berikan 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 |
stringMengidentifikasi jenis resource API. Nilainya adalah youtube#searchListResponse. |
etag |
etagEtag resource ini. |
nextPageToken |
stringToken yang dapat digunakan sebagai nilai parameter pageToken untuk mengambil halaman berikutnya dalam kumpulan hasil. |
prevPageToken |
stringToken yang dapat digunakan sebagai nilai parameter pageToken untuk mengambil halaman sebelumnya dalam kumpulan hasil. |
regionCode |
stringKode wilayah yang digunakan untuk kueri penelusuran. Nilai properti adalah kode negara ISO dua huruf yang mengidentifikasi wilayah. Metode i18nRegions.list menampilkan daftar wilayah 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 |
objectObjek pageInfo mengenkapsulasi informasi penomoran halaman untuk set hasil. |
pageInfo.totalResults |
integerJumlah total hasil dalam kumpulan hasil.Perhatikan bahwa nilai ini adalah perkiraan dan mungkin tidak mewakili nilai yang tepat. Selain itu, nilai maksimumnya 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. |
pageInfo.resultsPerPage |
integerJumlah hasil yang disertakan dalam respons API. |
items[] |
listDaftar hasil yang cocok dengan kriteria penelusuran. |
Contoh
Catatan: Contoh kode berikut mungkin tidak merepresentasikan 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 ''. ID video dan judul dari 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/data/reference/rest/v3/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 ke metode ini. Lihat dokumentasi pesan error untuk mengetahui detail selengkapnya.
| Jenis error | Detail error | Deskripsi |
|---|---|---|
badRequest (400) |
invalidChannelId |
Parameter channelId menentukan ID channel 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 dan/atau batasan penelusuran 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 melihat permintaan API serta respons API.