账户
浏览产品与网站导航

历史-赛季比赛记录

GET https://api.superscore.cn/football/database/matchSeason

接口说明

建议每天更新

请求方式
GET
请求地址
https://api.superscore.cn/football/database/matchSeason
Content-Type
application/x-www-form-urlencoded;charset=UTF-8

请求头与鉴权

字段类型必填文档示例值说明
tokenstring是传商户KEYtoken(传商户KEY)仅供测试,正式站请设置IP

商户密钥仅保存在自己的服务端。测试 token 与正式 IP 授权的适用范围以本表及账户授权说明为准。

请求参数

Query 查询参数

字段类型必填文档示例值说明
leagueIdint32是0联赛ID
seasonstring是—赛季

示例值用于说明字段;比赛、球队、联赛等 ID 应从实际接口取得,不能直接使用占位值。字段中的日期、枚举、分页范围与更新建议完整保留原始说明。

调用示例

替换 YOUR_MERCHANT_KEY、YOUR_MATCH_ID 等占位值后,在已授权的服务端调用。示例不会在本页面发起真实请求。

cURL

curl --get 'https://api.superscore.cn/football/database/matchSeason' \
  --header 'token: YOUR_MERCHANT_KEY' \
  --data-urlencode 'leagueId=YOUR_LEAGUE_ID' \
  --data-urlencode 'season=YOUR_SEASON'

JavaScript / Node.js

// 仅在服务端保存商户密钥;替换示例占位值。
const url = new URL("https://api.superscore.cn/football/database/matchSeason");
url.search = new URLSearchParams({
  "leagueId": "YOUR_LEAGUE_ID",
  "season": "YOUR_SEASON"
});
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 = {
  "leagueId": "YOUR_LEAGUE_ID",
  "season": "YOUR_SEASON"
}
headers = {
  "token": "YOUR_MERCHANT_KEY"
}
url = "https://api.superscore.cn/football/database/matchSeason"
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 均按接口定义列出。

字段路径类型说明与枚举
successboolean状态码
codestring状态编号
messagestring描述
dataarray数据
data[].matchIdint32比赛ID
data[].timeint32比赛时间(秒级时间戳)
data[].statusint32状态:0未开始,1上半场,2中场,3下半场,4加时,5点球,10完场,11取消,12暂停,13推迟,14延迟,15腰斩,16中断,17退赛,18待定,99删除
data[].leagueIdint32联赛ID
data[].seasonIdint32赛季ID
data[].stageIdint32阶段ID
data[].venueIdint32球场ID
data[].groupIdstring组
data[].refereeIdint32裁判ID
data[].homeScorestring主队比赛比分;int数组格式,返回顺序:常规时间比分,半场比分,加时赛比分(不含常规时间),点球比分(不含常规时间和加时赛比分),总分
data[].awayScorestring客队比赛比分;int数组格式,返回顺序:常规时间比分,半场比分,加时赛比分(不含常规时间),点球比分(不含常规时间和加时赛比分),总分
data[].homeIdint32主队ID
data[].awayIdint32客队ID
data[].beidanint32是否有北单:0无,1有主客一致,2有主客相反
data[].lotteryint32是否有竞彩:0无,1有主客一致,2有主客相反
data[].animationint32是否有动画
data[].streamint32是否有直播
data[].oddsint32是否有指数:0无,1有
data[].injuriesint32是否有情报:0无,1有
data[].lineupint32是否有阵容:0无,1有
data[].sortint32排序
data[].turnBasedstring回合制
data[].leagueobject联赛信息
data[].league.leagueIdint32联赛ID
data[].league.nameEnstring英文名称
data[].league.nameShortEnstring英文简称
data[].league.nameZhstring中文名称
data[].league.nameShortZhstring中文简称
data[].league.nameZhtstring繁体名称
data[].league.nameShortZhtstring繁体简称
data[].league.imagestring联赛图片
data[].league.colorstring颜色
data[].league.sortint32排序
data[].homeobject主队信息
data[].home.teamIdint32球队ID
data[].home.nameEnstring英文名称
data[].home.nameShortEnstring英文简称
data[].home.nameZhstring中文名称
data[].home.nameShortZhstring中文简称
data[].home.nameZhtstring繁体名称
data[].home.nameShortZhtstring繁体简称
data[].home.imagestring球队图片
data[].awayobject客队信息
data[].away.teamIdint32球队ID
data[].away.nameEnstring英文名称
data[].away.nameShortEnstring英文简称
data[].away.nameZhstring中文名称
data[].away.nameShortZhstring中文简称
data[].away.nameZhtstring繁体名称
data[].away.nameShortZhtstring繁体简称
data[].away.imagestring球队图片
data[].statsobject统计
data[].stats.minutestring分钟
data[].stats.secondstring秒
data[].stats.overtimestring加时
data[].stats.startTimeint64上下半场开始时间
data[].stats.homeTeamobject主队
data[].stats.homeTeam.possessionstring控球率
data[].stats.homeTeam.shotOnint32射正
data[].stats.homeTeam.shotOffint32射偏
data[].stats.homeTeam.cornerint32角球
data[].stats.homeTeam.yellowint32黄牌
data[].stats.homeTeam.redint32红牌
data[].stats.homeTeam.penaltyint32点球
data[].stats.homeTeam.attacksint32进攻
data[].stats.homeTeam.dangerousAttacksint32危险进攻
data[].stats.homeTeam.assistsint32助攻
data[].stats.homeTeam.headersint32头球
data[].stats.homeTeam.turnoversint32丟球
data[].stats.homeTeam.savesint32救球
data[].stats.homeTeam.ownGoalsint32乌龙
data[].stats.homeTeam.throwInint32界外球
data[].stats.homeTeam.goalKickint32球门球
data[].stats.homeTeam.tacklesint32成功抢断
data[].stats.homeTeam.blocksint32阻截
data[].stats.homeTeam.longPassesint32长传
data[].stats.homeTeam.shortPassesint32短传
data[].stats.homeTeam.crossesint32成功传中
data[].stats.homeTeam.foulsint32犯规
data[].stats.homeTeam.offsideint32越位
data[].stats.homeTeam.goalkeeperSavesint32守门员出击
data[].stats.awayTeamobject客队
data[].stats.awayTeam.possessionstring控球率
data[].stats.awayTeam.shotOnint32射正
data[].stats.awayTeam.shotOffint32射偏
data[].stats.awayTeam.cornerint32角球
data[].stats.awayTeam.yellowint32黄牌
data[].stats.awayTeam.redint32红牌
data[].stats.awayTeam.penaltyint32点球
data[].stats.awayTeam.attacksint32进攻
data[].stats.awayTeam.dangerousAttacksint32危险进攻
data[].stats.awayTeam.assistsint32助攻
data[].stats.awayTeam.headersint32头球
data[].stats.awayTeam.turnoversint32丟球
data[].stats.awayTeam.savesint32救球
data[].stats.awayTeam.ownGoalsint32乌龙
data[].stats.awayTeam.throwInint32界外球
data[].stats.awayTeam.goalKickint32球门球
data[].stats.awayTeam.tacklesint32成功抢断
data[].stats.awayTeam.blocksint32阻截
data[].stats.awayTeam.longPassesint32长传
data[].stats.awayTeam.shortPassesint32短传
data[].stats.awayTeam.crossesint32成功传中
data[].stats.awayTeam.foulsint32犯规
data[].stats.awayTeam.offsideint32越位
data[].stats.awayTeam.goalkeeperSavesint32守门员出击
data[].stats.updateTimeint64更新时间
data[].stats.matchIdint32比赛ID
data[].stats.statusint32比赛状态
data[].stats.animationIdint32动画ID
data[].stats.homePlayerarray主队球员统计
data[].stats.homePlayer[].playerIdint32球员ID
data[].stats.homePlayer[].nameEnstring球员名称(英文)
data[].stats.homePlayer[].nameZhstring球员名称(中文)
data[].stats.homePlayer[].imagestring球员图片
data[].stats.homePlayer[].numberstring号码
data[].stats.homePlayer[].positionint32位置:1守门员,2后卫,3中场,4前锋
data[].stats.homePlayer[].goalsint32进球
data[].stats.homePlayer[].assistsint32助攻
data[].stats.homePlayer[].shotsint32射门
data[].stats.homePlayer[].shotsOnTargetint32射正
data[].stats.homePlayer[].keyPassesint32关键传球
data[].stats.homePlayer[].passesint32传球
data[].stats.homePlayer[].passesSuccessfulint32传球成功
data[].stats.homePlayer[].tacklesint32抢断
data[].stats.homePlayer[].interceptionsint32拦截
data[].stats.homePlayer[].clearancesint32解围
data[].stats.homePlayer[].foulsint32犯规
data[].stats.homePlayer[].foulsDrawnint32被犯规
data[].stats.homePlayer[].yellowCardsint32黄牌
data[].stats.homePlayer[].redCardsint32红牌
data[].stats.homePlayer[].ratingstring评分
data[].stats.awayPlayerarray客队球员统计
data[].stats.awayPlayer[].playerIdint32球员ID
data[].stats.awayPlayer[].nameEnstring球员名称(英文)
data[].stats.awayPlayer[].nameZhstring球员名称(中文)
data[].stats.awayPlayer[].imagestring球员图片
data[].stats.awayPlayer[].numberstring号码
data[].stats.awayPlayer[].positionint32位置:1守门员,2后卫,3中场,4前锋
data[].stats.awayPlayer[].goalsint32进球
data[].stats.awayPlayer[].assistsint32助攻
data[].stats.awayPlayer[].shotsint32射门
data[].stats.awayPlayer[].shotsOnTargetint32射正
data[].stats.awayPlayer[].keyPassesint32关键传球
data[].stats.awayPlayer[].passesint32传球
data[].stats.awayPlayer[].passesSuccessfulint32传球成功
data[].stats.awayPlayer[].tacklesint32抢断
data[].stats.awayPlayer[].interceptionsint32拦截
data[].stats.awayPlayer[].clearancesint32解围
data[].stats.awayPlayer[].foulsint32犯规
data[].stats.awayPlayer[].foulsDrawnint32被犯规
data[].stats.awayPlayer[].yellowCardsint32黄牌
data[].stats.awayPlayer[].redCardsint32红牌
data[].stats.awayPlayer[].ratingstring评分
data[].Weatherobject天气
data[].Weather.weatherstring天气
data[].Weather.temperaturestring温度
data[].Weather.windSpeedstring风速
data[].Weather.humiditystring湿度

响应结构示例

下面的值仅展示字段类型,不是实时数据或真实调用结果。动态 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": "示例字符串"
      }
    }
  ]
}

错误处理与使用说明

  1. 先检查 HTTP 状态,再解析 JSON;网络失败或非 JSON 响应不能当作成功。
  2. 业务响应 success 为 false 时,读取 code 和 message;不要把业务错误与 HTTP 状态混为一谈。
  3. 保存原始错误码、请求时间及接口路径用于排查,日志中移除商户密钥。
  4. 按该接口的数据更新建议、账户授权和调用频率请求;日期和时间戳单位以字段说明为准。
  5. 允许字段缺失或数据为空,按接口中的稳定 ID 关联资料,不依赖数组顺序。