接口说明
建议每天更新
- 请求方式
GET- 请求地址
https://api.superscore.cn/football/database/matchPage- Content-Type
application/x-www-form-urlencoded;charset=UTF-8
请求头与鉴权
| 字段 | 类型 | 必填 | 文档示例值 | 说明 |
|---|---|---|---|---|
token | string | 是 | 传商户KEY | token(传商户KEY)仅供测试,正式站请设置IP |
商户密钥仅保存在自己的服务端。测试 token 与正式 IP 授权的适用范围以本表及账户授权说明为准。
请求参数
Query 查询参数
| 字段 | 类型 | 必填 | 文档示例值 | 说明 |
|---|---|---|---|---|
current | int32 | 是 | 1 | 页码 |
size | int32 | 是 | 100 | 每页条数(10-200) |
示例值用于说明字段;比赛、球队、联赛等 ID 应从实际接口取得,不能直接使用占位值。字段中的日期、枚举、分页范围与更新建议完整保留原始说明。
调用示例
替换 YOUR_MERCHANT_KEY、YOUR_MATCH_ID 等占位值后,在已授权的服务端调用。示例不会在本页面发起真实请求。
cURL
curl --get 'https://api.superscore.cn/football/database/matchPage' \
--header 'token: YOUR_MERCHANT_KEY' \
--data-urlencode 'current=1' \
--data-urlencode 'size=YOUR_PAGE_SIZE'JavaScript / Node.js
// 仅在服务端保存商户密钥;替换示例占位值。
const url = new URL("https://api.superscore.cn/football/database/matchPage");
url.search = new URLSearchParams({
"current": "1",
"size": "YOUR_PAGE_SIZE"
});
const response = await fetch(url, {
method: "GET",
headers: {
"token": "YOUR_MERCHANT_KEY"
}
});
if (!response.ok) throw new Error('HTTP ' + response.status);
const result = await response.json();
if (result.success !== true) throw new Error(String(result.message || result.code));
console.log(result.data);Python 标准库示例
# 标准库示例;商户密钥仅保存在服务端。
import json
from urllib.parse import urlencode
from urllib.request import Request, urlopen
parameters = {
"current": "1",
"size": "YOUR_PAGE_SIZE"
}
headers = {
"token": "YOUR_MERCHANT_KEY"
}
url = "https://api.superscore.cn/football/database/matchPage"
if parameters:
url += '?' + urlencode(parameters)
with urlopen(Request(url, headers=headers, method="GET"), timeout=15) as response:
result = json.load(response)
if not result.get('success'):
raise RuntimeError(result.get('message') or result.get('code'))
print(result.get('data'))返回参数
字段路径保留完整层级;[] 表示数组元素,<key> 表示按数据内容变化的映射键。success、code、message 与 data 均按接口定义列出。
| 字段路径 | 类型 | 说明与枚举 |
|---|---|---|
success | boolean | 状态码 |
code | string | 状态编号 |
message | string | 描述 |
data | array | 数据 |
data[].matchId | int32 | 比赛ID |
data[].time | int32 | 比赛时间(秒级时间戳) |
data[].status | int32 | 状态:0未开始,1上半场,2中场,3下半场,4加时,5点球,10完场,11取消,12暂停,13推迟,14延迟,15腰斩,16中断,17退赛,18待定,99删除 |
data[].leagueId | int32 | 联赛ID |
data[].seasonId | int32 | 赛季ID |
data[].stageId | int32 | 阶段ID |
data[].venueId | int32 | 球场ID |
data[].groupId | string | 组 |
data[].refereeId | int32 | 裁判ID |
data[].homeScore | string | 主队比赛比分;int数组格式,返回顺序:常规时间比分,半场比分,加时赛比分(不含常规时间),点球比分(不含常规时间和加时赛比分),总分 |
data[].awayScore | string | 客队比赛比分;int数组格式,返回顺序:常规时间比分,半场比分,加时赛比分(不含常规时间),点球比分(不含常规时间和加时赛比分),总分 |
data[].homeId | int32 | 主队ID |
data[].awayId | int32 | 客队ID |
data[].beidan | int32 | 是否有北单:0无,1有主客一致,2有主客相反 |
data[].lottery | int32 | 是否有竞彩:0无,1有主客一致,2有主客相反 |
data[].animation | int32 | 是否有动画 |
data[].stream | int32 | 是否有直播 |
data[].odds | int32 | 是否有指数:0无,1有 |
data[].injuries | int32 | 是否有情报:0无,1有 |
data[].lineup | int32 | 是否有阵容:0无,1有 |
data[].sort | int32 | 排序 |
data[].turnBased | string | 回合制 |
data[].league | object | 联赛信息 |
data[].league.leagueId | int32 | 联赛ID |
data[].league.nameEn | string | 英文名称 |
data[].league.nameShortEn | string | 英文简称 |
data[].league.nameZh | string | 中文名称 |
data[].league.nameShortZh | string | 中文简称 |
data[].league.nameZht | string | 繁体名称 |
data[].league.nameShortZht | string | 繁体简称 |
data[].league.image | string | 联赛图片 |
data[].league.color | string | 颜色 |
data[].league.sort | int32 | 排序 |
data[].home | object | 主队信息 |
data[].home.teamId | int32 | 球队ID |
data[].home.nameEn | string | 英文名称 |
data[].home.nameShortEn | string | 英文简称 |
data[].home.nameZh | string | 中文名称 |
data[].home.nameShortZh | string | 中文简称 |
data[].home.nameZht | string | 繁体名称 |
data[].home.nameShortZht | string | 繁体简称 |
data[].home.image | string | 球队图片 |
data[].away | object | 客队信息 |
data[].away.teamId | int32 | 球队ID |
data[].away.nameEn | string | 英文名称 |
data[].away.nameShortEn | string | 英文简称 |
data[].away.nameZh | string | 中文名称 |
data[].away.nameShortZh | string | 中文简称 |
data[].away.nameZht | string | 繁体名称 |
data[].away.nameShortZht | string | 繁体简称 |
data[].away.image | string | 球队图片 |
data[].stats | object | 统计 |
data[].stats.minute | string | 分钟 |
data[].stats.second | string | 秒 |
data[].stats.overtime | string | 加时 |
data[].stats.startTime | int64 | 上下半场开始时间 |
data[].stats.homeTeam | object | 主队 |
data[].stats.homeTeam.possession | string | 控球率 |
data[].stats.homeTeam.shotOn | int32 | 射正 |
data[].stats.homeTeam.shotOff | int32 | 射偏 |
data[].stats.homeTeam.corner | int32 | 角球 |
data[].stats.homeTeam.yellow | int32 | 黄牌 |
data[].stats.homeTeam.red | int32 | 红牌 |
data[].stats.homeTeam.penalty | int32 | 点球 |
data[].stats.homeTeam.attacks | int32 | 进攻 |
data[].stats.homeTeam.dangerousAttacks | int32 | 危险进攻 |
data[].stats.homeTeam.assists | int32 | 助攻 |
data[].stats.homeTeam.headers | int32 | 头球 |
data[].stats.homeTeam.turnovers | int32 | 丟球 |
data[].stats.homeTeam.saves | int32 | 救球 |
data[].stats.homeTeam.ownGoals | int32 | 乌龙 |
data[].stats.homeTeam.throwIn | int32 | 界外球 |
data[].stats.homeTeam.goalKick | int32 | 球门球 |
data[].stats.homeTeam.tackles | int32 | 成功抢断 |
data[].stats.homeTeam.blocks | int32 | 阻截 |
data[].stats.homeTeam.longPasses | int32 | 长传 |
data[].stats.homeTeam.shortPasses | int32 | 短传 |
data[].stats.homeTeam.crosses | int32 | 成功传中 |
data[].stats.homeTeam.fouls | int32 | 犯规 |
data[].stats.homeTeam.offside | int32 | 越位 |
data[].stats.homeTeam.goalkeeperSaves | int32 | 守门员出击 |
data[].stats.awayTeam | object | 客队 |
data[].stats.awayTeam.possession | string | 控球率 |
data[].stats.awayTeam.shotOn | int32 | 射正 |
data[].stats.awayTeam.shotOff | int32 | 射偏 |
data[].stats.awayTeam.corner | int32 | 角球 |
data[].stats.awayTeam.yellow | int32 | 黄牌 |
data[].stats.awayTeam.red | int32 | 红牌 |
data[].stats.awayTeam.penalty | int32 | 点球 |
data[].stats.awayTeam.attacks | int32 | 进攻 |
data[].stats.awayTeam.dangerousAttacks | int32 | 危险进攻 |
data[].stats.awayTeam.assists | int32 | 助攻 |
data[].stats.awayTeam.headers | int32 | 头球 |
data[].stats.awayTeam.turnovers | int32 | 丟球 |
data[].stats.awayTeam.saves | int32 | 救球 |
data[].stats.awayTeam.ownGoals | int32 | 乌龙 |
data[].stats.awayTeam.throwIn | int32 | 界外球 |
data[].stats.awayTeam.goalKick | int32 | 球门球 |
data[].stats.awayTeam.tackles | int32 | 成功抢断 |
data[].stats.awayTeam.blocks | int32 | 阻截 |
data[].stats.awayTeam.longPasses | int32 | 长传 |
data[].stats.awayTeam.shortPasses | int32 | 短传 |
data[].stats.awayTeam.crosses | int32 | 成功传中 |
data[].stats.awayTeam.fouls | int32 | 犯规 |
data[].stats.awayTeam.offside | int32 | 越位 |
data[].stats.awayTeam.goalkeeperSaves | int32 | 守门员出击 |
data[].stats.updateTime | int64 | 更新时间 |
data[].stats.matchId | int32 | 比赛ID |
data[].stats.status | int32 | 比赛状态 |
data[].stats.animationId | int32 | 动画ID |
data[].stats.homePlayer | array | 主队球员统计 |
data[].stats.homePlayer[].playerId | int32 | 球员ID |
data[].stats.homePlayer[].nameEn | string | 球员名称(英文) |
data[].stats.homePlayer[].nameZh | string | 球员名称(中文) |
data[].stats.homePlayer[].image | string | 球员图片 |
data[].stats.homePlayer[].number | string | 号码 |
data[].stats.homePlayer[].position | int32 | 位置:1守门员,2后卫,3中场,4前锋 |
data[].stats.homePlayer[].goals | int32 | 进球 |
data[].stats.homePlayer[].assists | int32 | 助攻 |
data[].stats.homePlayer[].shots | int32 | 射门 |
data[].stats.homePlayer[].shotsOnTarget | int32 | 射正 |
data[].stats.homePlayer[].keyPasses | int32 | 关键传球 |
data[].stats.homePlayer[].passes | int32 | 传球 |
data[].stats.homePlayer[].passesSuccessful | int32 | 传球成功 |
data[].stats.homePlayer[].tackles | int32 | 抢断 |
data[].stats.homePlayer[].interceptions | int32 | 拦截 |
data[].stats.homePlayer[].clearances | int32 | 解围 |
data[].stats.homePlayer[].fouls | int32 | 犯规 |
data[].stats.homePlayer[].foulsDrawn | int32 | 被犯规 |
data[].stats.homePlayer[].yellowCards | int32 | 黄牌 |
data[].stats.homePlayer[].redCards | int32 | 红牌 |
data[].stats.homePlayer[].rating | string | 评分 |
data[].stats.awayPlayer | array | 客队球员统计 |
data[].stats.awayPlayer[].playerId | int32 | 球员ID |
data[].stats.awayPlayer[].nameEn | string | 球员名称(英文) |
data[].stats.awayPlayer[].nameZh | string | 球员名称(中文) |
data[].stats.awayPlayer[].image | string | 球员图片 |
data[].stats.awayPlayer[].number | string | 号码 |
data[].stats.awayPlayer[].position | int32 | 位置:1守门员,2后卫,3中场,4前锋 |
data[].stats.awayPlayer[].goals | int32 | 进球 |
data[].stats.awayPlayer[].assists | int32 | 助攻 |
data[].stats.awayPlayer[].shots | int32 | 射门 |
data[].stats.awayPlayer[].shotsOnTarget | int32 | 射正 |
data[].stats.awayPlayer[].keyPasses | int32 | 关键传球 |
data[].stats.awayPlayer[].passes | int32 | 传球 |
data[].stats.awayPlayer[].passesSuccessful | int32 | 传球成功 |
data[].stats.awayPlayer[].tackles | int32 | 抢断 |
data[].stats.awayPlayer[].interceptions | int32 | 拦截 |
data[].stats.awayPlayer[].clearances | int32 | 解围 |
data[].stats.awayPlayer[].fouls | int32 | 犯规 |
data[].stats.awayPlayer[].foulsDrawn | int32 | 被犯规 |
data[].stats.awayPlayer[].yellowCards | int32 | 黄牌 |
data[].stats.awayPlayer[].redCards | int32 | 红牌 |
data[].stats.awayPlayer[].rating | string | 评分 |
data[].Weather | object | 天气 |
data[].Weather.weather | string | 天气 |
data[].Weather.temperature | string | 温度 |
data[].Weather.windSpeed | string | 风速 |
data[].Weather.humidity | string | 湿度 |
响应结构示例
下面的值仅展示字段类型,不是实时数据或真实调用结果。动态 map 的键取决于实际返回,不编造固定字段。
展开完整 JSON 结构
{
"success": false,
"code": "示例字符串",
"message": "示例字符串",
"data": [
{
"matchId": 0,
"time": 0,
"status": 0,
"leagueId": 0,
"seasonId": 0,
"stageId": 0,
"venueId": 0,
"groupId": "示例字符串",
"refereeId": 0,
"homeScore": "示例字符串",
"awayScore": "示例字符串",
"homeId": 0,
"awayId": 0,
"beidan": 0,
"lottery": 0,
"animation": 0,
"stream": 0,
"odds": 0,
"injuries": 0,
"lineup": 0,
"sort": 0,
"turnBased": "示例字符串",
"league": {
"leagueId": 0,
"nameEn": "示例字符串",
"nameShortEn": "示例字符串",
"nameZh": "示例字符串",
"nameShortZh": "示例字符串",
"nameZht": "示例字符串",
"nameShortZht": "示例字符串",
"image": "示例字符串",
"color": "示例字符串",
"sort": 0
},
"home": {
"teamId": 0,
"nameEn": "示例字符串",
"nameShortEn": "示例字符串",
"nameZh": "示例字符串",
"nameShortZh": "示例字符串",
"nameZht": "示例字符串",
"nameShortZht": "示例字符串",
"image": "示例字符串"
},
"away": {
"teamId": 0,
"nameEn": "示例字符串",
"nameShortEn": "示例字符串",
"nameZh": "示例字符串",
"nameShortZh": "示例字符串",
"nameZht": "示例字符串",
"nameShortZht": "示例字符串",
"image": "示例字符串"
},
"stats": {
"minute": "示例字符串",
"second": "示例字符串",
"overtime": "示例字符串",
"startTime": 0,
"homeTeam": {
"possession": "示例字符串",
"shotOn": 0,
"shotOff": 0,
"corner": 0,
"yellow": 0,
"red": 0,
"penalty": 0,
"attacks": 0,
"dangerousAttacks": 0,
"assists": 0,
"headers": 0,
"turnovers": 0,
"saves": 0,
"ownGoals": 0,
"throwIn": 0,
"goalKick": 0,
"tackles": 0,
"blocks": 0,
"longPasses": 0,
"shortPasses": 0,
"crosses": 0,
"fouls": 0,
"offside": 0,
"goalkeeperSaves": 0
},
"awayTeam": {
"possession": "示例字符串",
"shotOn": 0,
"shotOff": 0,
"corner": 0,
"yellow": 0,
"red": 0,
"penalty": 0,
"attacks": 0,
"dangerousAttacks": 0,
"assists": 0,
"headers": 0,
"turnovers": 0,
"saves": 0,
"ownGoals": 0,
"throwIn": 0,
"goalKick": 0,
"tackles": 0,
"blocks": 0,
"longPasses": 0,
"shortPasses": 0,
"crosses": 0,
"fouls": 0,
"offside": 0,
"goalkeeperSaves": 0
},
"updateTime": 0,
"matchId": 0,
"status": 0,
"animationId": 0,
"homePlayer": [
{
"playerId": 0,
"nameEn": "示例字符串",
"nameZh": "示例字符串",
"image": "示例字符串",
"number": "示例字符串",
"position": 0,
"goals": 0,
"assists": 0,
"shots": 0,
"shotsOnTarget": 0,
"keyPasses": 0,
"passes": 0,
"passesSuccessful": 0,
"tackles": 0,
"interceptions": 0,
"clearances": 0,
"fouls": 0,
"foulsDrawn": 0,
"yellowCards": 0,
"redCards": 0,
"rating": "示例字符串"
}
],
"awayPlayer": [
{
"playerId": 0,
"nameEn": "示例字符串",
"nameZh": "示例字符串",
"image": "示例字符串",
"number": "示例字符串",
"position": 0,
"goals": 0,
"assists": 0,
"shots": 0,
"shotsOnTarget": 0,
"keyPasses": 0,
"passes": 0,
"passesSuccessful": 0,
"tackles": 0,
"interceptions": 0,
"clearances": 0,
"fouls": 0,
"foulsDrawn": 0,
"yellowCards": 0,
"redCards": 0,
"rating": "示例字符串"
}
]
},
"Weather": {
"weather": "示例字符串",
"temperature": "示例字符串",
"windSpeed": "示例字符串",
"humidity": "示例字符串"
}
}
]
}错误处理与使用说明
- 先检查 HTTP 状态,再解析 JSON;网络失败或非 JSON 响应不能当作成功。
- 业务响应 success 为 false 时,读取 code 和 message;不要把业务错误与 HTTP 状态混为一谈。
- 保存原始错误码、请求时间及接口路径用于排查,日志中移除商户密钥。
- 按该接口的数据更新建议、账户授权和调用频率请求;日期和时间戳单位以字段说明为准。
- 允许字段缺失或数据为空,按接口中的稳定 ID 关联资料,不依赖数组顺序。