首页 新闻动态 知识

电视节目预告API怎么接入频道列表节目查询与日期更新如何处理

发布时间：2026-08-19 14:01 点击：8176次

电视节目预告 API 应先同步频道目录，再用频道 ID 和日期查询节目单；频道名称不能代替 tvid。官方资料说明数据覆盖未来一周，且在上一周周日更新，因此产品必须展示节目日期和时效边界。

电视节目 API 有哪些端点

截至 2026 年 8 月 19 日，极速数据电视节目预告 API 提供频道目录和节目查询两个端点：

任务 端点 请求方式 必填参数
获取频道目录 https://api.jisuapi.com/tv/channel GET 无业务参数
查询节目单 https://api.jisuapi.com/tv/query GET、POST tvid、date

频道目录返回 tvid、频道名称 name、上级目录 parentid 和是否为电视频道的 istv。节目查询返回指定频道和日期的节目列表。两个端点职责不同，不应让用户输入频道名称后直接拼接请求。

为什么要先同步频道目录

频道接口是节目查询的输入来源。最小请求模板如下：

curl --get "https://api.jisuapi.com/tv/channel" \
  --data-urlencode "appkey=YOUR_APPKEY"

后端可按 parentid 保存目录层级，同时原样保留 tvid 和 istv。是否把某个条目作为节目查询选项，应依据当前文档对 istv 的说明及实际返回验证；不要把频道名称当作唯一键，也不要仅凭 parentid=0 推断该条目一定可查询。

当频道目录更新时，建议采用新旧版本比对：新出现的频道进入待审核状态，消失的频道先停止新增查询但保留历史节目，名称变化则记录别名。这样可以避免频道更名后历史数据全部失去关联。

怎样按日期查询节目单

节目查询需要整数类型的 tvid 和日期字符串 date。模板使用安全占位符：

curl --get "https://api.jisuapi.com/tv/query" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "tvid=YOUR_TV_ID" \
  --data-urlencode "date=YYYY-MM-DD"

请求前应校验日期格式，并把用户选择的频道映射为当前目录中的 tvid。查询结果包含频道 ID、频道名称、日期和 program 列表；列表项包含节目名称 name 与开始时间 starttime。

starttime 是节目单提供的时间文本，入库前要按实际样本验证时区、跨日节目和空值表现。不要为了绘制时间轴而擅自把节目时长、结束时间或时区补进接口事实。若页面需要结束时间，只能基于下一节目开始时间做自有推导，并明确它不是官方返回字段。

一周数据和更新时间怎样设计

官方页面说明该产品提供未来一个星期的节目数据，数据在上一周周日更新。这意味着它适合近期节目预告和频道日历，不等于无限历史节目库，也不能保证节目临时调整后立即同步。

业务侧应保存三个时间概念：节目日期 date、来源数据更新说明、系统抓取时间 fetchedAt。当用户查看超出当前预告窗口的日期时，应显示暂无数据或不在当前预告范围，而不是自动复制相邻日期。

如果同一日期再次抓取到不同节目单，应保留版本或内容摘要，方便追踪临时调整。对外展示时可以标注“数据更新时间”，但不要把接口更新时间改写成电视台实时播出状态。节目是否实际播出、临时停播或延时，应以频道官方公告为准。

错误码怎么处理

官方业务错误码包括 201 电视节目频道为空、202 电视节目频道错误、203 没有信息；系统错误码 101 至 108 涉及 APPKEY、权限、次数、IP 与接口状态。

  • 201：检查是否遗漏 tvid，不要用频道名称替代。
  • 202：刷新频道目录，确认 ID 属于可查询频道。
  • 203：作为本次频道与日期请求“没有信息”处理，不把它进一步解释为频道停播或当天一定无节目。
  • 101 至 108：由服务端统一记录与告警，客户端不显示密钥或内部权限细节。

参数错误和无信息不适合循环重试。网络超时可有限退避重试；若使用缓存降级，必须展示来源日期和抓取时间，避免把旧节目单标成当天实时安排。

上线前检查清单

  1. 频道目录与节目查询分成两个同步任务。
  2. 用 tvid 查询，不把名称当成接口 ID。
  3. 校验 YYYY-MM-DD 日期，并处理预告范围外日期。
  4. 节目名称和开始时间允许为空，不自行补造结束时间。
  5. 保存节目日期、来源更新时间和抓取时间。
  6. 区分无信息、频道错误和系统错误，缓存降级时注明时间。
  7. APPKEY 只保存在服务端，频道目录变化保留版本记录。

端点、字段和错误码可在极速数据电视节目预告 API 官方文档核对。正式用于节目展示前，还应确认内容授权、数据更新时间和电视台临时调整的处理规则。

关于极速数据

极速数据由杭州极速互联科技有限公司运营，提供数据 API 与数据服务。本文只讨论电视节目预告 API 的频道目录、日期查询和时效处理，不把节目预告等同于电视台实时播出状态。