Search

search 結果包含符合 API 要求中指定搜尋參數的 YouTube 影片、頻道或播放清單資訊。搜尋結果會指向可唯一識別的資源 (例如影片)，但本身沒有持續性資料。

方法

這個 API 支援下列搜尋方法：

list

傳回符合 API 要求中指定查詢參數的搜尋結果集合。根據預設，搜尋結果集會找出相符的 video、channel 和 playlist 資源，但您也可以設定查詢，只擷取特定類型的資源。 立即試用。

資源表示法

以下 JSON 結構顯示搜尋結果的格式：

{
  "kind": "youtube#searchResult",
  "etag": etag,
  "id": {
    "kind": string,
    "videoId": string,
    "channelId": string,
    "playlistId": string
  },
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "channelTitle": string,
    "liveBroadcastContent": string
  }
}

屬性

下表定義搜尋結果中顯示的屬性：

屬性
kind	string 識別 API 資源的類型。值為 youtube#searchResult。
etag	etag 這項資源的 Etag。
id	object id 物件包含的資訊可用於不重複識別符合搜尋要求的資源。
id.kind	string API 資源的類型。
id.videoId	string 如果 id.type 屬性的值為 youtube#video，則這個屬性會存在，且其值會包含 YouTube 用來唯一識別符合搜尋查詢的影片 ID。
id.channelId	string 如果 id.type 屬性的值為 youtube#channel，則這項屬性會存在，且其值會包含 YouTube 用來識別符合搜尋查詢的頻道 ID。
id.playlistId	string 如果 id.type 屬性的值為 youtube#playlist，則這項屬性會存在，且其值會包含 YouTube 用來識別符合搜尋查詢的播放清單 ID。
snippet	object snippet 物件包含搜尋結果的基本詳細資料，例如名稱或說明。舉例來說，如果搜尋結果是影片，標題就會是影片標題，說明則會是影片說明。
snippet.publishedAt	datetime 搜尋結果所識別資源的建立日期和時間。值以 ISO 8601 格式指定。
snippet.channelId	string YouTube 用來識別頻道的值，該頻道發布了搜尋結果所識別的資源。
snippet.title	string 搜尋結果的標題。
snippet.description	string 搜尋結果的說明。
snippet.thumbnails	object 與搜尋結果相關聯的縮圖地圖。地圖中的每個物件都有一個鍵，也就是縮圖圖片的名稱，而值則是包含縮圖其他資訊的物件。
snippet.thumbnails.(key)	object 有效鍵值如下： default：預設縮圖圖片。影片的預設縮圖 (或參照影片的資源，例如播放清單項目或搜尋結果) 寬 120 像素，高 90 像素。頻道的預設縮圖寬度和高度皆為 88 像素。 medium：縮圖圖片的更高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 320 像素，高度為 180 像素。如果是頻道，這張圖片的寬度和高度都是 240 像素。 high – 縮圖的高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 480 像素，高度為 360 像素。如果是頻道，這張圖片的寬度和高度都是 800 像素。 standard：比 high 解析度圖片的縮圖圖片解析度更高。這張圖片適用於部分影片，以及參照影片的其他資源，例如播放清單項目或搜尋結果。這張圖片的寬度為 640 像素，高度為 480 像素。 maxres：縮圖圖片的最高解析度版本。部分影片和其他參照影片的資源 (例如播放清單項目或搜尋結果) 會提供這個尺寸的圖片。這張圖片的寬度為 1280 像素，高度為 720 像素。 注意：搜尋結果不支援 1080p 以上的縮圖圖片 (fhd、qhd 和 uhd)。如要擷取高解析度縮圖，請使用資源 ID 呼叫資源專屬端點 (例如 videos.list)。
snippet.thumbnails.(key).url	string 圖片的網址。
snippet.thumbnails.(key).width	unsigned integer 圖片寬度。
snippet.thumbnails.(key).height	unsigned integer 圖片高度。
snippet.channelTitle	string 搜尋結果所指資源的發布頻道名稱。
snippet.liveBroadcastContent	string 指出 video 或 channel 資源是否含有現場直播內容。有效屬性值為 upcoming、live 和 none。 對於 video 資源，值為 upcoming 表示影片是尚未開始的現場直播，值為 live 則表示影片是正在進行的現場直播。如果是 channel 資源，值為 upcoming 表示頻道有排定的廣播但尚未開始，值為 live 則表示頻道有進行中的現場直播。