MK体育科技接口分类与开发文档目录
提供足球、篮球、网球及电竞等全球职业赛事实时比分、全量事件流、动画推演与历史大数据接口。全网节点平均耗时低于 35ms，提供稳定双向心跳保障与标准化 JSON 序列化返回。
核心数据接口端点速览
支持按 URI、方法及返回数据结构标准即插即用调用
获取全球范围内正在进行的足球比赛实时比分、当前半场时间、伤停补时及比分变更时间戳。
- match_id (int, optional): 指定赛事唯一识别ID
- league_id (int, optional): 指定联赛ID（如五大联赛、欧冠）
- lang (string, default: "zh_CN"): 多语言返回，支持 zh_CN / en / es
{ "code": 200, "data": [{ "match_id": 982103, "home_score": 2, "away_score": 1, "status": "LIVE_2H", "match_time": "68'" }] }
全双工长连接通道，进球、红黄牌、角球、越位、点球判罚及换人事件在发生后 15ms 内瞬时推送。
{ "action": "subscribe", "channels": ["match:982103:events", "match:982103:score"] }
{ "event_type": "GOAL", "team_type": "home", "player_id": 4410, "minute": 74, "timestamp": 1713500293120 }
覆盖 NBA、CBA 及欧洲篮球联赛单节得分、全队犯规、暂停余量、命中率及球员个人效率值数据。
- match_id (int, required): 篮球赛事ID
- include_players (bool, optional): 是否包含替补席个人统计
{ "period_scores": { "q1": [28, 24], "q2": [32, 29], "q3": [20, 27] }, "possession": "away" }
提供球权归属、皮球实时落点坐标 (X, Y)、攻防状态推进及危险进攻判定，用于驱动前端 2D/3D 虚拟赛场动画还原。
基准坐标系：以球场正中心为原点 (0,0)，标准球场长轴范围 [-100, 100]，宽轴范围 [-64, 64]。每秒刷新 10 次空间插值包。
{ "ball_x": 42.15, "ball_y": -12.40, "action": "DANGEROUS_ATTACK", "zone": "final_third" }
支持网球四大满贯、ATP、WTA 及多球种长达 15 个赛季的历史交锋、胜负盘率、一发得分率及场地偏好深度归档。
- player1_id (int, required): 选手 1 唯一标识
- player2_id (int, required): 选手 2 唯一标识
- surface (string, optional): 场地材质 (hard, clay, grass)
{ "total_matches": 12, "player1_wins": 7, "player2_wins": 5, "avg_aces": 8.4 }
覆盖主流电竞联赛（英雄联盟、DOTA2、CS2），针对一血、大小龙争夺、推塔及经济差变动进行主动 HTTP POST 投递。
- X-Sports-Signature: HMAC-SHA256 计算出的十六进制摘要
- X-Event-Id: 单事件全局唯一 UUID 幂等校验
{ "game": "lol", "tournament_id": 401, "event": "BARON_NASHOR_KILL", "gold_diff": 3200 }
统一请求规范与签名鉴权机制
所有流经本平台的生产接口均受双向加密与时间戳校验保护，防止重放攻击并保证传输鲁棒性。开发者需在 HTTP 请求头标或 WebSocket 握手头中携带合法凭据。
标准请求头标规范 (Request Headers)
| Header 名称 | 类型 | 说明 |
|---|---|---|
| X-API-KEY | String | 开发者唯一公钥凭证 |
| X-TIMESTAMP | Long | 当前 13 位毫秒级 Unix 时间戳 |
| X-SIGNATURE | String | HMAC-SHA256 运算摘要值 |
| Accept-Encoding | String | 推荐 gzip, deflate 启用高压缩比 |
签名计算规则 (Signature Algorithm)
Signature = HexEncode(HMAC_SHA256(secret_key, HTTP_METHOD + "\n" + REQUEST_URI + "\n" + X_TIMESTAMP + "\n" + BODY_HASH))
提示：时间戳误差超过正负 300 秒的请求将被网关安全层自动阻断 (HTTP 401)。
# 步骤 1：构造带有合法签名的 HTTP 请求调用示例 curl -X GET "https://api.cqhhyym.com/v2/football/matches/live?league_id=82" \ -H "X-API-KEY: live_sec_99a8f27bc01" \ -H "X-TIMESTAMP: 1713500293000" \ -H "X-SIGNATURE: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \ -H "Content-Type: application/json" \ --compressed # 响应状态 (HTTP 200 OK): { "code": 200, "server_time": 1713500293022, "latency_ms": 22, "data": { "total": 1, "list": [ { "match_id": 982103, "home_name": "皇家马德里", "away_name": "曼彻斯特城", "home_score": 2, "away_score": 1 } ] } }
标准化数据字段字典
各运动项目通用与专有事件标识编码对照，保证字段在不同协议与端点之间严格单义对应。
| 事件代码 (Type) | 释义说明 | 附带载荷字段 (Payload Schema) |
|---|---|---|
| GOAL | 常规进球 | { player_id, assist_player_id, is_penalty } |
| YELLOW_CARD | 黄牌警告 | { player_id, minute, reason } |
| RED_CARD | 直接红牌 / 两黄变红 | { player_id, is_double_yellow: true } |
| CORNER_KICK | 角球产生 | { team_side: "home" | "away", total_count } |
| VAR_REVIEW | 视频助理裁判介入 | { status: "PENDING" | "CONFIRMED" | "CANCELLED" } |
| SUBSTITUTION | 球员换人调整 | { player_in_id, player_out_id, team_side } |
{
// 全局统一帧格式
"version": "2.4",
"event_id": "evt_98821903",
"sport_id": 1,
"match_id": 982103,
"timestamp": 1713500293120,
"period": {
"type": "SECOND_HALF",
"current_minute": 74,
"injury_time": 0
},
"scores": {
"home": 2,
"away": 1
},
"stats": {
"possession_pct": [56, 44],
"shots_on_target": [6, 4],
"corner_kicks": [5, 2]
}
}
服务层级配额与性能 SLA 指标
从本地开发调试到高并发跨国商业转播，按需匹配吞吐量与连接保障
免费沙箱版
适合技术预研、本地功能原型搭建与字段协议联调。
专业开发者版
面向中型体育门户、赛事比分客户端与量化分析团队。
企业私有定制版
面向顶级赛事转播商、商业机构及海量用户并发平台。
接口调用状态码与排错排查对照
当网关返回非 200 HTTP 响应时，系统将随响应体返回统一格式的 JSON 错误信息。请根据对应业务错误代码快速定位排查。
| HTTP Code | 错误业务码 (err_code) | 触发根因说明 | 建议排查与解决动作 |
|---|---|---|---|
| 200 OK | SUCCESS | 请求成功并返回有效业务载荷 | 正常解析 data 节点即可 |
| 401 Unauthorized | AUTH_SIGNATURE_INVALID | API Key 失效、签名算法不匹配或时间戳漂移 > 300 秒 | 核对本地 NTP 时钟同步，检查 API-Secret 与 HMAC-SHA256 拼接顺序 |
| 403 Forbidden | PERMISSION_DENIED | 调用了当前套餐未授权的联赛事件或高级动画端点 | 前往控制台确认赛事权限范围或升级至专业版配额 |
| 429 Too Many Requests | RATE_LIMIT_EXCEEDED | 超出当前 API Key 分配的 QPS 频次限额 | 客户端引入令牌桶或漏桶算法削峰，或联系客户经理扩充并发上限 |
| 500 Server Error | GATEWAY_UPSTREAM_TIMEOUT | 边缘网关回源处理超时或集群瞬时突发雪崩保护 | 利用本地缓存进行降级展示，系统将自动在 50ms 内切换备用数据链路 |
立即开通沙箱环境，开启MK体育平台实时联调
免费获取开发环境 Token，通过 Web 在线交互式终端直接发送请求、验证协议字段、观察毫秒级推送帧率。无需等待审批，即刻对接。