篮球 API 比赛-赛程赛果接口文档

接口说明

建议每天更新

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

请求头与鉴权

字段	类型	必填	文档示例值	说明
`token`	string	是	`test`	token仅供测试，正式站请设置IP

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

请求参数

Query 查询参数

字段	类型	必填	文档示例值	说明
`languageId`	string	否	`zh`	多语言默认zh
`date`	string	是	`2023-08-01`	日期2023-06-01

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

调用示例

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

cURL

curl --get 'https://api.superscore.cn/basketball/change/matchList' \
  --header 'token: YOUR_MERCHANT_KEY' \
  --data-urlencode 'languageId=YOUR_LANGUAGE_ID' \
  --data-urlencode 'date=YYYY-MM-DD'

JavaScript / Node.js

// 仅在服务端保存商户密钥；替换示例占位值。
const url = new URL("https://api.superscore.cn/basketball/change/matchList");
url.search = new URLSearchParams({
  "languageId": "YOUR_LANGUAGE_ID",
  "date": "YYYY-MM-DD"
});
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 = {
  "languageId": "YOUR_LANGUAGE_ID",
  "date": "YYYY-MM-DD"
}
headers = {
  "token": "YOUR_MERCHANT_KEY"
}
url = "https://api.superscore.cn/basketball/change/matchList"
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	是否成功
`message`	string	提示信息
`data`	array	数据
`data[].matchId`	int32	比赛
`data[].leagueId`	int32	联赛
`data[].seasonId`	int32	赛季
`data[].stageId`	int32	分组
`data[].homeId`	int32	主队
`data[].awayId`	int32	客队
`data[].homeScore`	string	主队比分第一节,第二节,第三节,第四节,加时,总共
`data[].time`	int32	比赛时间
`data[].status`	int32	状态0未开始,1第一节,2第二节,3中场,4第三节,5第四节,6加时,7休息,10完成,11取消,12暂停,13推迟,14延迟,15腰斩,16中断,17退赛,18待定,99删除
`data[].venueId`	int32	球场
`data[].awayScore`	string	客队队比分第一节,第二节,第三节,第四节,加时,总共
`data[].lottery`	int32	是否有竞彩,0无,1有主客一直,2有主客相反
`data[].stream`	int32	是否有直播,0无,1有
`data[].odds`	int32	是否有指数,0无,1有
`data[].inplay`	int32	是否有滚球,0无,1有
`data[].animation`	int32	是否有动画,0无,1有
`data[].sort`	int32	竞彩排序
`data[].league`	object	联赛信息
`data[].league.id`	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	image
`data[].league.sort`	int32	排序
`data[].home`	object	主队信息
`data[].home.id`	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	image
`data[].home.sort`	int32	排序
`data[].away`	object	客队信息
`data[].away.id`	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	image
`data[].away.sort`	int32	排序
`data[].stats`	object	比赛统计
`data[].stats.minute`	string	分钟
`data[].stats.second`	string	秒
`data[].stats.updateTime`	int64	更新时间
`data[].stats.homeTeam`	object	主队
`data[].stats.homeTeam.s1`	string	第一节得分
`data[].stats.homeTeam.s2`	string	第二节得分
`data[].stats.homeTeam.s3`	string	第三节得分
`data[].stats.homeTeam.s4`	string	第四节得分
`data[].stats.homeTeam.half`	string	半场得分
`data[].stats.homeTeam.ot`	string	加时得分
`data[].stats.homeTeam.t`	string	总得分
`data[].stats.awayTeam`	object	客队
`data[].stats.awayTeam.s1`	string	第一节得分
`data[].stats.awayTeam.s2`	string	第二节得分
`data[].stats.awayTeam.s3`	string	第三节得分
`data[].stats.awayTeam.s4`	string	第四节得分
`data[].stats.awayTeam.half`	string	半场得分
`data[].stats.awayTeam.ot`	string	加时得分
`data[].stats.awayTeam.t`	string	总得分
`data[].teamStats`	object	球队统计
`data[].teamStats.away`	object	客队
`data[].teamStats.away.assists`	string	助攻
`data[].teamStats.away.blocks`	string	蓋帽
`data[].teamStats.away.fieldGoalsMade`	object	投篮命中率
`data[].teamStats.away.fieldGoalsMade.attempts`	string	No comments found.
`data[].teamStats.away.fieldGoalsMade.pct`	string	No comments found.
`data[].teamStats.away.fieldGoalsMade.total`	string	No comments found.
`data[].teamStats.away.freeThrowsGoalsMade`	object	罚球命中率
`data[].teamStats.away.freeThrowsGoalsMade.attempts`	string	No comments found.
`data[].teamStats.away.freeThrowsGoalsMade.pct`	string	No comments found.
`data[].teamStats.away.freeThrowsGoalsMade.total`	string	No comments found.
`data[].teamStats.away.personalFouls`	string	个人犯规
`data[].teamStats.away.rebounds`	object	篮板球
`data[].teamStats.away.rebounds.defense`	string	No comments found.
`data[].teamStats.away.rebounds.offence`	string	No comments found.
`data[].teamStats.away.rebounds.total`	string	No comments found.
`data[].teamStats.away.steals`	string	抢断
`data[].teamStats.away.threePointGoalsMade`	object	三分球命中率
`data[].teamStats.away.threePointGoalsMade.attempts`	string	No comments found.
`data[].teamStats.away.threePointGoalsMade.pct`	string	No comments found.
`data[].teamStats.away.threePointGoalsMade.total`	string	No comments found.
`data[].teamStats.away.turnovers`	string	失误
`data[].teamStats.home`	object	主队
`data[].teamStats.home.assists`	string	助攻
`data[].teamStats.home.blocks`	string	蓋帽
`data[].teamStats.home.fieldGoalsMade`	object	投篮命中率
`data[].teamStats.home.fieldGoalsMade.attempts`	string	No comments found.
`data[].teamStats.home.fieldGoalsMade.pct`	string	No comments found.
`data[].teamStats.home.fieldGoalsMade.total`	string	No comments found.
`data[].teamStats.home.freeThrowsGoalsMade`	object	罚球命中率
`data[].teamStats.home.freeThrowsGoalsMade.attempts`	string	No comments found.
`data[].teamStats.home.freeThrowsGoalsMade.pct`	string	No comments found.
`data[].teamStats.home.freeThrowsGoalsMade.total`	string	No comments found.
`data[].teamStats.home.personalFouls`	string	个人犯规
`data[].teamStats.home.rebounds`	object	篮板球
`data[].teamStats.home.rebounds.defense`	string	No comments found.
`data[].teamStats.home.rebounds.offence`	string	No comments found.
`data[].teamStats.home.rebounds.total`	string	No comments found.
`data[].teamStats.home.steals`	string	抢断
`data[].teamStats.home.threePointGoalsMade`	object	三分球命中率
`data[].teamStats.home.threePointGoalsMade.attempts`	string	No comments found.
`data[].teamStats.home.threePointGoalsMade.pct`	string	No comments found.
`data[].teamStats.home.threePointGoalsMade.total`	string	No comments found.
`data[].teamStats.home.turnovers`	string	失误
`data[].playerStats`	object	球员统计
`data[].playerStats.away`	object	客队
`data[].playerStats.away.bench`	array	替补
`data[].playerStats.away.bench[].assists`	string	助攻
`data[].playerStats.away.bench[].blocks`	string	盖帽
`data[].playerStats.away.bench[].defenseRebounds`	string	防守篮板
`data[].playerStats.away.bench[].fieldGoalsAttempts`	string	射门次数
`data[].playerStats.away.bench[].fieldGoalsMade`	string	投篮命中率
`data[].playerStats.away.bench[].freeThrowsGoalsAttempts`	string	罚球次数
`data[].playerStats.away.bench[].freeThrowsGoalsMade`	string	罚球命中率
`data[].playerStats.away.bench[].id`	string	球员id
`data[].playerStats.away.bench[].minutes`	string	上场时间
`data[].playerStats.away.bench[].name`	string
`data[].playerStats.away.bench[].offenceRebounds`	string	进攻篮板
`data[].playerStats.away.bench[].onCourt`	boolean	是否在球场上
`data[].playerStats.away.bench[].personalFouls`	string	个人犯规
`data[].playerStats.away.bench[].plusMinus`	string	正负值
`data[].playerStats.away.bench[].points`	string	得分
`data[].playerStats.away.bench[].pos`	int32	位置
`data[].playerStats.away.bench[].steals`	string	抢断
`data[].playerStats.away.bench[].threePointGoalsAttempts`	string	三分进球次数
`data[].playerStats.away.bench[].threePointGoalsMade`	string	三分球命中率
`data[].playerStats.away.bench[].totalRebounds`	string	总篮板数
`data[].playerStats.away.bench[].turnovers`	string	失误
`data[].playerStats.away.starters`	array	首发
`data[].playerStats.away.starters[].assists`	string	助攻
`data[].playerStats.away.starters[].blocks`	string	盖帽
`data[].playerStats.away.starters[].defenseRebounds`	string	防守篮板
`data[].playerStats.away.starters[].fieldGoalsAttempts`	string	射门次数
`data[].playerStats.away.starters[].fieldGoalsMade`	string	投篮命中率
`data[].playerStats.away.starters[].freeThrowsGoalsAttempts`	string	罚球次数
`data[].playerStats.away.starters[].freeThrowsGoalsMade`	string	罚球命中率
`data[].playerStats.away.starters[].id`	string	球员id
`data[].playerStats.away.starters[].minutes`	string	上场时间
`data[].playerStats.away.starters[].name`	string
`data[].playerStats.away.starters[].offenceRebounds`	string	进攻篮板
`data[].playerStats.away.starters[].onCourt`	boolean	是否在球场上
`data[].playerStats.away.starters[].personalFouls`	string	个人犯规
`data[].playerStats.away.starters[].plusMinus`	string	正负值
`data[].playerStats.away.starters[].points`	string	得分
`data[].playerStats.away.starters[].pos`	int32	位置
`data[].playerStats.away.starters[].steals`	string	抢断
`data[].playerStats.away.starters[].threePointGoalsAttempts`	string	三分进球次数
`data[].playerStats.away.starters[].threePointGoalsMade`	string	三分球命中率
`data[].playerStats.away.starters[].totalRebounds`	string	总篮板数
`data[].playerStats.away.starters[].turnovers`	string	失误
`data[].playerStats.home`	object	主队
`data[].playerStats.home.bench`	array	替补
`data[].playerStats.home.bench[].assists`	string	助攻
`data[].playerStats.home.bench[].blocks`	string	盖帽
`data[].playerStats.home.bench[].defenseRebounds`	string	防守篮板
`data[].playerStats.home.bench[].fieldGoalsAttempts`	string	射门次数
`data[].playerStats.home.bench[].fieldGoalsMade`	string	投篮命中率
`data[].playerStats.home.bench[].freeThrowsGoalsAttempts`	string	罚球次数
`data[].playerStats.home.bench[].freeThrowsGoalsMade`	string	罚球命中率
`data[].playerStats.home.bench[].id`	string	球员id
`data[].playerStats.home.bench[].minutes`	string	上场时间
`data[].playerStats.home.bench[].name`	string
`data[].playerStats.home.bench[].offenceRebounds`	string	进攻篮板
`data[].playerStats.home.bench[].onCourt`	boolean	是否在球场上
`data[].playerStats.home.bench[].personalFouls`	string	个人犯规
`data[].playerStats.home.bench[].plusMinus`	string	正负值
`data[].playerStats.home.bench[].points`	string	得分
`data[].playerStats.home.bench[].pos`	int32	位置
`data[].playerStats.home.bench[].steals`	string	抢断
`data[].playerStats.home.bench[].threePointGoalsAttempts`	string	三分进球次数
`data[].playerStats.home.bench[].threePointGoalsMade`	string	三分球命中率
`data[].playerStats.home.bench[].totalRebounds`	string	总篮板数
`data[].playerStats.home.bench[].turnovers`	string	失误
`data[].playerStats.home.starters`	array	首发
`data[].playerStats.home.starters[].assists`	string	助攻
`data[].playerStats.home.starters[].blocks`	string	盖帽
`data[].playerStats.home.starters[].defenseRebounds`	string	防守篮板
`data[].playerStats.home.starters[].fieldGoalsAttempts`	string	射门次数
`data[].playerStats.home.starters[].fieldGoalsMade`	string	投篮命中率
`data[].playerStats.home.starters[].freeThrowsGoalsAttempts`	string	罚球次数
`data[].playerStats.home.starters[].freeThrowsGoalsMade`	string	罚球命中率
`data[].playerStats.home.starters[].id`	string	球员id
`data[].playerStats.home.starters[].minutes`	string	上场时间
`data[].playerStats.home.starters[].name`	string
`data[].playerStats.home.starters[].offenceRebounds`	string	进攻篮板
`data[].playerStats.home.starters[].onCourt`	boolean	是否在球场上
`data[].playerStats.home.starters[].personalFouls`	string	个人犯规
`data[].playerStats.home.starters[].plusMinus`	string	正负值
`data[].playerStats.home.starters[].points`	string	得分
`data[].playerStats.home.starters[].pos`	int32	位置
`data[].playerStats.home.starters[].steals`	string	抢断
`data[].playerStats.home.starters[].threePointGoalsAttempts`	string	三分进球次数
`data[].playerStats.home.starters[].threePointGoalsMade`	string	三分球命中率
`data[].playerStats.home.starters[].totalRebounds`	string	总篮板数
`data[].playerStats.home.starters[].turnovers`	string	失误
`code`	string	编码
`timestamp`	int64	时间

响应结构示例

下面的值仅展示字段类型，不是实时数据或真实调用结果。动态 map 的键取决于实际返回，不编造固定字段。

展开完整 JSON 结构

{
  "success": false,
  "message": "示例字符串",
  "data": [
    {
      "matchId": 0,
      "leagueId": 0,
      "seasonId": 0,
      "stageId": 0,
      "homeId": 0,
      "awayId": 0,
      "homeScore": "示例字符串",
      "time": 0,
      "status": 0,
      "venueId": 0,
      "awayScore": "示例字符串",
      "lottery": 0,
      "stream": 0,
      "odds": 0,
      "inplay": 0,
      "animation": 0,
      "sort": 0,
      "league": {
        "id": 0,
        "nameEn": "示例字符串",
        "nameShortEn": "示例字符串",
        "nameZh": "示例字符串",
        "nameShortZh": "示例字符串",
        "nameZht": "示例字符串",
        "nameShortZht": "示例字符串",
        "image": "示例字符串",
        "sort": 0
      },
      "home": {
        "id": 0,
        "nameEn": "示例字符串",
        "nameShortEn": "示例字符串",
        "nameZh": "示例字符串",
        "nameShortZh": "示例字符串",
        "nameZht": "示例字符串",
        "nameShortZht": "示例字符串",
        "image": "示例字符串",
        "sort": 0
      },
      "away": {
        "id": 0,
        "nameEn": "示例字符串",
        "nameShortEn": "示例字符串",
        "nameZh": "示例字符串",
        "nameShortZh": "示例字符串",
        "nameZht": "示例字符串",
        "nameShortZht": "示例字符串",
        "image": "示例字符串",
        "sort": 0
      },
      "stats": {
        "minute": "示例字符串",
        "second": "示例字符串",
        "updateTime": 0,
        "homeTeam": {
          "s1": "示例字符串",
          "s2": "示例字符串",
          "s3": "示例字符串",
          "s4": "示例字符串",
          "half": "示例字符串",
          "ot": "示例字符串",
          "t": "示例字符串"
        },
        "awayTeam": {
          "s1": "示例字符串",
          "s2": "示例字符串",
          "s3": "示例字符串",
          "s4": "示例字符串",
          "half": "示例字符串",
          "ot": "示例字符串",
          "t": "示例字符串"
        }
      },
      "teamStats": {
        "away": {
          "assists": "示例字符串",
          "blocks": "示例字符串",
          "fieldGoalsMade": {
            "attempts": "示例字符串",
            "pct": "示例字符串",
            "total": "示例字符串"
          },
          "freeThrowsGoalsMade": {
            "attempts": "示例字符串",
            "pct": "示例字符串",
            "total": "示例字符串"
          },
          "personalFouls": "示例字符串",
          "rebounds": {
            "defense": "示例字符串",
            "offence": "示例字符串",
            "total": "示例字符串"
          },
          "steals": "示例字符串",
          "threePointGoalsMade": {
            "attempts": "示例字符串",
            "pct": "示例字符串",
            "total": "示例字符串"
          },
          "turnovers": "示例字符串"
        },
        "home": {
          "assists": "示例字符串",
          "blocks": "示例字符串",
          "fieldGoalsMade": {
            "attempts": "示例字符串",
            "pct": "示例字符串",
            "total": "示例字符串"
          },
          "freeThrowsGoalsMade": {
            "attempts": "示例字符串",
            "pct": "示例字符串",
            "total": "示例字符串"
          },
          "personalFouls": "示例字符串",
          "rebounds": {
            "defense": "示例字符串",
            "offence": "示例字符串",
            "total": "示例字符串"
          },
          "steals": "示例字符串",
          "threePointGoalsMade": {
            "attempts": "示例字符串",
            "pct": "示例字符串",
            "total": "示例字符串"
          },
          "turnovers": "示例字符串"
        }
      },
      "playerStats": {
        "away": {
          "bench": [
            {
              "assists": "示例字符串",
              "blocks": "示例字符串",
              "defenseRebounds": "示例字符串",
              "fieldGoalsAttempts": "示例字符串",
              "fieldGoalsMade": "示例字符串",
              "freeThrowsGoalsAttempts": "示例字符串",
              "freeThrowsGoalsMade": "示例字符串",
              "id": "示例字符串",
              "minutes": "示例字符串",
              "name": "示例字符串",
              "offenceRebounds": "示例字符串",
              "onCourt": false,
              "personalFouls": "示例字符串",
              "plusMinus": "示例字符串",
              "points": "示例字符串",
              "pos": 0,
              "steals": "示例字符串",
              "threePointGoalsAttempts": "示例字符串",
              "threePointGoalsMade": "示例字符串",
              "totalRebounds": "示例字符串",
              "turnovers": "示例字符串"
            }
          ],
          "starters": [
            {
              "assists": "示例字符串",
              "blocks": "示例字符串",
              "defenseRebounds": "示例字符串",
              "fieldGoalsAttempts": "示例字符串",
              "fieldGoalsMade": "示例字符串",
              "freeThrowsGoalsAttempts": "示例字符串",
              "freeThrowsGoalsMade": "示例字符串",
              "id": "示例字符串",
              "minutes": "示例字符串",
              "name": "示例字符串",
              "offenceRebounds": "示例字符串",
              "onCourt": false,
              "personalFouls": "示例字符串",
              "plusMinus": "示例字符串",
              "points": "示例字符串",
              "pos": 0,
              "steals": "示例字符串",
              "threePointGoalsAttempts": "示例字符串",
              "threePointGoalsMade": "示例字符串",
              "totalRebounds": "示例字符串",
              "turnovers": "示例字符串"
            }
          ]
        },
        "home": {
          "bench": [
            {
              "assists": "示例字符串",
              "blocks": "示例字符串",
              "defenseRebounds": "示例字符串",
              "fieldGoalsAttempts": "示例字符串",
              "fieldGoalsMade": "示例字符串",
              "freeThrowsGoalsAttempts": "示例字符串",
              "freeThrowsGoalsMade": "示例字符串",
              "id": "示例字符串",
              "minutes": "示例字符串",
              "name": "示例字符串",
              "offenceRebounds": "示例字符串",
              "onCourt": false,
              "personalFouls": "示例字符串",
              "plusMinus": "示例字符串",
              "points": "示例字符串",
              "pos": 0,
              "steals": "示例字符串",
              "threePointGoalsAttempts": "示例字符串",
              "threePointGoalsMade": "示例字符串",
              "totalRebounds": "示例字符串",
              "turnovers": "示例字符串"
            }
          ],
          "starters": [
            {
              "assists": "示例字符串",
              "blocks": "示例字符串",
              "defenseRebounds": "示例字符串",
              "fieldGoalsAttempts": "示例字符串",
              "fieldGoalsMade": "示例字符串",
              "freeThrowsGoalsAttempts": "示例字符串",
              "freeThrowsGoalsMade": "示例字符串",
              "id": "示例字符串",
              "minutes": "示例字符串",
              "name": "示例字符串",
              "offenceRebounds": "示例字符串",
              "onCourt": false,
              "personalFouls": "示例字符串",
              "plusMinus": "示例字符串",
              "points": "示例字符串",
              "pos": 0,
              "steals": "示例字符串",
              "threePointGoalsAttempts": "示例字符串",
              "threePointGoalsMade": "示例字符串",
              "totalRebounds": "示例字符串",
              "turnovers": "示例字符串"
            }
          ]
        }
      }
    }
  ],
  "code": "示例字符串",
  "timestamp": 0
}

错误处理与使用说明

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