Search: list

傳回一組與 API 要求中指定的查詢參數相符的搜尋結果。根據預設,搜尋結果集會識別相符的 videochannelplaylist 資源,但您也可以設定查詢,僅擷取特定類型的資源。

配額影響:呼叫這個方法的配額為 100 個單位。

常見用途

要求

HTTP 要求

GET https://www.googleapis.com/youtube/v3/search

參數

下表列出此查詢支援的參數。這裡列出的參數全都是查詢參數。

參數
必要參數
part string
part 參數會指定一份以逗號分隔的清單,其中包含一或多個 API 回應會包含的 search 資源屬性。將參數值設為 snippet
篩選器 (指定下列 0 或 1 個參數)
forContentOwner boolean
這個參數只能用在正確的授權要求,且僅供 YouTube 內容合作夥伴使用。

forContentOwner 參數會限制搜尋作業,只擷取由 onBehalfOfContentOwner 參數指定的內容擁有者所擁有的影片。如果將 forContentOwner 設為 true,要求還必須符合以下規定:
  • onBehalfOfContentOwner 為必要參數,
  • 授權要求的使用者必須使用已連結至指定內容擁有者的帳戶。
  • type 參數值必須設為 video
  • 無法設定以下其他參數:videoDefinitionvideoDimensionvideoDurationvideoEmbeddablevideoLicensevideoPaidProductPlacementvideoSyndicatedvideoType
forDeveloper boolean
這個參數只能在正確的授權要求中使用。forDeveloper 參數會將搜尋範圍限制為僅擷取透過開發人員應用程式或網站上傳的影片。API 伺服器會使用要求的授權憑證來識別開發人員。forDeveloper 參數可與選用搜尋參數 (例如 q 參數) 搭配使用。

使用這項功能時,每部上傳的影片都會自動標上與 Google Developers Console 中開發人員應用程式相關聯的專案編號。

當搜尋要求後續將 forDeveloper 參數設為 true 時,API 伺服器會使用要求的授權憑證來識別開發人員。因此,開發人員可以將搜尋結果限制為透過開發人員自家應用程式或網站上傳的影片,但是無法瀏覽透過其他應用程式或網站上傳的影片。
forMine boolean
這個參數只能在正確的授權要求中使用。forMine 參數會將搜尋範圍限制在已驗證使用者擁有的影片。如果將這個參數設為 true,則 type 參數值也必須設為 video。此外,您無法在同一項要求中設定下列其他參數:videoDefinitionvideoDimensionvideoDurationvideoEmbeddablevideoLicensevideoPaidProductPlacementvideoSyndicatedvideoType
選用參數
channelId string
channelId 參數表示 API 回應只能包含頻道建立的資源。

注意:如果您的要求指定 channelId 參數的值並將 type 參數值設為 video,但同時未設定其中一個 forContentOwnerforDeveloperforMine 篩選條件,則搜尋結果的影片數量上限為 500 部影片。
channelType string
channelType 參數可讓您將搜尋範圍限制在特定管道類型。

可接受的值如下:
  • any – 傳回所有頻道。
  • show:只擷取節目。
eventType string
eventType 參數會限制搜尋廣播事件的範圍。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • completed:僅包含已結束的廣播。
  • live:只包含進行中的廣播訊息。
  • upcoming:只包含即將播送的直播內容。
location string
location 參數會與 locationRadius 參數搭配使用,定義圓形地理區域,並限制搜尋中繼資料 (已在中繼資料中指定位於該區域的地理位置) 的影片。參數值是指定經緯度座標的字串,例如 (37.42307,-122.08427)。

  • location 參數值識別該區域中心點。
  • locationRadius 參數會指定與影片相關聯的位置距離範圍上限,如此影片便會納入搜尋結果中。
如果您的要求指定 location 參數的值,但沒有指定 locationRadius 參數值,則 API 會傳回錯誤。

注意:如果指定這個參數的值,您也必須將 type 參數值設為 video
locationRadius string
locationRadius 參數搭配 location 參數會定義圓形地理區域。

參數值必須是浮點數,後面接著測量單位。有效的測量單位為 mkmftmi。舉例來說,有效的參數值包括 1500m5km10000ft0.75mi。API 不支援超過 1,000 公里的 locationRadius 參數值。

注意:詳情請參閱 location 參數的定義。
maxResults unsigned integer
maxResults 參數會指定結果集應傳回的項目數量上限。可接受的值為 050 (含頭尾)。預設值為 5
onBehalfOfContentOwner string
這個參數只能在正確的授權要求中使用。注意:這個參數僅適用於 YouTube 內容合作夥伴。

onBehalfOfContentOwner 參數代表透過要求的授權憑證,代表 YouTube CMS 使用者,代表在參數值中指定的內容擁有者擔任代理人。這個參數適用於擁有及管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只要通過一次驗證,即可存取所有影片和頻道資料,不必分別提供各個頻道的驗證憑證。用於驗證的 CMS 帳戶,必須連結至指定的 YouTube 內容擁有者。
order string
order 參數會指定 API 回應中用於排序資源的方法。預設值為 relevance

可接受的值如下:
  • date:根據建立日期,由新到舊排序資源。
  • rating - 資源依評分由高至低排序。
  • relevance:系統會按照資源與搜尋查詢的關聯性排序資源。這是這個參數的預設值。
  • title:按照標題的字母順序排列資源。
  • videoCount:頻道會按照上傳影片數量遞減排序。
  • viewCount - 資源會按照瀏覽次數由高至低排序。就現場直播而言,系統會在播送期間根據同時線上觀眾人數排序影片。
pageToken string
pageToken 參數可在結果集中指明應傳回的特定網頁。在 API 回應中,nextPageTokenprevPageToken 屬性會識別其他可擷取的網頁。
publishedAfter datetime
publishedAfter 參數表示 API 回應只能包含在指定時間當天或之後建立的資源。這個值是採用 RFC 3339 格式的日期時間值 (1970-01-01T00:00:00Z)。
publishedBefore datetime
publishedBefore 參數表示 API 回應只能包含指定時間之前或時間建立的資源。這個值是採用 RFC 3339 格式的日期時間值 (1970-01-01T00:00:00Z)。
q string
q 參數會指定要搜尋的查詢字詞。

在要求中,你也可以使用布林 NOT (-) 和 OR (|) 運算子來排除影片,或是找出與多個搜尋字詞之一相關的影片。舉例來說,如要搜尋符合「划船」或「航海」的影片,請將 q 參數值設為 boating|sailing。同樣地,如要搜尋符合「划船」或「航行」但排除「釣魚」的影片,請將 q 參數值設為 boating|sailing -fishing。請注意,在您的 API 要求中傳送管道字元時,直立線字元必須逸出網址。直立線字元的網址逸出值為 %7C
regionCode string
regionCode 參數會指示 API 傳回搜尋結果,只傳回可在指定國家/地區觀看的影片。參數值採用 ISO 3166-1 alpha-2 國家/地區代碼。
relevanceLanguage string
relevanceLanguage 參數會指示 API 傳回與指定語言最相關的搜尋結果。參數值通常是 ISO 639-1 雙字母語言代碼。不過,對於簡體中文,應使用 zh-Hans 值,繁體中文則使用 zh-Hant。請注意,如果其他語言的結果與搜尋查詢高度相關,則仍會傳回。
safeSearch string
safeSearch 參數會指出搜尋結果是否應該包含受限制的內容和標準內容。

可接受的值如下:
  • moderate:YouTube 會在搜尋結果中過濾掉部分內容,且至少會將受您地區限制的內容過濾掉。視其內容而定,搜尋結果可能會從搜尋結果中移除,或是降低搜尋結果的排名。這是預設的參數值。
  • none:YouTube 不會篩選搜尋結果集。
  • strict:YouTube 會嘗試從搜尋結果集中排除所有受限制的內容。視其內容而定,搜尋結果可能會從搜尋結果中移除,或是降低搜尋結果的排名。
topicId string
topicId 參數表示 API 回應只能包含與指定主題相關聯的資源。這個值用於識別 Freebase 主題 ID。

重要事項:由於 Freebase 和 Freebase API 已淘汰,topicId 參數的運作方式也從 2017 年 2 月 27 日起開始不同。YouTube 開始支援少數收錄的主題 ID,因此你只能使用這組 ID 做為這個參數的值。

type string
type 參數會限制搜尋查詢只擷取特定類型的資源。這個值是資源類型的逗號分隔清單。預設值為 video,channel,playlist

可接受的值如下:
  • channel
  • playlist
  • video
videoCaption string
videoCaption 參數會指出 API 是否應根據是否有字幕篩選影片搜尋結果。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • any:不要根據字幕提供狀況篩選結果。
  • closedCaption:只加入有字幕的影片。
  • none:只加入沒有字幕的影片。
videoCategoryId string
videoCategoryId 參數會根據類別篩選影片搜尋結果。如果要指定這個參數的值,必須一併將 type 參數值設為 video
videoDefinition string
videoDefinition 參數可用來限制搜尋範圍,只納入高畫質 (HD) 或標準畫質 (SD) 影片。HD 高畫質影片至少能以 720p 播放,但某些解析度較高 (例如 1080p) 或許也可用。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • any:傳回所有影片,無論影片解析度為何。
  • high:只擷取 HD 高畫質影片。
  • standard:只擷取標準畫質的影片。
videoDimension string
videoDimension 參數可將搜尋範圍限制在僅擷取 2D 或 3D 影片。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • 2d:限制搜尋結果,排除 3D 影片。
  • 3d:限制搜尋結果只包含 3D 影片。
  • any:在傳回的結果中同時納入 3D 和非 3D 影片。這是預設值。
videoDuration string
videoDuration 參數會根據時間長度篩選影片搜尋結果。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • any:請勿根據時間長度篩選影片搜尋結果。這是預設值。
  • long:僅納入長度超過 20 分鐘的影片。
  • medium:只加入長度介於四到 20 分鐘 (含) 的影片。
  • short:只加入長度在四分鐘以內的影片。
videoEmbeddable string
videoEmbeddable 參數可讓您將搜尋範圍限制在可嵌入網頁中的影片。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • any:傳回所有影片 (無論是否可嵌入影片)。
  • true:只擷取可嵌入的影片。
videoLicense string
videoLicense 參數會篩選搜尋結果,只納入具有特定授權的影片。YouTube 可讓影片上傳者選擇是否要在每部影片中附加創用 CC 授權或標準 YouTube 授權。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • any:傳回所有符合查詢參數的影片,不論影片擁有何種授權都一樣。
  • creativeCommon:只傳回擁有創用 CC 授權的影片。使用者可在自己建立的其他影片中,重複使用具備授權的影片。瞭解詳情
  • youtube:只傳回具有標準 YouTube 授權的影片。
videoPaidProductPlacement string
videoPaidProductPlacement 參數會篩選搜尋結果,僅納入創作者標示為有付費宣傳內容的影片。如果要指定這個參數的值,也必須將 type 參數值設為 video

可接受的值如下:
  • any:傳回所有影片,不論影片是否含有付費宣傳內容。
  • true:只擷取含有付費宣傳的影片。
videoSyndicated string
videoSyndicated 參數可讓您將搜尋範圍限制在 youtube.com 之外播放的影片。如果指定了這個參數的值,也必須將 type 參數值設為 video

可接受的值如下:
  • any:傳回所有影片,無論是否聯合發布。
  • true:只擷取聯合發布影片。
videoType string
videoType 參數可讓您將搜尋範圍限制在特定的影片類型中。如果要指定這個參數的值,必須一併將 type 參數值設為 video

可接受的值如下:
  • any:傳回所有影片。
  • episode:只擷取節目劇集。
  • movie:只擷取電影。

要求主體

呼叫此方法時,不要提供要求主體。

回應

如果成功的話,這個方法會傳回回應內文,其結構如下:

{
  "kind": "youtube#searchListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "regionCode": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    search Resource
  ]
}

屬性

下表列出搜尋結果中顯示的屬性:

屬性
kind string
識別 API 資源的類型。值為 youtube#searchListResponse
etag etag
這項資源的 Etag。
nextPageToken string
可做為 pageToken 參數值的權杖,用於擷取結果集中的下一頁。
prevPageToken string
可做為 pageToken 參數值的權杖,擷取結果集中的上一頁。
regionCode string
用於搜尋查詢的區碼。屬性值是兩個字母的 ISO 國家/地區代碼,用於識別區域。i18nRegions.list 方法會傳回支援區域的清單。預設值為 US。如果指定了不支援的地區,YouTube 仍可能選擇其他地區 (而非預設值) 來處理查詢。
pageInfo object
pageInfo 物件會封裝結果集的分頁資訊。
pageInfo.totalResults integer
結果集中的結果總數。請注意,這個值是概略值,不一定代表實際值。此外,最大值為 1,000,000。

請不要使用這個值建立分頁連結。請改用 nextPageTokenprevPageToken 屬性值來判斷是否要顯示分頁連結。
pageInfo.resultsPerPage integer
API 回應中包含的結果數量。
items[] list
符合搜尋條件的結果清單。

範例

注意:下列程式碼範例可能不是所有支援的程式設計語言。如需支援的語言清單,請參閱用戶端程式庫說明文件。

Apps Script

這個函式會搜尋與關鍵字「dogs」相關的影片。搜尋結果的影片 ID 和標題會記錄在 Apps Script 的記錄中。

請注意,這個範例會將結果限制為 25 個。如要傳回更多結果,請按照這裡的說明傳送其他參數: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);
  }
}

查看

這個程式碼範例會呼叫 API 的 search.list 方法,擷取與特定關鍵字相關聯的搜尋結果。

本範例使用 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

下列程式碼範例會呼叫 API 的 search.list 方法,擷取與特定關鍵字相關聯的搜尋結果。

本範例使用 .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

這個範例呼叫 API 的 search.list 方法,擷取與特定關鍵字相關聯的搜尋結果。

本範例使用 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

錯誤

下表列出 API 回應此方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息的說明文件。

錯誤類型 錯誤詳細資料 說明
badRequest (400) invalidChannelId channelId 參數指定的頻道 ID 無效。
badRequest (400) invalidLocation location 和/或 locationRadius 參數值的格式有誤。
badRequest (400) invalidRelevanceLanguage relevanceLanguage 參數值的格式有誤。
badRequest (400) invalidSearchFilter 這項要求含有無效的搜尋篩選器和/或限制組合。請注意,如果您將 forContentOwnerforMine 參數設為 true,則必須將 type 參數設為 video。如果為 eventTypevideoCaptionvideoCategoryIdvideoDefinitionvideoDimensionvideoDurationvideoEmbeddablevideoLicensevideoSyndicatedvideoType 參數設定值,您也必須將 type 參數設為 video

試試看!

使用 APIs Explorer 呼叫這個 API 並查看 API 要求和回應。