赛程列表 - AnySport

最核心的比赛查询接口，支持按单日、日期区间、联赛+赛季、球队、单场 match_id 等条件自由组合查询，返回比赛基础信息，已完赛场次会附带比分。绝大多数”赛程/赛果/日历”类页面都以本接口为数据源；如果只想查”未来一周”这类相对时间窗口，用近期赛程会更省事（免去自己计算日期）。查到 match_id 后可分别用于单场详情、首发阵容、实时比分、实时赛况等接口深挖单场数据。

接口路径

GET /v1/soccer/matches

入参说明

过滤条件可组合；season 在带 league_id 且无日期/单场限定时必填，其余可选。

参数	类型	必填	说明
`match_id`	string	否	比赛 ID（`as_`）
`date`	string	否	单日，`YYYY-MM-DD`（UTC）
`from` / `to`	string	否	日期区间，`YYYY-MM-DDTHH:mm`示例`from=2026-08-16T20:00&to=2026-08-17T02:00`
`league_id`	string	否	联赛（`asl_`）
`team_id`	string	否	球队（`ast_`）
`season`	string	条件必填	带 `league_id` 且未带任何日期（date/from/to）或 match_id 时必填（含 league+team 组合）；已用日期或单场限定时可省略
`status`	string	否	状态过滤（如 `FT`、`AET`、`Not Started`、`Cancl.`）。进行中/未开赛场次的 status 为纯数字分钟或 `HH:MM` 形态、逐值变化，不适合用该参数筛”进行中/未开赛”，请改用日期范围＋客户端判读
`lang`	string	否	`en` / `zh-CN`，非法值静默回退默认语言，可选值以 `GET /languages`（19）为准
`page` / `limit`	int	否	分页，limit 范围 1~100

带 league_id 而未带 season、且没有日期/单场限定时返回 400。

出参说明（data: 数组）

字段	类型	说明
`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	比赛状态的本地化文本（按 lang 返回，例如 lang=zh-CN 时为 `完场`）；`status` 原值不变；当 lang 为非默认语言、且该文字状态存在本地化文本时下发，并非所有取值都有本地化文本，无对应文本时该字段不下发，客户端需容错（`HH:MM`/纯数字分钟形态无 label）
`league` / `league_id`	string	联赛名 / ID
`season`	string	赛季
`home` / `away`	object	`{ name, team_id }`
`ht_score`	string	半场比分（已完赛场次返回；已归一为 `1-0` 形态，无空格）
`ft_score`	string	常规 90 分钟比分（已完赛场次返回）
`et_score`	string	加时结束的累计比分（如 `3-1`；仅加时赛场次返回，与滚球流 livescore 同口径）
`penalty_score`	string	点球大战比分（仅点球决胜场次返回）
`venue`	string	场馆（可能为空）

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

点球决胜场次status=Pen.）的 ft_score 可能含点球胜方虚记的 1 球et_score 为加时段净比分；判定胜负请用 penalty_score。

枚举说明

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）：进行中，值即当前比赛分钟。

入参示例

# 按 league+season 查赛程
GET /v1/soccer/matches?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&season=2026&limit=5&lang=en

# 按 date+league+season 并用状态值过滤（status=AET）
GET /v1/soccer/matches?date=2026-07-12&league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&season=2026&status=AET&limit=5

出参示例

league+season（HTTP

{
  "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": ""
    },
    {
      "match_id": "as_e59479b08f194c1b91df261d9ca56878",
      "date": "2026-07-14",
      "time": "19:00",
      "status": "19:00",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "2026",
      "home": {
        "name": "France",
        "team_id": "ast_99cc49049ab642909e034538476c64ee"
      },
      "away": {
        "name": "Spain",
        "team_id": "ast_ac0fd01a74b04b61ac8e7b0d8a774cb2"
      },
      "venue": ""
    }
  ],
  "meta": {
    "total": 102,
    "page": 1,
    "limit": 5,
    "total_pages": 21,
    "timestamp": "2026-07-13T19:18:24.076830600Z"
  },
  "traceId": "f11f21f6-0b68-438d-94b7-c8622470176f"
}

{
  "success": true,
  "data": [
    {
      "match_id": "as_3b37c382f39a4235aa93705f053b2da4",
      "date": "2026-07-12",
      "time": "01:00",
      "status": "AET",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "2026",
      "home": {
        "name": "Argentina",
        "team_id": "ast_9137ee449e3b40a68149ca319373adaf"
      },
      "away": {
        "name": "Switzerland",
        "team_id": "ast_499130f3976546089056d8d747b6c059"
      },
      "ht_score": "1-0",
      "ft_score": "1-1",
      "et_score": "3-1",
      "venue": ""
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 5,
    "total_pages": 1,
    "timestamp": "2026-07-13T19:18:24.266517800Z"
  },
  "traceId": "bd249d3c-6058-49de-a23f-a12d6b0ea65a"
}

错误示例

均返回 HTTP 400，error.code INVALID_PARAMS。

# 按 league 缺 season
GET /v1/soccer/matches?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&limit=5

# league+team 缺 season
GET /v1/soccer/matches?league_id=asl_62db9cfc3ebf4b87a44570b16668b23e&team_id=ast_9137ee449e3b40a68149ca319373adaf&limit=5

​接口路径

​入参说明

​出参说明（data: 数组）

​枚举说明

​入参示例

​出参示例

​错误示例

接口路径

入参说明

出参说明（data: 数组）

枚举说明

入参示例

出参示例

错误示例