近期赛程 - AnySport

赛程列表的相对日期版本：用 from_days/to_days 表达”距今多少天”，而不需要客户端自己计算绝对日期，适合”未来一周赛程""最近战报”这类相对时间窗口的场景，输出字段结构与 10 完全一致。同时也是发现”未开赛/进行中”比赛、进而拿到 match_id 供实时比分、实时赛况、滚球赔率使用的推荐入口。

接口路径

GET /v1/soccer/matches/window

查询距今 from_days ~ to_days 天内（UTC 日期，含两端）的比赛，免去客户端自行计算日期：from_days=0&to_days=7 = 未来一周，from_days=-3&to_days=0 = 近 3 天（含今天）。也是发现”未开赛 / 进行中”比赛的推荐入口（拉回后按 status 形态判读）。

入参说明

参数	类型	必填	默认	说明
`from_days`	int	否	0	窗口起点（相对今天的天数偏移，可为负=过去）
`to_days`	int	否	7	窗口终点（相对今天的天数偏移）；须 ≥ from_days，跨度最大 90 天，否则 400
`league_id`	string	否		联赛过滤（`asl_`）；已有日期限定，无需 season
`team_id`	string	否		球队过滤（`ast_`）
`status`	string	否		状态过滤（规则同赛程列表；`FT` 不含加时/点球决胜场次）
`lang`	string	否	en	`en` / `zh-CN`，非法值静默回退默认语言，可选值以 `GET /languages`（19）为准
`page` / `limit`	int	否	1 / 50	分页，limit 范围 1~100

出参说明（data: 数组）

与赛程列表（GET /matches）完全一致（内部即 /matches 的 from/to 查询）：

字段	类型	说明
`match_id`	string	比赛 ID（`as_` 前缀，全接口统一）
`date`	string	开赛日期 `YYYY-MM-DD`（UTC，ISO）
`time`	string	开赛时间 `HH:mm`（UTC）
`status`	string	文字状态（`FT`/`AET`/`Not Started`…）/ `HH:MM` 开赛时间 / 纯数字分钟，可能为空串
`status_label`	string	比赛状态的本地化文本（如 zh-CN `完场`）；`status` 原值不变，当 lang 为非默认语言、且该取值存在本地化文本时下发。并非所有取值都有本地化文本；无对应文本时该字段不下发，客户端需容错（`HH:MM`/纯数字分钟形态无 label）
`league`	string	联赛名
`league_id`	string	联赛 ID（`asl_`）
`season`	string	赛季
`home`	object	主队 `{ name, team_id }`
`away`	object	客队 `{ name, team_id }`
`ht_score`	string	半场比分（已完赛场次返回，无空格）
`ft_score`	string	常规 90 分钟比分（已完赛场次返回）
`et_score`	string	加时结束的累计比分（仅加时赛场次返回）
`penalty_score`	string	点球大战比分（仅点球决胜场次返回）
`venue`	string	场馆（可能为空）

*_label 约定：当 lang 为非默认语言时 status 保留原值，另新增平行本地化标签 status_label（仅文字状态可有本地化文本）。并非所有取值都有本地化文本；无对应文本时该字段不下发，客户端需容错。队名/联赛名（home/away/league）暂不随 lang 本地化。

status 形态判读：未开赛 = HH:MM / Not Started / TBA / 空串，进行中 = 纯数字分钟 / HT（及低频的 ET/P/Break Time）。查到的 match_id 可直接用于 livescore 与 situation。

枚举说明

status（字符串，三种形态）： 1). 文字状态：

枚举值	含义
`Not Started`	未开赛：未开始
`TBA`	未开赛：时间待定（To Be Announced）
“（空串）	未开赛：未排期/未标注，视为未开赛
`HT`	进行中：中场休息
`ET`	进行中：加时赛进行中（官方词表收录，历史库低频）
`P`	进行中：点球大战进行中（官方词表收录，历史库低频）
`Break Time`	进行中：加时上下半场之间/加时与点球大战之间的休息（官方词表收录）
`FT`	已结束：常规时间结束（Full Time，最常见）
`AET`	已结束：加时赛后结束（After Extra Time）
`Pen.`	已结束：点球大战决出（Penalties）
`Awarded`	已结束：判负/判胜（Technical loss，弃权、资格问题等行政判定）
`WO`	已结束：弃权/不战而胜（Walkover，官方词表收录，历史库低频）
`Postp.`	延期：延期（Postponed）
`Delayed`	延期：推迟开赛（官方词表收录，历史库低频）
`Cancl.` / `Cancelled`	取消：取消
`Abandoned` / `Aban.`	中断：比赛中断废弃
`Susp.`	中断：暂停（开赛后中断，官方词表收录，历史库低频）
`Int.`	中断：中断（Interrupted，官方词表收录，历史库低频）

2). HH:MM 形态（如 15:00、19:45）：未开赛，值即 UTC 开赛时间（与 time 字段一致）。 3). 纯数字形态（如 9、45、88）：进行中，值即当前比赛分钟。

入参示例

# 未来一周的世界杯赛程
GET /v1/soccer/matches/window?from_days=0&to_days=7&league_id=asl_62db9cfc3ebf4b87a44570b16668b23e

# 近 3 天常规时间完赛（FT）的比赛
GET /v1/soccer/matches/window?from_days=-3&to_days=0&status=FT

出参示例（结构与赛程列表相同）

{
  "success": true,
  "data": [
    {
      "match_id": "as_37f0da0520bb4e9a9588f80994cefc5b",
      "date": "2026-07-15",
      "time": "19:00",
      "status": "19:00",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "2026",
      "home": {
        "name": "England",
        "team_id": "ast_13e4e7eccd7640de91c13cffcf0c3ff2"
      },
      "away": {
        "name": "Argentina",
        "team_id": "ast_9137ee449e3b40a68149ca319373adaf"
      },
      "venue": ""
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "total_pages": 1,
    "timestamp": "2026-07-13T19:18:24.076830600Z"
  },
  "traceId": "f11f21f6-0b68-438d-94b7-c8622470176f"
}

错误示例

from_days > to_days（或窗口跨度超 90 天）→ HTTP 400，error.code INVALID_PARAMS

GET /v1/soccer/matches/window?from_days=5&to_days=0

​接口路径

​入参说明

​出参说明（data: 数组）

​枚举说明

​入参示例

​出参示例（结构与赛程列表相同）

​错误示例

接口路径

入参说明

出参说明（data: 数组）

枚举说明

入参示例

出参示例（结构与赛程列表相同）

错误示例