交锋历史 - AnySport

给定两支球队 team1_id/team2_id，返回二者近 N 场（默认 10 场，可调）的历史交锋记录，字段结构与赛程列表一致。典型用于赛前分析页的”历史交锋”板块，帮助用户快速了解两队过往战绩与近期走势。

接口路径

GET /v1/soccer/head2head

入参说明

参数	类型	必填	默认	说明
`team1_id`	string	是		球队1（`ast_`）
`team2_id`	string	是		球队2（`ast_`）
`limit`	int	否	10	返回近 N 场（1~100）
`lang`	string	否	en	目标语言（如 `zh-CN`），非法值静默回退默认语言，可选值以 `GET /v1/soccer/languages` 为权威来源

出参说明（data: 数组）

字段	类型	说明
`match_id`	string	比赛 ID（`as_` 前缀，全接口统一）
`date`	string	开赛日期 `YYYY-MM-DD`（UTC，ISO）
`time`	string	开赛时间 `HH:mm`（UTC）
`status`	string	三种形态完整枚举见下方”枚举说明”
`status_label`	string	比赛状态的本地化文本；`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	半场比分（已归一为 `2-2` 形态，无空格）
`ft_score`	string	常规 90 分钟比分
`et_score`	string	加时结束的累计比分（无加时不返回）
`penalty_score`	string	点球大战比分（无则不返回）
`venue`	string	场馆

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

枚举说明

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/head2head?team1_id=ast_9137ee449e3b40a68149ca319373adaf&team2_id=ast_13e4e7eccd7640de91c13cffcf0c3ff2&limit=5&lang=en

出参示例

交锋历史示例：阿根廷 vs 英格兰（节选）

{
  "success": true,
  "data": [
    {
      "match_id": "as_794ea6e4273c488c8d2038832bed3059",
      "date": "1998-06-30",
      "time": "19:00",
      "status": "Pen.",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "1998",
      "home": {
        "name": "Argentina",
        "team_id": "ast_9137ee449e3b40a68149ca319373adaf"
      },
      "away": {
        "name": "England",
        "team_id": "ast_13e4e7eccd7640de91c13cffcf0c3ff2"
      },
      "ht_score": "2-2",
      "ft_score": "2-2",
      "venue": "Stade Geoffroy-Guichard (Saint-Ètienne)"
    },
    {
      "match_id": "as_86b9a00a78ba4e1a8c60d01e4c9fdd96",
      "date": "1966-07-23",
      "time": "14:00",
      "status": "FT",
      "league": "World Cup",
      "league_id": "asl_62db9cfc3ebf4b87a44570b16668b23e",
      "season": "1966",
      "home": {
        "name": "England",
        "team_id": "ast_13e4e7eccd7640de91c13cffcf0c3ff2"
      },
      "away": {
        "name": "Argentina",
        "team_id": "ast_9137ee449e3b40a68149ca319373adaf"
      },
      "ht_score": "0-0",
      "ft_score": "1-0",
      "venue": "Wembley Stadium (old) (London)"
    }
  ],
  "meta": {
    "total": 5,
    "timestamp": "2026-07-13T19:18:24.654061Z"
  },
  "traceId": "d0128f3b-d0c1-4dd4-8f30-a74ed49048e2"
}