Search

搜尋結果包含與 API 要求中指定的搜尋參數相符的 YouTube 影片、頻道或播放清單的相關資訊。雖然搜尋結果指向了可識別的專屬資源,例如影片,但它沒有專屬的持續性資料。

方法

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

list
傳回符合 API 要求中指定的查詢參數的搜尋結果集合。根據預設,搜尋結果集可識別相符的 videochannelplaylist 資源,但您也可以設定讓查詢只擷取特定類型的資源。 立即試用

資源表示法

下列 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 的值會包含 YouTube 用來識別符合搜尋查詢的管道 ID。
id.playlistId string
如果 id.type 屬性的值是 youtube#playlist,則該屬性會顯示;YouTube 的值會包含 YouTube 用於識別符合搜尋查詢的播放清單。
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 像素,高度為 88 像素。
  • medium:縮圖圖片的高解析度版本。如果是影片 (或影片專用的資源),這張圖片寬度為 320px,高度為 180px。對頻道而言,這張圖片的圖片寬度為 240px,高度為 240px。
  • high:縮圖的高解析度版本。如果是影片 (或影片專用的資源),這張圖片寬度為 480px,高度為 360px。頻道圖片的寬度為 800 像素,高度為 800 像素。
  • standard – 比 high 解析度圖片更高解析度的縮圖。這張圖片適用於部分影片和其他參考影片的資源,例如播放清單項目或搜尋結果。這張圖片寬度為 640px,高度為 480px。
  • maxres:縮圖圖片的解析度最高版本。此圖片大小適用於部分影片和其他參考影片的資源,例如播放清單項目或搜尋結果。此圖片的寬度為 1280px,高度為 720px。
snippet.thumbnails.(key).url string
圖片網址。
snippet.thumbnails.(key).width unsigned integer
圖片的寬度。
snippet.thumbnails.(key).height unsigned integer
圖片的高度。
snippet.channelTitle string
發布搜尋結果所識別資源的頻道標題。
snippet.liveBroadcastContent string
表示 videochannel 資源是否包含現場直播內容。有效屬性值為 upcominglivenone

如果是 video 資源,upcoming 值表示影片為尚未開始的現場直播,live 值則代表影片為進行中的現場直播。在 channel 資源中,upcoming 值表示頻道有尚未開始的播送活動,而 live 值表示頻道有進行中的現場直播。