📅
赛程与赛事列表
按日期与项目返回完整赛程，包含赛事名称、轮次、对阵双方与开赛时间，支持按足球等主打项目筛选，便于快速搭建当日赛事总览。
接口说明 - jinnianhui官网
本栏目是 jinnianhui官网面向合作方与资深球迷设立的技术说明专区，系统整理本站赛事数据、即时比分与直播信息在对外服务中的字段口径、刷新机制与调用规范。作为综合门户，金年会的内容覆盖足球、篮球等多个项目，其中足球为主打方向，所有数据遵循实时更新、每分钟刷新的统一节奏。本栏目会逐项说明每个数据接口返回的字段含义、时间戳标准、状态标识与异常处理方式，并给出常见的对接示例与校验方法。对于长期关注赛事、对数据准确性要求较高的资深球迷和机构用户而言，这里可以帮助你在接入前准确理解数据结构，减少因口径不一致造成的误读。今年会持续维护本栏目内容，接口发生调整时会同步更新说明，建议在正式接入前完整阅读一遍，并对照自身业务场景确认所需字段与更新频率是否匹配。
接口能力概览
⚽
即时比分数据
提供进行中与已结束比赛的比分、阶段与时间信息，数据每分钟刷新一次，返回字段附带更新时间戳，方便前端判断数据新鲜度。
📺
直播信息索引
给出每场比赛对应的直播状态与信号类型标识，仅作信息索引用途，帮助用户在赛事列表页直接判断该场次当前是否提供直播入口。
📊
技术统计字段
涵盖控球比例、射门次数、角球与犯规等常规统计项的字段定义，每项均注明取值范围与统计口径，避免不同端展示时产生歧义。
📰
资讯与图文内容
返回赛事相关资讯的标题、摘要、发布时间与来源标识，字段结构统一，支持按项目与时间范围拉取，用于资讯流的聚合展示。
🔔
状态与异常标识
定义比赛延期、中断、取消等异常状态的枚举值，并说明对应字段的返回规则，让接入方能够准确区分正常完赛与非正常结束的情况。
接入前需要看清的几个要点
字段口径是否写清楚
接口说明的价值首先体现在字段定义的完整度上。一份合格的说明会逐字段列出名称、类型、取值范围与业务含义，尤其是时间字段要注明是开赛时间还是数据更新时间、采用哪个时区。判断方法很直接：拿一份真实返回的数据，逐条对照说明，看是否每个字段都能在文档里找到解释。若出现返回有值但文档未提及的字段，说明维护并不同步，后续排查问题会非常被动。
刷新频率与实际表现是否一致
本站对外口径是数据每分钟刷新，那么说明文档就应写明刷新周期、更新触发条件以及时间戳字段的位置。客户通常会关心高峰期是否会延迟、比赛进行中与结束后更新频率是否相同。建议在正式接入前，选取同一场比赛连续观察一段时间，记录时间戳的变化间隔，用实际数据验证文档承诺，而不是只看文字描述。
异常与边界情况有无覆盖
第一次接触的人最容易忽略这一块。比赛延期、场地变更、数据源临时中断都属于常见情况，说明里应当给出对应的状态码与返回示例，并明确此时哪些字段会为空、哪些字段仍然可信。如果文档只描述了理想路径，接入方在遇到异常返回时就只能靠猜，容易把空值误判为真实数据。
版本与变更记录是否可追溯
接口会随业务演进调整，好的说明会保留版本号与变更记录，注明每次调整涉及的字段、生效时间以及是否向下兼容。对接方据此可以评估升级成本，安排自己的发版节奏。若文档没有版本标注，一旦字段结构变化，历史代码可能静默失效，排查成本会显著上升。
调用约束与错误码是否明确
说明中应写清请求频率限制、单次返回条数上限、分页方式以及各类错误码的含义与建议处理动作。客户通常关注的是：达到限制时返回什么、是否需要退避重试、重试间隔建议多久。把这些写进文档，接入方才能设计出稳定的拉取策略，而不是在出问题后反复试探。
示例与自检手段是否齐备
一份实用的说明会为每个接口提供完整的请求示例与响应示例，并给出可自行验证的字段校验方法，例如用时间戳比对当前时间判断数据是否新鲜。对资深球迷和机构用户来说，这些细节决定了接入是几天完成还是反复沟通数周。建议在阅读时把示例直接跑一遍，确认返回结构与文档描述完全吻合再进入开发。
常见问题
数据多久更新一次，如何确认拿到的是最新数据？
本站数据遵循每分钟刷新的统一节奏。每次返回都会附带更新时间戳字段，接入方可以将其与本地当前时间比对，差值明显偏大时即可判定为数据延迟，建议在页面上给出相应提示而不是直接展示。
足球之外的项目是否也提供同样的字段结构？
足球是本站主打项目，字段说明最为完整。其他项目在赛程、比分与状态标识上沿用同一套基础结构，仅在技术统计项上存在差异，具体可见各项目对应的字段附表。
接口调整后旧版本还能继续使用吗？
每次调整都会在变更记录中注明生效时间与兼容情况。涉及字段增删的调整会保留一段过渡期，过渡期内新旧结构并行返回，方便接入方平滑迁移。
第一次接入应该从哪一部分开始看？
建议先阅读字段口径与刷新机制两节，确认数据能满足自身展示需求，再查看异常状态与错误码部分，最后用示例请求跑通一次完整流程。按这个顺序推进，可以避免在开发中段才发现口径不符而返工。