流媒体即将下架 API:按国家与平台做待看清单提醒

发布于 2026年10月28日

change_type=expiring 是下架提醒的入口;改成 removed,拿到的就是已经移除的变更。两者不能共用“还有三天可看”的文案。真正要交给通知系统的,不是搜到的片名,而是“这个国家、这个观看渠道中,影响该用户待看影片的一条变更候选”。

下架提醒应从片库变更开始,而不是反复搜索片名

get-changes 必填 country、change_type 和 item_type;本例使用 expiring、show,需要只看电影时再加 show_type=movie。new、removed、updated 面向历史,expiring、upcoming 面向未来,不能用新增片单推断下架名单。

先用 get-countries 确认市场与服务标识。它是按国家代码索引的对象,各国对象内有 services,不是影片列表。catalogs 可用服务 ID,也可用 service_id.subscription、.rent、.buy、.free、.addon 或 service_id.addon.addon_id,分别限定订阅、租赁、购买、免费或附加频道;最多组合 32 项,按“任一匹配”合并,省略则覆盖该国可用片库。

因此,租赁渠道消失不等于会员权益到期。查询只需平台密钥,不要求提供 Netflix 账号或官方开发者凭据;覆盖国家和片库仍须以目录为准。

把 changes 变更数组与 shows 影片对象放在一起读

先诊断响应,再写提醒逻辑:HTTP 成功后还要检查平台业务 code,成功值为 200,再读取 data。鉴权失败、余额不足或结构异常不能转成“今天无下架影片”。

业务载荷中,changes 是变更数组,shows 是受影响影片详情对象,hasMore 是布尔值;继续翻页时才需要 nextCursor。不要把整个载荷当影片数组,也不要把 shows 中每部影片直接群发:一部影片可能关联不同观看方式,提醒资格应由变更记录决定。

下面代码只验证并交出这两部分,不假装已经解析嵌套关联。空 changes 只表示这次筛选没有记录,不证明全国片库没有变动。

用稳定影片标识匹配待看清单,避免同名误报

先核对实际变更记录中的影片引用,究竟对应 shows 的键还是详情中的标识;不要未经确认就写死 shows[event["showId"]]。外层结构明确,不代表所有嵌套字段都已形成可依赖的关联契约;关联不明的记录应暂存复核,而不是猜片名补齐。

待看库应保存影片 ID 及命名空间。已有 IMDb 或 TMDB 数据时, get-show 可接受 tt0120338、movie/597、tv/1396 等格式,帮助建立本地标识映射;电影和剧集不能只按数字合并。确认关联后,再将受影响 ID 与用户清单取交集,不必逐条补查所有变更。

只有片名时才用 search-shows-by-title 辅助消歧。它按片名匹配,可能返回当前国家没有观看渠道的作品;“搜到电影”并不是“订阅可看”。

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

游标翻页时固定国家、片库与日期窗口

from、to 是包含边界的 Unix 秒:未来变更限定在今天至未来 31 天,历史变更限定在过去 31 天至今天。不要传毫秒。缺省窗口会随日期移动,轮询任务宜显式保存窗口;首次不传 cursor,后续只更换游标,其余筛选值全部保留。

请求模板为 https://api.opendata-api.com/api/project/streaming-availability/get-changes?key=YOUR_API_KEY,另带上述必填筛选。平台密钥从控制台获取,只在服务端读取环境变量,并在访问日志中遮盖查询参数。模板不会因打开文章或复制代码而执行。

以下函数要求调用方传入已核对的 country、change_type=expiring、item_type=show 及合法整数 from/to,可附加经目录确认的 catalogs;它不猜平台 ID,也不自动计算每天滚动的边界。

import os
import requests

URL = "https://api.opendata-api.com/api/project/streaming-availability/get-changes"

def change_pages(filters):
    fixed = dict(filters, key=os.environ["OPENDATA_API_KEY"])
    fixed.pop("cursor", None)
    params, seen = dict(fixed), set()
    while True:
        response = requests.get(URL, params=params, timeout=30)
        response.raise_for_status()
        envelope = response.json()
        if not isinstance(envelope, dict) or envelope.get("code") != 200:
            raise RuntimeError("API business request failed")
        data = envelope.get("data")
        if not isinstance(data, dict):
            raise ValueError("Expected a changes payload object")
        if not isinstance(data.get("changes"), list):
            raise ValueError("Expected a changes array")
        if not isinstance(data.get("shows"), dict):
            raise ValueError("Expected a shows object")
        more, cursor = data.get("hasMore"), data.get("nextCursor")
        if not isinstance(more, bool):
            raise ValueError("Expected a boolean hasMore")
        if more and (not isinstance(cursor, str) or not cursor or cursor in seen):
            raise ValueError("Missing or repeated continuation cursor")
        yield data["changes"], data["shows"]
        if not more:
            break
        seen.add(cursor)
        params = dict(fixed, cursor=cursor)

文档页大小为 25 条,但停止条件是 hasMore=false,不是“这页不足 25 条”。requests 会编码游标;不要手工拼接。缺失或重复游标应中止并保留进度,不算完整扫描。固定筛选也不意味着服务保证分页期间片库冻结不变。

多轮轮询只生成一次提醒候选

游标是遍历位置,不是事件 ID。重叠窗口与重复轮询可能再次读到同一变更;本地去重键可组合国家、规范化片库范围、稳定影片标识、实际服务与观看方式、变更类型、已知变更日期。这是应用自己的键设计,不是接口承诺的唯一事件编号,轮询时间和游标都不应放进去。

先入候选表,再按待看清单分发;用户通知表另以用户 ID 加候选键约束唯一,发送成功后才记已送达。日期修订应更新原候选并按产品规则处理,不能当成第二部影片。某页失败时不要推进完整扫描水位,也不要清空待看清单;过期窗口是否仍可恢复,须重新检查允许的日期范围。

下架日期未知时,不要生成精确倒计时

include_unknown_dates 默认 false,仅影响未来变更。设为 true 可以纳入无日期记录,但排序时这些记录按时间戳 0 处理:升序在前、降序在后。这不表示影片在 1970 年下架,也不能把它替换成今天。

已知日期候选与未知日期候选应分开:前者经核对后展示预计日期;后者只提示“可能即将下架,具体日期未公布”,不触发“今晚截止”通知。未知变已知时补全原候选,而非重复提醒。中文界面可以自行本地化文案,但 output_language 仅支持 en、es、tr、fr,不要传 zh。

片库变更接口不能承诺最后可看时刻

这套接口提供影片元数据与服务观看链接,不提供视频播放源、下载地址或会员授权。下架事件、片名搜索命中、订阅权益与当前实际可播放,是不同判断;一个国家或一种观看方式的变动,不能扩写成“全球下架”。

给订阅用户或片单邮件呈现的应是地区、渠道、预计日期与不确定性,而不是保证最后一秒仍可观看。未来 31 天窗口不是完整版权历史库,日期为空也不是永不下架;现有结构证据同样不能证明每个嵌套字段齐全、每个服务覆盖完整或数据实时更新。提醒可以帮助用户安排观看,不能替平台承诺播放权限或到期时刻。