⚽OpenData足球数据开放平台
中EN登录控制台免费试用 14 天

← 返回接口文档

GET/api/v1/matches/basics

获取比赛列表
资料库数据包activebetacore可调用(数据有范围)

接口说明

返回全量比赛数据，可根据时间戳增量获取新增或变动的数据

1、首次全量更新，根据参数id获取全量数据
2、后续增量更新，根据参数time增量获取变动数据（建议请求频次：1min/次）

调用信息

请求
GET https://api.sports.csap.ai/api/v1/matches/basics
鉴权
请求头 X-API-Key: <你的 key>(也支持 Authorization: Bearer <key>;?key= 仍可用但不建议,key 会留在地址和日志里)
外部 key
可调用(数据有范围)外部 key 可以调用，但只返回开放范围内的数据，见「通用说明 · 外部 key 的数据范围」。
频率限制
每分钟 3000 次 · 每天 200000 次 · 按 key 配置(以 /api/v1/account 返回的 rate_per_min、quota_daily 为准;上面是试用 key 的值),超出回 429。另外整表快照、不带比赛 id 的统计列表等重型请求全站同时只处理 2 个,排不上回 429 + Retry-After。响应里暂时没有 X-RateLimit-* 头。 详见通用说明

请求参数 3

参数类型必填示例说明
idinteger可选5179查询大于等于id的记录，根据id排序
timeinteger可选查询大于等于更新时间的记录(时间戳)，根据更新时间排序
limitinteger可选2返回数据最大数，默认为1000，最大为1000

请求示例

curl "https://api.sports.csap.ai/api/v1/matches/basics?limit=2" \
  -H "X-API-Key: YOUR_API_KEY"

在线调试

示例返回

下面是 2026/11/09 22:28(北京时间) 用外部 key 实际请求的返回:HTTP 200,2 行,253 ms(数据只留前 2 行)

{
  "code": 0,
  "data": [
    {
      "agg_score": null,
      "assistant1": null,
      "assistant2": null,
      "assistant_var": null,
      "away_corner": 0,
      "away_gtid": 4,
      "away_logo": "http://43.99.60.51:8080/logos/7831f4f13766be113c7d5bd7a86ea6b6b7655b2fcb6489fccb4892557c93bc6c.webp",
      "away_ot": null,
      "away_pen": 0,
      "away_position": null,
      "away_red": 0,
      "away_score": 3,
      "away_scores": 1,
      "away_team": "KRC Genk U19",
      "away_team_id": 4,
      "away_yellow": 3,
      "away_zh": "亨克U19",
      "comp_logo": "http://43.99.60.51:8080/logos/9addc564a659ede798792b5cfe73468d5aaf32a48f84587300750f55c6f53834.png",
      "comp_ref": null,
      "competition_id": 3,
      "coverage": null,
      "cur_period_start": 1793714739,
      "ended": null,
      "environment": null,
      "fourth": null,
      "gcid": 3,
      "gmid": 1,
      "group_num": null,
      "half_away": 1,
      "half_home": 2,
      "has_ot": null,
      "home_corner": 0,
      "home_gtid": 3,
      "home_logo": "http://43.99.60.51:8080/logos/1648702a19007e2b0e9338d0f790dbc09b2cb4066fb0187194e1f67b98509a9c.webp",
      "home_ot": null,
      "home_pen": 0,
      "home_position": null,
      "home_red": 2,
      "home_score": 4,
      "home_scores": 2,
      "home_team": "Red Bull Salzburg U19",
      "home_team_id": 3,
      "home_yellow": 2,
      "home_zh": "萨尔茨堡U19",
      "humidity": null,
      "id": 1,
      "intelligence": null,
      "league": "UEFA Youth League",
      "league_zh": "欧青联 第二圈 次回合",
      "limit": null,
      "lineup": null,
      "loss": null,
      "match_time": "2026-11-03T13:00:00Z",
      "max_id": null,
      "max_time": null,
      "min_id": null,
      "min_time": null,
      "minute": null,
      "mlive": null,
      "neutral": null,
      "note": null,
      "period_initial": 2700,
      "pressure": null,
      "query": null,
      "referee_id": null,
      "referees": null,
      "related_id": null,
      "round": null,
      "round_num": null,
      "season_id": null,
      "source": "merged",
      "sources": "S5,S9,S4,S3,S2,S8",
      "stage_id": null,
      "start_ts": "2026-11-03T13:00:00Z",
      "status_code": 8,
      "status_id": 8,
      "status_type": "finished",
      "tbd": null,
      "team_reverse": null,
      "temperature": null,
      "time": null,
      "type": null,
      "updated_at": 1794107207241,
      "var": null,
      "venue_id": null,
      "weather": null,
      "wind": null
    },
    {
      "agg_score": null,
      "assistant1": null,
      "assistant2": null,
      "assistant_var": null,
      "away_corner": 4,
      "away_gtid": 14,
      "away_logo": "http://43.99.60.51:8080/logos/8d256871b885c1ceec0af16920cbf7cf6864fc1515494da47629d5fcf2dd9c24.webp",
      "away_ot": null,
      "away_pen": 0,
      "away_position": null,
      "away_red": 0,
      "away_score": 1,
      "away_scores": 0,
      "away_team": "Riffa",
      "away_team_id": 14,
      "away_yellow": 2,
      "away_zh": "阿尔里法",
      "comp_logo": "http://43.99.60.51:8080/logos/637acfb3646144c4309add12936f7ca3a16ecb9ab75cb574103c50b711d19529.png",
      "comp_ref": null,
      "competition_id": 4,
      "coverage": null,
      "cur_period_start": 1793720726,
      "ended": null,
      "environment": null,
      "fourth": null,
      "gcid": 4,
      "gmid": 2,
      "group_num": null,
      "half_away": 0,
      "half_home": 0,
      "has_ot": null,
      "home_corner": 6,
      "home_gtid": 13,
      "home_logo": "http://43.99.60.51:8080/logos/1324a3b41616bbbaebf750902d74e5bf3fde11db44b686b6d86954e1b5cb58b7.png",
      "home_ot": null,
      "home_pen": 0,
      "home_position": null,
      "home_red": 0,
      "home_score": 1,
      "home_scores": 0,
      "home_team": "Al-Zawraa",
      "home_team_id": 13,
      "home_yellow": 1,
      "home_zh": "扎瓦拉",
      "humidity": null,
      "id": 2,
      "intelligence": null,
      "league": "Gulf Club Champions League",
      "league_zh": "海湾锦标",
      "limit": null,
      "lineup": null,
      "loss": null,
      "match_time": "2026-11-03T14:30:00Z",
      "max_id": null,
      "max_time": null,
      "min_id": null,
      "min_time": null,
      "minute": "Ended",
      "mlive": null,
      "neutral": null,
      "note": null,
      "period_initial": 2700,
      "pressure": null,
      "query": null,
      "referee_id": null,
      "referees": null,
      "related_id": null,
      "round": null,
      "round_num": null,
      "season_id": null,
      "source": "merged",
      "sources": "S5,S9,S3,S2,S8",
      "stage_id": null,
      "start_ts": "2026-11-03T14:30:00Z",
      "status_code": 8,
      "status_id": 8,
      "status_type": "finished",
      "tbd": null,
      "team_reverse": null,
      "temperature": null,
      "time": null,
      "type": null,
      "updated_at": 1794107162969,
      "var": null,
      "venue_id": null,
      "weather": null,
      "wind": null
    }
  ],
  "message": "success",
  "success": true
}

返回字段 87

agg_scorenull可为空双回合常规时间(包括加时时间)总比分 字段说明 · example：[3, 6]
assistant1null可为空助理裁判1
assistant2null可为空助理裁判2
assistant_varnull可为空var助理裁判 字段说明 · example：[6261, 6262]
away_cornerinteger客队角球数示例: 0
away_gtidinteger客队我方球队 id示例: 4
away_logostring客队 logo(本平台的图片地址)
away_otnull可为空客队加时比分
away_peninteger客队点球大战比分示例: 0
away_positionnull可为空客队排名
away_redinteger客队红牌数示例: 0
away_scoreinteger客队比分(常规时间,含补时)示例: 3
away_scoresinteger比分字段说明 · example：[1, 0, 0, 0, -1, 0, 0]示例: 1
away_teamstring客队名(英文)示例: "KRC Genk U19"
away_team_idinteger客队id示例: 4
away_yellowinteger客队黄牌数示例: 3
away_zhstring客队中文名示例: "亨克U19"
comp_logostring赛事 logo(本平台的图片地址)
comp_refnull可为空来源内的赛事 id
competition_idinteger赛事 id示例: 3
coveragenull可为空动画、情报、阵容 字段
cur_period_startinteger当前阶段开始时间(Unix 秒)示例: 1793714739
endednull可为空结束时间（有数据时返回）
environmentnull可为空比赛环境,有数据才有此字段
fourthnull可为空第四官员
gcidinteger我方赛事 id示例: 3
gmidinteger我方比赛 id(gmid,全平台唯一)示例: 1
group_numnull可为空第几组，1-A、2-B以此类推
half_awayinteger客队半场比分示例: 1
half_homeinteger主队半场比分示例: 2
has_otnull可为空是否有加时 1.是（有数据时返回）
home_cornerinteger主队角球数示例: 0
home_gtidinteger主队我方球队 id示例: 3
home_logostring主队 logo(本平台的图片地址;没有时为空)
home_otnull可为空主队加时比分
home_peninteger主队点球大战比分示例: 0
home_positionnull可为空主队排名
home_redinteger主队红牌数示例: 2
home_scoreinteger主队比分(常规时间,含补时)示例: 4
home_scoresinteger比分字段说明 · example：[1, 0, 0, 0, -1, 0, 0]示例: 2
home_teamstring主队名(英文)示例: "Red Bull Salzburg U19"
home_team_idinteger主队id示例: 3
home_yellowinteger主队黄牌数示例: 2
home_zhstring主队中文名示例: "萨尔茨堡U19"
humiditynull可为空湿度
idinteger记录 id;翻页游标(id 参数取 >= 此值的记录)。比赛类接口里是我方比赛 id(gmid)示例: 1
intelligencenull可为空是否有情报，1-是、0-否
leaguestring赛事名(英文)示例: "UEFA Youth League"
league_zhstring赛事中文名示例: "欧青联 第二圈 次回合"
limitnull可为空本次最多返回条数
lineupnull可为空是否有阵容，1-是、0-否
lossnull可为空是否判负 1.是（有数据时返回）
match_timestring开赛时间(UTC,ISO 8601)示例: "2026-11-03T13:00:00Z"
max_idnull可为空本页最大 id
max_timenull可为空本页最大更新时间(Unix 秒)
min_idnull可为空本页最小 id
min_timenull可为空本页最小更新时间(Unix 秒)
minutestring可为空比赛进行分钟示例: "Ended"
mlivenull可为空是否有动画，1-是、0-否
neutralnull可为空是否中立场，1-是、0-否
notenull可为空备注
period_initialinteger当前阶段起始分钟示例: 2700
pressurenull可为空气压
querynull可为空查询信息(翻页游标、总数)
referee_idnull可为空裁判id
refereesnull可为空裁判组,有数据才有此字段
related_idnull可为空双回合中另一回合比赛id
roundnull可为空轮次
round_numnull可为空第几轮
season_idnull可为空赛季 id
sourcestring数据来源代号(S1、S2…)示例: "merged"
sourcesstring这条合并记录的来源代号列表(逗号分隔)示例: "S5,S9,S4,S3,S2,S8"
stage_idnull可为空阶段id
start_tsstring开赛时间(UTC,ISO 8601)示例: "2026-11-03T13:00:00Z"
status_codeinteger状态码示例: 8
status_idinteger比赛状态码(见状态与类型码对照表)示例: 8
status_typestring比赛状态:notstarted 未开赛 / inprogress 进行中 / finished 已结束 等示例: "finished"
tbdnull可为空比赛时间是否待定 1.是（有数据时返回）
team_reversenull可为空是否主客相反 1.是（有数据时返回 eg：相反-官网A vs B、本平台B vs A）
temperaturenull可为空温度
timenull可为空时间 / 分钟
typenull可为空类型
updated_atinteger最后更新时间(UTC,ISO 8601;增量同步用 time 参数按它取)示例: 1794107207241
varnull可为空var裁判
venue_idnull可为空场馆id
weathernull可为空天气id · 1:局部有云 · 2:多云 · 3:局部有云/雨 · 4:雪 · 5:晴 · 6:阴有雨/局部有雷暴 · 7:阴 · 8:薄雾 · 9:阴有雨 · 10:多云有雨 · 11:多云有雨/局部有雷暴 · 12:局部有云/雨和雷暴 · 13:雾
windnull可为空风速

错误码

HTTPmessage场景
401missing API key / unauthorized没带 X-API-Key 或 key 无效、已停用
400bad param …参数格式不对(如 id 不是数字或 u<uid>)
301match merged into <gmid>按旧比赛 id 查,这场已合并到新 gmid:Location 指向新地址,返回体带 moved_to
404not found比赛 / 球队 / 赛事不存在,或不在这个 key 的可见范围内(外部 key 只能看到开放范围内的比赛)
429rate limit exceeded / daily quota exceeded超过 key 的每分钟次数或每日配额
429server busy, retry later服务端并发名额已满(重型请求同时只有 2 个),按 Retry-After 秒后重试
500query error服务端查询失败,可重试