按类型、年份、评分和关键词浏览某国家的流媒体片库

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

在某个国家的流媒体片库中搜索(可限定到指定平台),返回支持游标分页的电影和剧集列表。唯一必填的输入是 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 功能

按平台和套餐类型限定片库范围 catalogs 最多接受 32 个选择器,如 netflix、prime.subscription、peacock.free 或 hulu.addon.hbo,可以只搜整个平台、某一种套餐类型或某个附加频道;不传则搜索该国家的全部片库。
支持 and/or 逻辑的类型筛选 在 genres 中传入逗号分隔的类型 id,再用 genres_relation 选择:and(默认)只保留同时具备所有类型的作品,or 则保留至少具备其中一个类型的作品。
上映年份与评分区间 year_min、year_max、rating_min、rating_max 都是整数边界,一次请求就能把结果收窄到指定的上映年份范围和评分区间。
标题与简介的关键词匹配 keyword 只保留标题或简介中包含该词的作品,可以与类型、年份筛选组合,在同一个片库切片里精确查找。
按原始语言切分片单 show_original_language 接受 ko、fr 这样的 ISO 639-1 语言代码,只保留原始语言匹配的作品,适合做小众内容发现页。
七种排序方式与方向控制 order_by 支持 original_title、release_date、rating 以及四个热度窗口(全部时间、近 1 年、近 1 个月、近 1 周),order_direction 可在 asc 与 desc 之间切换。
三档剧集信息粒度 series_granularity 可选 show、season 或 episode:show 让响应保持精简,episode 会额外返回季和集的数据,以及各自的播放选项与深度链接。
每个作品附带同国其他平台的可观看信息 每个作品除了请求的片库外,还会列出同一国家内其他平台的播放选项;示例调用设置 catalogs=netflix 后,返回了来自十个平台的选项。
基于游标的连续翻页 响应包含 hasMore 和 nextCursor;保持筛选条件不变,把 cursor 设为 nextCursor 重新请求即可读取下一页,直到 hasMore 为 false。

在线 API 演示

GET /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'
📢
需要帮助?
如遇接口异常,或需要其他接口需求,可联系我们
联系我们

使用场景

常见问题

哪个参数是必填的?

只有 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 不包含季和集信息,在不需要这些数据时推荐使用,因为响应更小、速度更快。该参数对电影没有影响。

响应里的图片链接是永久有效的吗?

请当作临时链接处理。来源文档的响应示例显示图片链接带有过期时间和签名查询参数,所以应该重新请求获取最新结果,而不是长期保存这些链接。

相关接口

相关指南

查看订阅方案 →