Search: list

返回与 API 请求中指定的查询参数匹配的搜索结果集合。默认情况下，搜索结果集会标识匹配的 video、channel 和 playlist 资源，但您也可以将查询配置为仅检索特定类型的资源。

对配额的影响：调用此方法的配额费用为 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。
  • 以下参数均不能设置：videoDefinition、videoDimension、videoDuration、videoEmbeddable、videoLicense、videoPaidProductPlacement、videoSyndicated、videoType。
forDeveloper boolean
此参数只能在正确授权的请求中使用。forDeveloper 参数用于将搜索限制为仅检索通过开发者的应用或网站上传的视频。API 服务器使用请求的授权凭据标识开发者。forDeveloper 参数可以与 q 参数等可选搜索参数结合使用。

对于此功能，系统会自动使用 Google Developers Console 中与开发者的应用相关联的项目编号标记上传的视频。

随后，如果搜索请求将 forDeveloper 参数设置为 true，API 服务器会使用该请求的授权凭据来识别开发者。因此，开发者可以将搜索结果范围限定为通过开发者自己的应用或网站上传的视频，而无法仅显示通过其他应用或网站上传的视频。
forMine boolean
此参数只能在正确授权的请求中使用。forMine 参数用于将搜索限制为仅检索由经过身份验证的用户拥有的视频。如果将此参数设置为 true，则 type 参数的值也必须设置为 video。此外，无法在同一个请求中设置以下任何其他参数：videoDefinition、videoDimension、videoDuration、videoEmbeddable、videoLicense、videoPaidProductPlacement、videoSyndicated 和 videoType。
可选参数
channelId string
channelId 参数表示 API 响应应仅包含该频道创建的资源。

注意：如果您的请求指定了 channelId 参数的值并将 type 参数值设置为 video，但并未设置 forContentOwner、forDeveloper 或 forMine 过滤条件之一，则搜索结果最多只能包含 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 参数搭配使用时，定义了圆形地理区域。

此参数值必须是浮点数加测量单位。有效的计量单位包括 m、km、ft 和 mi。例如，有效的参数值包括 1500m、5km、10000ft 和 0.75mi。该 API 不支持大于 1,000 公里的 locationRadius 参数值。

注意：如需了解详情，请参阅 location 参数的定义。
maxResults unsigned integer
maxResults 参数指定结果集中应返回的商品数量上限。可接受的值包括0到50（含 0 和 10000）。默认值为 5。
onBehalfOfContentOwner string
此参数只能在正确授权的请求中使用。注意：此参数仅适用于 YouTube 内容合作伙伴。

onBehalfOfContentOwner 参数用于指明该请求的授权凭据会标识代表参数值中指定的内容所有者执行操作的 YouTube 内容管理系统用户。此参数适用于拥有和管理众多不同 YouTube 频道的 YouTube 内容合作伙伴。它可让内容所有者在一次身份验证后获得访问其所有视频和频道数据的权限，而无需为每个频道提供身份验证凭据。用户进行身份验证时所用的 CMS 账号必须与指定的 YouTube 内容所有者相关联。
order string
order 参数指定在 API 响应中对资源进行排序的方法。默认值为 relevance。

可接受的值包括：
  • date - 根据资源创建日期以时间倒序排列资源。
  • rating - 资源按评分由高到低排序。
  • relevance - 根据资源与搜索查询的相关程度对其进行排序。这是此参数的默认值。
  • title - 资源按标题的字母顺序排序。
  • videoCount - 按照频道上传的视频数量降序排列频道。
  • viewCount - 按查看次数从高到低对资源进行排序。对于直播，系统会在直播过程中按同时观看人数对视频进行排序。
pageToken string
pageToken 参数用于标识结果集中应返回的特定网页。在 API 响应中，nextPageToken 和 prevPageToken 属性用于标识可检索到的其他页面。
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 会尝试从搜索结果中排除所有受限内容。YouTube 会根据搜索结果的内容，从搜索结果中删除某些搜索结果或将其降位。
topicId string
topicId 参数表示 API 响应应仅包含与指定主题相关联的资源。该值用于标识 Freebase 主题 ID。

重要提示：由于 Freebase 和 Freebase API 已被弃用，自 2017 年 2 月 27 日起，topicId 参数的工作方式开始有所不同。当时，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) 视频。您能以至少 720p 的分辨率播放高清视频，不过，您也可以使用更高的分辨率，例如 1080p。如果您为此参数指定值，则还必须将 type 参数的值设为 video。

可接受的值为：
  • any - 返回所有视频，无论其分辨率如何。
  • high - 仅检索高清视频。
  • standard - 仅检索标清视频。
videoDimension string
您可以使用 videoDimension 参数将搜索限制为仅检索 2D 或 3D 视频。如果您为此参数指定值，则还必须将 type 参数的值设为 video。

可接受的值为：
  • 2d - 将搜索结果限制为排除 3D 视频。
  • 3d - 将搜索结果限制为仅包含 3D 视频。
  • any - 返回的结果中同时包含 3D 和非 3D 视频。这是默认值。
videoDuration string
videoDuration 参数会根据时长来过滤视频搜索结果。如果您为此参数指定值，则还必须将 type 参数的值设为 video。

可接受的值为：
  • any – 请勿根据视频时长过滤视频搜索结果。这是默认值。
  • long – 仅包含时长超过 20 分钟的视频。
  • medium - 仅包含时长在 4 到 20 分钟（含）之间的视频。
  • short - 只能包含时长在 4 分钟以内的视频。
videoEmbeddable string
您可以使用 videoEmbeddable 参数将搜索范围限定为可以嵌入到网页中的视频。如果您为此参数指定值，则还必须将 type 参数的值设为 video。

可接受的值为：
  • any - 返回所有视频，无论是否可嵌入。
  • true – 仅检索可嵌入的视频。
videoLicense string
videoLicense 参数用于过滤搜索结果，使其仅包含具有特定许可的视频。YouTube 允许视频上传者选择为每个视频附加知识共享许可或标准 YouTube 许可。如果您为此参数指定值，则还必须将 type 参数的值设为 video。

可接受的值为：
  • any - 返回与查询参数匹配的所有视频，无论其拥有何种许可。
  • creativeCommon - 仅返回具有知识共享许可的视频。用户可以在自己创建的其他视频中重复使用具有此许可的视频。了解详情。
  • 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。

您不应使用此值创建分页链接。而应改用 nextPageToken 和 prevPageToken 属性值来确定是否显示分页链接。
pageInfo.resultsPerPage integer
API 响应中包含的结果数量。
items[] list
与搜索条件匹配的结果列表。

示例

注意：以下代码示例可能并未涵盖所有受支持的编程语言。有关受支持语言的列表，请参阅客户端库文档。

Apps 脚本

此函数用于搜索与关键字“dogs”相关的视频。搜索结果的视频 ID 和标题会记录到 Apps 脚本的日志中。

请注意，此示例将结果限制为 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);
  }
}
youtube.gs

Go

此代码示例调用 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")
}

search_by_keyword.go

.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)));
    }
  }
}

Search.cs

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

search.rb

错误

下表列出了 API 在响应对此方法的调用时可能会返回的错误消息。如需了解详情，请参阅错误消息文档。

错误类型 错误详情 说明
badRequest (400) invalidChannelId channelId 参数指定的频道 ID 无效。
badRequest (400) invalidLocation location 和/或 locationRadius 参数值格式不正确。
badRequest (400) invalidRelevanceLanguage relevanceLanguage 参数值的格式不正确。
badRequest (400) invalidSearchFilter 请求包含无效的搜索过滤条件和/或限制组合。请注意，如果您将 forContentOwner 或 forMine 参数设置为 true，则必须将 type 参数设置为 video。如果您为 eventType、videoCaption、videoCategoryId、videoDefinition、videoDimension、videoDuration、videoEmbeddable、videoLicense、videoSyndicated 或 videoType 形参设置了值，则还必须将 type 形参设为 video。

试试看！

使用 APIs Explorer 调用此 API 并查看 API 请求和响应。