按类型和年份筛选 Netflix 片库:为什么 catalogs=netflix 的结果里还有别的平台

发布于 2026年10月29日

catalogs=netflix 返回的并不是一份 Netflix 片单。它的意思是「这部片在 Netflix 片库里有」,影片入选之后,接口会把它在同一个国家的所有上架情况一并带回。直接把 shows 当成 Netflix 列表入库,页面上就会冒出 Prime Video 的租赁价、Roku 频道里的免费入口,而你的筛选条件明明写着 netflix。

下面先用一次样例调用把这个误会拆开,再写代码:怎么取类型 id,怎么读 streamingOptions,怎么把查询固定下来,最后是一份能存档、下周能对账的脚本。

按 Netflix 过滤的结果里为什么还有别的平台

search-shows-by-filters 里,catalogs 的规则是「影片出现在所列片库的任意一个里就入选」。接口说明同时写明:除了你指定的平台,每部影片还会列出同一国家其他平台的观看方式;其他国家的数据一律不带。

一次样例调用的参数是 country=us、catalogs=netflix、show_type=movie、order_by=popularity_alltime,返回 20 部电影,hasMore 为 true,另有一个字符串 nextCursor。逐部检查 streamingOptions.us:

  • 20 部都有 Netflix 的订阅行,入选条件没有问题;
  • 这 20 部的上架行合计来自 10 个服务,每部 3 到 15 行,没有一部只有 Netflix;
  • 第一部电影的第一行就不是 Netflix,而是 Roku 频道里的 Paramount+ 附加频道。

所以 options[0]["link"] 这种写法拿到的未必是 Netflix 链接,按行统计租赁、购买、免费也会把别的平台算进来。美国区的 get-country 样例里,Netflix 只有 subscription 一种类型为 true,rent、buy、free、addon 都是 false;也就是说在这个样例里,结果中出现这几种类型的行,必定属于别的服务。

把 catalogs 收窄成 netflix.subscription 之类的写法,按说明同样只影响哪些片入选,不改变每部片带回哪些行。这个窄写法没有单独跑过样例,所以「只留 Netflix」这一步放在客户端做,不要指望服务端替你删行。

先用 get-genres 取类型 id,再写 genres 过滤条件

genres 要的是类型 id,不是页面上的显示名。get-genres 的样例返回 21 项,每项只有 id 和 name:scifi 对应 Science Fiction,talk 对应 Talk Show,thriller 就是 Thriller。凭印象写 sci-fi 或 science-fiction,等于把一个猜出来的字符串当过滤值。拼错的 id 接口会怎么回应,样例没有覆盖,所以脚本在发片库请求之前先用目录校验一遍,不依赖服务端报错。

这个接口没有必填参数,返回走平台信封 {code, message, data}:先看 HTTP 状态,再看 code 是否为 200,data 才是那个 21 项的数组,没有 genres 之类的外层键,也没有游标。output_language 支持 en、es、tr、fr,样例只验证过默认英文,因此过滤一律使用默认语言取到的 id,翻译后的 name 只用于展示。影片自身的 genres 字段是 {id, name} 对象的数组,正好可以在拿到结果后反向核对。

把 streamingOptions 当成国家映射,只保留你要的平台

streamingOptions 是以小写国家代码为键的对象,值是上架行数组。这个接口一次只查一个国家,样例里只有 us 一个键。读取时按请求的国家代码取,也就是 show["streamingOptions"].get("us", []),不要把所有键的值拍平。

字段并不是每行都齐。样例里的 Netflix 行带 videoLink、audios、subtitles、expiresSoon、availableSince,没有 addon;addon 只出现在附加频道行上,quality、expiresOn 也是有些行才有。

最容易踩的坑是 service 不是字符串,而是带 id、name、homePage 的对象。option["service"] == "netflix" 永远不成立,过滤结果为空,你还可能由此得出「这批片都不在 Netflix 上」的荒唐结论。要比较的是 option["service"]["id"]。

平台 id 同样别靠记忆。样例里 Prime Video 的 id 是 prime,Apple TV 是 apple,Paramount+ 作为服务是 paramount,而它在 Roku 里作为附加频道的 id 却是 paramountplus。把要用的 id 从 get-country(单个国家,看 services[].id)或 get-countries(各国一次取回)里抄出来,再写进 catalogs 和过滤常量。

保留规则很简单:目标服务的行用来统计 offer_types,其余服务只记下 id,放进 also_on。后者不是废料,「Netflix 上有的片,别处是否免费」恰好用得上它。入选却一行目标服务都没有的影片要单独标出来,不要静默丢掉;样例里没有出现,真出现了就说明 id 写错,或者对过滤语义的理解有偏差。

把 genres_relation、年份区间和评分区间固定成一条可复现的查询

genres=scifi,thriller 之后必须说明关系:genres_relation=and 要求两个类型都有,or 只要命中其一。缺省值是 and,也要写进查询里,写出来的值才会跟着快照一起存档;它只在 genres 含多个 id 时才起作用。

year_min、year_max 是四位年份整数,rating_min、rating_max 也是整数。样例里的 rating 是 73、84 这类整数,所以传 60,别传 6.0 或 7.5。

排序的坑出在周对比上。order_by 默认是 original_title;popularity_1week、popularity_1month 这类窗口会随时间滚动,同一批片下周的位置就变了,你会把排序抖动误读成上下架。要对账就选 original_title 或 release_date,并且比较时用 imdbId 做集合差,不比位置。

最后把整条查询(不含密钥)和结果存进同一个文件。下周的脚本先比较两份查询是否一致,不一致就不输出差异,因为条件变了的两份结果没有可比性。

请求模板是 https://api.opendata-api.com/api/project/streaming-availability/search-shows-by-filters?key=YOUR_API_KEY,再加上上面这些参数。密钥在控制台获取,脚本只读环境变量 OPENDATA_API_KEY,带查询串的完整地址不要写进日志;模板只是占位,打开或复制这篇文章不会发出任何数据请求。

每页数量随 show_type 变化:电影 20 条,其他 15 或 10 条

接口说明给出的规则是:show_type=movie 或 series_granularity=show(缺省值)时每页 20 条;剧集在 episode 粒度下每页 10 条;其余组合是 15 条。换句话说,电影永远是 20,剧集随粒度从 20(show)降到 15(season)再到 10(episode)。样例只验证了电影加 show 粒度的 20 条,另外两个数字来自说明。

这直接影响三件事。

第一,不要用「这页不足 20 条」判断抓完了,停止条件只有 hasMore 为 false。第二,响应里只有 shows、hasMore、nextCursor,没有总数字段,事先算不出要翻多少页;每翻一页都是一次独立请求,所以脚本设页数上限,超限就当没抓完,不落盘。第三,不传 show_type 时电影和剧集混在一起,页大小还要看粒度;做类型榜单时固定 show_type,电影和剧集各跑一条查询,各存各的快照。

如需其他同类应用的 API,可通过联系页面提出需求,平台也提供源码私有化部署。

完整脚本:一个平台、一组类型、下周还能对比的结果行

脚本做五件事:校验类型 id;按固定查询翻页;只保留目标服务的行并记下别的服务;核对入选条件;把快照连同查询存盘,再与上一份比较。HTTP 失败和业务 code 非 200 都会中止且不写文件,半份快照不会变成下周的基线。

import json
import os
import sys
from datetime import date
from pathlib import Path

import requests

BASE = "https://api.opendata-api.com/api/project/streaming-availability"
SERVICE = "netflix"  # a service id copied from get-country, not a guess
QUERY = {
    "country": "us",
    "catalogs": SERVICE,
    "show_type": "movie",
    "genres": "scifi,thriller",
    "genres_relation": "and",  # written out even though it is the default
    "year_min": 2015,
    "year_max": 2024,
    "rating_min": 60,
    "order_by": "original_title",  # a stable order, unlike rolling popularity windows
    "order_direction": "asc",
    "series_granularity": "show",
}
MAX_PAGES = 40


def call(operation, **params):
    params["key"] = os.environ["OPENDATA_API_KEY"]
    response = requests.get(f"{BASE}/{operation}", params=params, timeout=30)
    if not response.ok:  # raise_for_status would put the URL, and the key, in the message
        raise RuntimeError(f"{operation}: HTTP {response.status_code}")
    envelope = response.json()
    code = envelope.get("code") if isinstance(envelope, dict) else None
    if str(code) != "200":  # HTTP 200 alone is not business success
        raise RuntimeError(f"{operation}: business code {code}")
    return envelope["data"]


def check_genres(ids):
    known = {g["id"] for g in call("get-genres")}  # data is a plain array
    unknown = sorted(set(ids.split(",")) - known)
    if unknown:
        raise SystemExit(f"not in get-genres: {unknown}")


def pages():
    params = dict(QUERY)
    for _ in range(MAX_PAGES):
        data = call("search-shows-by-filters", **params)
        yield data["shows"]
        if not data["hasMore"]:  # never infer the last page from its size
            return
        params["cursor"] = data["nextCursor"]  # every other filter stays unchanged
    raise RuntimeError("page cap hit: the snapshot would be incomplete")


def to_row(show):
    options = (show.get("streamingOptions") or {}).get(QUERY["country"], [])
    mine = [o for o in options if o["service"]["id"] == SERVICE]  # service is an object
    return {
        "title": show["title"],
        "year": show.get("releaseYear"),
        "rating": show.get("rating"),
        "genres": sorted(g["id"] for g in show.get("genres", [])),
        "offer_types": sorted({o["type"] for o in mine}),
        "also_on": sorted({o["service"]["id"] for o in options} - {SERVICE}),
        "no_target_row": not mine,
    }


def snapshot():
    check_genres(QUERY["genres"])
    rows = {}
    for page in pages():
        for show in page:
            rows[show.get("imdbId") or show["id"]] = to_row(show)
    wanted = set(QUERY["genres"].split(","))
    odd = [
        key
        for key, row in rows.items()
        if row["no_target_row"]
        or (QUERY["genres_relation"] == "and" and not wanted <= set(row["genres"]))
    ]
    if odd:
        print(f"{len(odd)} rows fail the checks, first: {odd[:5]}", file=sys.stderr)
    return {"query": QUERY, "rows": rows}


def save_and_diff(snap):
    stem = f"{SERVICE}-{QUERY['country']}"
    out = Path(f"{stem}-{date.today()}.json")
    earlier = sorted(p for p in Path().glob(f"{stem}-*.json") if p != out)
    out.write_text(json.dumps(snap, ensure_ascii=False, indent=1), encoding="utf-8")
    if not earlier:
        print(f"first snapshot: {len(snap['rows'])} rows")
        return
    old = json.loads(earlier[-1].read_text(encoding="utf-8"))
    if old["query"] != snap["query"]:
        print(f"query changed since {earlier[-1].name}, diff skipped")
        return
    print("added  ", sorted(snap["rows"].keys() - old["rows"].keys()))
    print("dropped", sorted(old["rows"].keys() - snap["rows"].keys()))


if __name__ == "__main__":
    save_and_diff(snapshot())

先看 stderr。出现「没有目标服务行」,多半是 SERVICE 和 catalogs 的 id 对不上;and 关系下缺少所请求的类型,则要回头核对对过滤语义的理解。首次运行只会打印行数,从第二次起才有 added 和 dropped。

什么时候不该用片库过滤

  • 手里已有 IMDb 或 TMDB 编号,用 get-show;只有片名,用 search-shows-by-title。片库过滤是切片,不是查找。
  • 要确凿的上下架时间。快照差集只说明「这条查询的结果集变了」,rating_min 附近的评分波动同样会让影片进出结果。上下架走带 catalogs 的 get-changes,思路见即将下架提醒指南。
  • 想知道美区 Netflix 一共有多少部。响应里没有总数,只能翻完所有页。
  • 想跨国对比。country 是必填的单值,每个国家各发一次其余参数完全相同的查询,各存各的文件,别指望一次返回多个国家。
  • 返回的 link 是跳转到对应平台的入口,不是视频播放源,不要当作可嵌入的播放地址。

片库过滤负责缩小范围;一部片算不算「Netflix 的」,最后还是要靠你对 service.id 的那一次比较。