接口说明
按需请求
- 请求方式
GET- 请求地址
https://api.superscore.cn/football/database/match- Content-Type
application/x-www-form-urlencoded;charset=UTF-8
请求头与鉴权
| 字段 | 类型 | 必填 | 文档示例值 | 说明 |
|---|---|---|---|---|
token | string | 是 | 传商户KEY | token(传商户KEY)仅供测试,正式站请设置IP |
商户密钥仅保存在自己的服务端。测试 token 与正式 IP 授权的适用范围以本表及账户授权说明为准。
请求参数
Query 查询参数
| 字段 | 类型 | 必填 | 文档示例值 | 说明 |
|---|---|---|---|---|
matchId | int32 | 是 | 0 | 比赛ID |
示例值用于说明字段;比赛、球队、联赛等 ID 应从实际接口取得,不能直接使用占位值。字段中的日期、枚举、分页范围与更新建议完整保留原始说明。
调用示例
替换 YOUR_MERCHANT_KEY、YOUR_MATCH_ID 等占位值后,在已授权的服务端调用。示例不会在本页面发起真实请求。
cURL
curl --get 'https://api.superscore.cn/football/database/match' \
--header 'token: YOUR_MERCHANT_KEY' \
--data-urlencode 'matchId=YOUR_MATCH_ID'JavaScript / Node.js
// 仅在服务端保存商户密钥;替换示例占位值。
const url = new URL("https://api.superscore.cn/football/database/match");
url.search = new URLSearchParams({
"matchId": "YOUR_MATCH_ID"
});
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 = {
"matchId": "YOUR_MATCH_ID"
}
headers = {
"token": "YOUR_MERCHANT_KEY"
}
url = "https://api.superscore.cn/football/database/match"
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 | object | 数据 |
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 | 湿度 |
data.events | array | 事件列表 |
data.events[].matchId | int32 | 比赛ID |
data.events[].eventId | int32 | 事件ID |
data.events[].type | int32 | 事件类型 |
data.events[].minute | int32 | 事件分钟数 |
data.events[].extraMinute | int32 | 加时 |
data.events[].teamType | int32 | 队伍类型 1主队 2客队 |
data.events[].playerId | int32 | 球员ID |
data.events[].playerName | string | 球员名称 |
data.events[].playerImage | string | 球员图片 |
data.events[].relatedPlayerId | int32 | 关联球员ID(助攻、换人等) |
data.events[].relatedPlayerName | string | 关联球员名称 |
data.events[].relatedPlayerImage | string | 关联球员图片 |
data.events[].reason | string | 原因(如红牌原因) |
data.events[].description | string | 事件描述 |
data.textLive | array | 文字直播 |
data.textLive[].id | int32 | ID |
data.textLive[].matchId | int32 | 比赛ID |
data.textLive[].time | int32 | 时间 |
data.textLive[].minute | int32 | 分钟数 |
data.textLive[].content | string | 内容 |
data.textLive[].type | int32 | 类型 |
data.textLive[].teamType | int32 | 队伍类型 1主队 2客队 |
data.coach | object | 场馆 |
data.coach.coachId | int32 | 教练ID |
data.coach.nameEn | string | 教练名称(英文) |
data.coach.nameShortEn | string | 教练短名称(英文) |
data.coach.nameZh | string | 教练名称(中文) |
data.coach.nameShortZh | string | 教练短名称(中文) |
data.coach.nameZht | string | 教练名称(繁体中文) |
data.coach.nameShortZht | string | 教练短名称(繁体中文) |
data.coach.firstName | string | 名 |
data.coach.lastName | string | 姓 |
data.coach.teamId | int32 | 球队ID |
data.coach.countryId | string | 国家ID |
data.coach.age | string | 年龄 |
data.coach.birthDate | string | 生日 |
data.coach.birthCountryId | string | 出生国家 |
data.coach.birthPlace | string | 出生地 |
data.coach.height | string | 身高 |
data.coach.weight | string | 体重 |
data.coach.image | string | 教练图片 |
data.venue | object | 场馆 |
data.venue.venueId | int32 | 场馆ID |
data.venue.nameEn | string | 场馆名称(英文) |
data.venue.nameZh | string | 场馆名称(中文) |
data.venue.nameZht | string | 场馆名称(繁体中文) |
data.venue.image | string | 场馆图片 |
data.venue.countryId | int32 | 国家ID |
data.venue.country | object | 国家数据 |
data.venue.country.countryId | int32 | 国家ID |
data.venue.country.nameEn | string | 国家名称(英文) |
data.venue.country.nameZh | string | 国家名称(中文) |
data.venue.country.nameZht | string | 国家名称(繁体中文) |
data.venue.country.classify | int32 | 运动类型:1足球,2篮球,3电竞,4网球,5排球,6棒球,7板球,8手球,9橄榄球,10曲棍球,11赛车,12赛马,13拳击 |
data.venue.country.type | int32 | 赛事类型:1国际赛事、2欧洲赛事、3美洲赛事、4亚洲赛事、5大洋洲赛事、6非洲赛事 |
data.venue.country.code | string | 编号 |
data.venue.country.sort | int32 | 排序 |
data.venue.country.image | string | 图片 |
data.venue.city | string | 城市 |
data.venue.capacity | int32 | 容量 |
data.venue.builtYear | int32 | 建立年份 |
data.venue.surface | string | 地面 |
data.venue.address | string | 地址 |
data.venue.location | string | 定位 |
data.venue.build | string | 建造年份 |
data.venue.status | string | 近况 |
data.venue.introduction | string | 场馆介绍 |
data.referee | object | 裁判 |
data.referee.refereeId | int32 | 裁判ID |
data.referee.nameEn | string | 裁判名称(英文) |
data.referee.nameZh | string | 裁判名称(中文) |
data.referee.nameZht | string | 裁判名称(繁体中文) |
data.referee.image | string | 裁判图片 |
data.referee.countryId | int32 | 国家ID |
data.referee.country | object | 国家数据 |
data.referee.country.countryId | int32 | 国家ID |
data.referee.country.nameEn | string | 国家名称(英文) |
data.referee.country.nameZh | string | 国家名称(中文) |
data.referee.country.nameZht | string | 国家名称(繁体中文) |
data.referee.country.classify | int32 | 运动类型:1足球,2篮球,3电竞,4网球,5排球,6棒球,7板球,8手球,9橄榄球,10曲棍球,11赛车,12赛马,13拳击 |
data.referee.country.type | int32 | 赛事类型:1国际赛事、2欧洲赛事、3美洲赛事、4亚洲赛事、5大洋洲赛事、6非洲赛事 |
data.referee.country.code | string | 编号 |
data.referee.country.sort | int32 | 排序 |
data.referee.country.image | string | 图片 |
data.referee.age | int32 | 年龄 |
data.referee.birthday | 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": "示例字符串"
},
"events": [
{
"matchId": 0,
"eventId": 0,
"type": 0,
"minute": 0,
"extraMinute": 0,
"teamType": 0,
"playerId": 0,
"playerName": "示例字符串",
"playerImage": "示例字符串",
"relatedPlayerId": 0,
"relatedPlayerName": "示例字符串",
"relatedPlayerImage": "示例字符串",
"reason": "示例字符串",
"description": "示例字符串"
}
],
"textLive": [
{
"id": 0,
"matchId": 0,
"time": 0,
"minute": 0,
"content": "示例字符串",
"type": 0,
"teamType": 0
}
],
"coach": {
"coachId": 0,
"nameEn": "示例字符串",
"nameShortEn": "示例字符串",
"nameZh": "示例字符串",
"nameShortZh": "示例字符串",
"nameZht": "示例字符串",
"nameShortZht": "示例字符串",
"firstName": "示例字符串",
"lastName": "示例字符串",
"teamId": 0,
"countryId": "示例字符串",
"age": "示例字符串",
"birthDate": "示例字符串",
"birthCountryId": "示例字符串",
"birthPlace": "示例字符串",
"height": "示例字符串",
"weight": "示例字符串",
"image": "示例字符串"
},
"venue": {
"venueId": 0,
"nameEn": "示例字符串",
"nameZh": "示例字符串",
"nameZht": "示例字符串",
"image": "示例字符串",
"countryId": 0,
"country": {
"countryId": 0,
"nameEn": "示例字符串",
"nameZh": "示例字符串",
"nameZht": "示例字符串",
"classify": 0,
"type": 0,
"code": "示例字符串",
"sort": 0,
"image": "示例字符串"
},
"city": "示例字符串",
"capacity": 0,
"builtYear": 0,
"surface": "示例字符串",
"address": "示例字符串",
"location": "示例字符串",
"build": "示例字符串",
"status": "示例字符串",
"introduction": "示例字符串"
},
"referee": {
"refereeId": 0,
"nameEn": "示例字符串",
"nameZh": "示例字符串",
"nameZht": "示例字符串",
"image": "示例字符串",
"countryId": 0,
"country": {
"countryId": 0,
"nameEn": "示例字符串",
"nameZh": "示例字符串",
"nameZht": "示例字符串",
"classify": 0,
"type": 0,
"code": "示例字符串",
"sort": 0,
"image": "示例字符串"
},
"age": 0,
"birthday": "示例字符串"
}
}
}错误处理与使用说明
- 先检查 HTTP 状态,再解析 JSON;网络失败或非 JSON 响应不能当作成功。
- 业务响应 success 为 false 时,读取 code 和 message;不要把业务错误与 HTTP 状态混为一谈。
- 保存原始错误码、请求时间及接口路径用于排查,日志中移除商户密钥。
- 按该接口的数据更新建议、账户授权和调用频率请求;日期和时间戳单位以字段说明为准。
- 允许字段缺失或数据为空,按接口中的稳定 ID 关联资料,不依赖数组顺序。