按类型、年份、评分和关键词浏览某国家的流媒体片库
查看 流媒体观看平台与片库查询 的全部接口 →在某个国家的流媒体片库中搜索(可限定到指定平台),返回支持游标分页的电影和剧集列表。唯一必填的输入是 country(ISO 3166-1 alpha-2 国家代码)。可选筛选条件包括:catalogs(最多 32 个以逗号分隔的片库选择器,如 netflix、prime.subscription 或 hulu.addon.hbo)、genres 及 genres_relation(and 或 or)、在标题和简介中匹配的 keyword、show_original_language、year_min 和 year_max、rating_min 和 rating_max。排序使用 order_by(original_title、release_date、rating,或四个时间窗口的热度排序)配合 order_direction;series_granularity(show、season 或 episode)决定返回多细的剧集信息,output_language 可选 en、es、tr、fr,cursor 用于获取下一页。文档说明的响应是一个对象,包含 shows 数组、hasMore 标志和 nextCursor 字符串。每个作品包含标题、IMDb 与 TMDb id、上映年份,以及带深度链接、字幕、音轨和画质信息的播放选项。除了请求指定的平台外,每个作品还会列出同一国家内其他平台的可观看信息;其他国家的信息不会出现。每页条数:show_type 为 movie 或 series_granularity 为 show 时是 20 条,series 配合 episode 粒度时是 10 条,其余情况是 15 条。一次示例调用(country 为 us、catalogs 为 netflix、show_type 为 movie、order_by 为 popularity_alltime、series_granularity 为 show)返回 HTTP 200,含 20 个作品,hasMore 为 true,并带有字符串类型的 nextCursor。示例中每个作品包含 itemType、showType、id、imdbId、tmdbId、title、overview、releaseYear、originalTitle、genres、directors、cast、rating、runtime、streamingOptions(以国家代码为键、值为播放选项列表的对象)和 imageSet。每个播放选项包含 service、type、addon、link、videoLink、price、quality、audios、subtitles、expiresSoon、expiresOn 和 availableSince。来源文档的响应示例被截断,且其中的图片链接带有过期信息,因此只有上述示例字段列表应视为已验证。
API 功能
在线 API 演示
未找到可用的 API Key,请前往控制台创建后刷新本页。 控制台 →
/api/project/streaming-availability/search-shows-by-filters API 响应 (JSON)
{} curl -X GET 'https://api.opendata-api.com/api/project/streaming-availability/search-shows-by-filters?key=<API_KEY>&country=<country>&genres_relation=and&order_by=original_title&output_language=en&series_granularity=show'
查询结果
使用场景
- 用 rating_min、genres 加上热度或评分排序,每周生成一份「美国 Netflix 高分惊悚片」榜单
- 对两个国家使用完全相同的筛选条件分别查询,对比同一平台在不同国家的片库规模与构成
- 利用 year_min、genres 和 catalogs 搭建「Prime 新上科幻片」这类编辑专题页,无需自己维护作品数据库
- 按原始语言切出韩剧等小众发现栏目,服务于冷门内容推荐应用
- 把筛选后的片库快照作为推荐系统的种子数据,并保留每个作品在各平台的播放选项
- 当某部作品在一个平台的片库里被找到、同时也在同国其他平台上线时,提示更便宜或免费的观看途径
常见问题
哪个参数是必填的?
只有 country,即两位 ISO 3166-1 alpha-2 国家代码,例如 us。其余参数都是可选的;不传 catalogs 时,搜索范围覆盖该国家可用的全部片库。
catalogs 的值怎么写?
使用最多 32 项、以逗号分隔的列表。单独的平台 id(如 netflix)搜索该平台的整个片库;service.type 的形式(如 prime.subscription、peacock.free、prime.rent)把范围限定到订阅、免费、租赁、购买和附加频道中的某一种套餐类型;service.addon.addon_id 的形式(如 hulu.addon.hbo)则限定到某个附加频道。只要作品命中任意一项就会被返回。
怎么翻页?
响应中包含 hasMore 和 nextCursor。当 hasMore 为 true 时,用相同的参数再次请求,并把 cursor 设为上一次的 nextCursor,同时要做 URL 转义,因为它可能包含 ? 和 & 等字符。首次请求不需要 cursor。示例调用返回的 hasMore 为 true,并带有字符串类型的 nextCursor。
每页返回多少个作品?
show_type 为 movie 或 series_granularity 为 show 时是 20 条;show_type 为 series 且 series_granularity 为 episode 时是 10 条;其余情况是 15 条。示例中的电影查询返回了 20 个作品。
catalogs 会限制每个作品里的播放选项吗?
不会。文档说明每个作品还会列出同一国家内其他平台的可观看信息,示例调用设置 catalogs=netflix 后,返回了来自十个平台的选项。其他国家的可观看信息永远不会出现。
genres 和 genres_relation 如何配合使用?
genres 接受来自类型接口的逗号分隔 id,例如 scifi,thriller。只有传入多个 id 时 genres_relation 才有意义:and(默认)返回同时具备全部类型的作品,or 返回至少具备其中一个类型的作品。
怎样优先拿到评分最高或最热门的作品?
把 order_by 设为 rating,或 popularity_alltime、popularity_1year、popularity_1month、popularity_1week 之一。文档说明方向默认值是:标题和日期排序为 asc,评分和热度排序为 desc,也可以用 order_direction 显式指定。示例调用使用了 popularity_alltime,没有传 order_direction。
rating_min 和 rating_max 使用什么量表?
它们是整数边界,作用于每个作品返回的同一个 rating 值。来源文档没有说明量表范围;示例调用中的 20 个作品评分为 73 到 84 之间的整数,所以很可能是 0 到 100 的量表,但这一点尚未得到确认。
剧集会包含季和集的数据吗?
只有当 series_granularity 为 season 或 episode 时才会。默认值 show 不包含季和集信息,在不需要这些数据时推荐使用,因为响应更小、速度更快。该参数对电影没有影响。
响应里的图片链接是永久有效的吗?
请当作临时链接处理。来源文档的响应示例显示图片链接带有过期时间和签名查询参数,所以应该重新请求获取最新结果,而不是长期保存这些链接。