按片名搜索电影和剧集,返回所选国家的流媒体播放选项

查看 流媒体观看平台与片库查询 的全部接口 →

按片名关键词搜索电影和剧集,返回匹配影视作品的 JSON 数组,每条结果都附带你所选国家的流媒体上架信息。必填参数有两个:country(ISO 3166-1 alpha-2 国家代码,例如 us,支持的国家可通过 countries 接口查询)和 title(要搜索的片名关键词)。可选参数包括:show_type,用于把搜索限定为某一类作品(示例调用使用的是 movie,不传则同时搜索电影和剧集);output_language(en、es、tr 或 fr,默认 en);series_granularity(show、season 或 episode,默认 show,只对剧集生效,选 show 时返回体最小)。默认最多返回 20 条结果;如果片名完全相同的作品超过 20 部,则返回全部精确匹配项。本接口不支持分页。流媒体信息只包含所请求的国家,而且搜索条件仅有片名和作品类型,因此命中的作品在该国不一定能在线观看。示例调用(country 为 us、title 为 batman、show_type 为 movie、series_granularity 为 show)返回 HTTP 200,根节点是包含 20 个作品对象的数组。每个对象包含 itemType、showType、id、imdbId、tmdbId、title、originalTitle、overview、releaseYear、genres(由 id 和 name 组成的键值对)、directors、cast、rating、imageSet 和 streamingOptions,其中 20 条里有 19 条还带有 runtime。streamingOptions 是以国家代码为键的对象(示例中为 us),其下的播放选项包含 service、type、link、quality、audios、subtitles、expiresSoon 和 availableSince;租赁和购买类选项还有 price 对象(amount、currency、formatted),部分选项另有 expiresOn、videoLink 或 addon。文档中除 movie 这个示例外没有列出 show_type 的其他取值,示例调用也只验证了电影结果。

API 功能

片名关键词匹配,最多返回 20 条 传入任意片名关键词,最多返回 20 部作品;若片名完全相同的作品超过 20 部,则返回全部精确匹配项,不会被截断。
每条结果附带指定国家的 streamingOptions 每个结果都带有以你所请求国家为键的 streamingOptions,包含平台、选项类型、跳转链接、画质、音轨、字幕,租赁和购买类选项还有 price 价格对象。
用 show_type 区分电影或剧集 传入 show_type 即可把搜索限定为某一类作品;不传则一次请求同时搜索电影和剧集。
控制剧集结果的详细程度 series_granularity 可在 show、season、episode 之间切换剧集的返回粒度;默认的 show 返回体最小,电影结果不受影响。
返回可直接用于后续查询的编号 每条结果都包含内部 id 以及 imdbId 和 tmdbId,选中的作品可以直接交给单片查询接口,进一步查看跨国家的上架情况。
支持四种输出语言 output_language 可选 en、es、tr 或 fr,用来指定返回文本的语言,默认是 en。

在线 API 演示

GET /api/project/streaming-availability/search-shows-by-title

调用成本暂不可用,未假定任何价格。

查看价格

API 响应 (JSON)

{}
curl -X GET 'https://api.opendata-api.com/api/project/streaming-availability/search-shows-by-title?key=<API_KEY>&country=<country>&output_language=en&series_granularity=show&title=<title>'
📢
需要帮助?
如遇接口异常,或需要其他接口需求,可联系我们
联系我们

使用场景

常见问题

按片名搜索最多返回多少条结果?可以翻页吗?

最多返回 20 条;如果片名完全相同的作品超过 20 部,则返回全部精确匹配项。本接口不支持分页。以 batman 为关键词的示例调用返回了一个包含 20 部作品的根数组。

所有国家的流媒体信息都会返回吗?

不会。只覆盖 country 参数指定的国家,streamingOptions 以该国家代码为键(示例中为 us)。如果想对比同一部作品在不同地区的上架情况,可以先从搜索结果里取出它的 id,再调用不带 country 的单片查询接口。

为什么有的结果里 streamingOptions 是空对象?

搜索条件只有片名和作品类型,所以在目标国家无法在线观看的作品也可能被匹配到。示例调用的 20 条结果中,有一部 1966 年的《蝙蝠侠》电影在 us 下的 streamingOptions 就是空对象。

播放选项可能有哪些类型和字段?

示例中出现的类型有 subscription、rent、buy、free 和 addon。每个选项都有 service、type、link、audios、subtitles、expiresSoon 和 availableSince,大多数还有 quality。租赁和购买类选项带有 price,其中包含 amount、currency 和 formatted;部分选项还有 expiresOn、videoLink,或用来标明附加频道的 addon 对象。

show_type 应该传什么值?

该参数可选。示例调用传的是 movie;不传时电影和剧集都会被搜索。已提供的文档只给出了 movie 这一个示例值,没有列出其他取值,因此如果要按它筛选,建议以响应中的 showType 字段为准。

series_granularity 在这个接口里有什么作用?

它只影响剧集。show 不包含季和集信息,season 增加季信息但不含分集,episode 则同时包含季、集信息以及分集跳转链接。默认值是 show,返回体最小、速度最快。电影不受影响,示例调用(全是电影)使用的就是 show。

响应里的图片链接会过期吗?

示例响应中的图片链接带有 Expires 和 Signature 查询参数,应视为有时效的链接,需要时重新请求该作品,而不要长期保存这些 URL。imageSet 包含 verticalPoster、horizontalPoster、verticalBackdrop 和 horizontalBackdrop,每种都有 w360、w720 等多种宽度。

相关接口

相关指南

查看订阅方案 →