AnySport 足球数据接口全新升级

发布日期： 2026-07-27
AnySport

这次我们对 AnySport 足球数据 API 做了一轮大版本升级，升级后我们能提供的数据更多，实时推送的数据也更全了。

数据规模：赔率盘口现在升级成一套标准化 market_code 字典（赛前 63 种、滚球 499 种），同时新增了赛季、教练、伤停、单场详情、实时赛况、比赛事件、近期赛程窗口等一批端点。
实时推送：旧版的WebSocket只能提供实时比分数据，这次升级后，可通过WebSocket订阅比分、赛况、赛前赔率、滚球赔率。

同时，这一版换了基础地址、换了认证方式、换了 ID 体系,所以旧版 (v1) 用户需要按下面的迁移说明升级代码，不是无痛平滑的。我们把该讲的坑都写在这篇里了。

📌 文档也换新了：新版是 docs.anysport.io,旧版 v1 归档在 docsv1.anysport.io。下文所有端点、字段、code 均以新版为准。

一、本次升级一览

先用一张表看全貌（🔴 = 对旧版用户属于破坏性变更，需要改代码）：

维度	旧版 v1	新版
REST 基础地址	`https://api.anysport.io/v1`	`https://data.anysport.io/v1/soccer`	🔴
认证方式	`X-API-Key` 请求头或 `?api_key=` 查询参数	仅 `apikey` 请求头(小写、无 `X-`),不支持查询参数	🔴
实体 ID	纯整数(`match_id: 1234567`、`league_id: 148`)	语义化前缀字符串(`as_` / `asl_` / `ast_` …)	🔴
赔率数据模型	人读市场名 `market_name`(“1X2”)，无完整目录	标准化 `market_code` 字典(`match_winner`)	🔴
赛前赔率盘口	少量常见市场	63 种 `market_code` 完整目录	⬆️
滚球赔率盘口	一批常见市场，无统一 code 字典	499 个 `market_code` 完整字典	⬆️
WebSocket 数据	单一 `livescore_update` 比分流	四条流:比分 / 赛况 / 赛前赔率 / 滚球赔率	⬆️🔴
WebSocket 协议	URL 挂 `league_id`/`match_id` 过滤	发送订阅 `code` + 心跳的订阅协议	🔴
响应信封	`success` / `data` / `meta`	`success` / `data` / `meta` / `traceId`	⬆️
新增端点	—	赛季、教练、伤停、单场详情、实时赛况、比赛事件、近期赛程窗口	⬆️

本轮更新的两条主线：数据的广度和 WebSocket 的实时能力。下面分开讲。

二、升级一：更大、更规整的数据覆盖

2.1 赔率：标准化 `market_code` 字典

旧版的赔率市场用一个人读字符串 market_name 表示，没有权威目录，你得靠字符串匹配去猜：

// 旧版 v1:GET https://api.anysport.io/v1/odds?match_id=1234567
{
  "data": [{
    "match_id": 1234567,
    "bookmakers": [{
      "bookmaker_name": "bet365",
      "markets": [
        { "market_name": "1X2", "odds": [ {"value":"Home","odd":1.38}, ... ] },
        { "market_name": "Over/Under", "odds": [ {"value":"Over","odd":2.0,"handicap":"2.5"}, ... ] }
      ]
    }]
  }]
}

// 旧版 v1:GET https://api.anysport.io/v1/odds?match_id=1234567
{
  "data": [{
    "match_id": 1234567,
    "bookmakers": [{
      "bookmaker_name": "bet365",
      "markets": [
        { "market_name": "1X2", "odds": [ {"value":"Home","odd":1.38}, ... ] },
        { "market_name": "Over/Under", "odds": [ {"value":"Over","odd":2.0,"handicap":"2.5"}, ... ] }
      ]
    }]
  }]
}

新版把盘口彻底标准化成一套 market_code 枚举字典，并给出完整目录，可枚举、可对照、可做映射表：

赛前赔率 GET /odds/prematch：63 种 market_code 从 match_winner(全场胜平负)、asian_handicap(亚盘)、goals_over_under(大小球),到 double_chance、ht_ft_double、odd_even 等等，常规赛前分析页要用的盘口基本铺齐。
滚球赔率 GET /odds/live:499 个 market_code 完整字典，欧式三向让球、亚盘(含上/下半场)、大小球、全场/半场角球、下一个进球、剩余时间盘等等,单场进行中通常有数十个活跃盘口同时跳动。

对旧版用户来说，这意味着你原来那套按 market_name 字符串匹配的解析逻辑要改成按 market_code 路由(见第四节迁移)。

⚠️ market_code 是开放枚举,还会继续扩充。 我们后续会持续加入新玩法，客户端请对未知 market_code 做降级处理而不是抛错，遇到不认识的 code 跳过或原样透传即可，这样解析层不会因为我们上新盘口而崩掉。

几个赔率老坑这次仍然成立，一并提醒：

⚠️ 赛前和滚球是两条独立数据流,选项标签体系不一样。 同样是主胜/平/客胜,赛前用 Home/Draw/Away,滚球用 1/X/2，想用一套代码同时解析两条流，必须先做映射。让分值 handicap 的位置也不同(赛前嵌在 option 名里，滚球在 markets[].handicap 独立字段)，终场后滚球 markets 可能收缩成空数组 []。

2.2 新增了一批端点

除了赔率,这一版还补齐了不少数据端点：

赛季列表
教练列表
伤停名单
单场详情
实时赛况
近期赛程窗口

配合原有的赛程、比分、阵容、积分榜、射手榜、交锋历史，一条完整的足球数据链路基本齐了。

三、升级二：WebSocket 扩大至四条可订阅数据流

这是本次升级里我们自己最兴奋的部分，变化也最大。

旧版的 WebSocket 只有一条数据流。 你连上 wss://api.anysport.io/v1/ws/live?api_key=KEY&league_id=148，服务端就不断推 livescore_update。它能做比分牌，但拿不到赔率，也没有独立的技术统计流，过滤只能靠 URL 上的 league_id/match_id 参数:

// 旧版 v1:只有这一种推送
{ "type": "livescore_update", "data": [ { "match_id": 1234567, "score": "2-1", "minute": 67, ... } ] }

// 旧版 v1:只有这一种推送
{ "type": "livescore_update", "data": [ { "match_id": 1234567, "score": "2-1", "minute": 67, ... } ] }

新版把它拆开并大幅扩展。 一条长连接上，可以按需订阅下面 4 种数据产品的任意组合，各自独立的订阅 code、推送 type,互不影响：

数据产品	订阅 code	订阅成功	取消 code	推送 `type`
比分	`20200`	`20201`	`21200`	`score_update`
赛况(事件流 + 技术统计)	`20000`	`20001`	`21000`	`situation_update`
滚球赔率	`20100`	`20101`	`21100`	`odds_live_update`
赛前赔率	`20300`	`20301`	`21300`	`odds_prematch_update`

两个最实在的变化：赔率数据第一次能走 WebSocket 推送（赛前 + 滚球），以及赛况独立成一条信息量最大的流（进球、红黄牌、换人等完整事件 + stats_json 技术统计 + ball_xy 球坐标）。一个滚球投注页面过去要 “WS 拿比分 + 轮询拿赔率 + 轮询拿事件” 三套逻辑拼起来，现在一条连接、一个 match_id 全搞定。

3.1 建立连接

新版WS地址(注意域名是 data. 不是旧版的 api.):

wss://data.anysport.io/v1/ws/live?api_key=YOUR_API_KEY

wss://data.anysport.io/v1/ws/live?api_key=YOUR_API_KEY

握手成功会收到一条 connected，此时还不会推数据，要发订阅消息之后才开始推：

{ "type": "connected", "message": "WebSocket connected. Send subscribe message to receive data.", "timestamp": "2026-07-13T08:00:00.000Z" }

{ "type": "connected", "message": "WebSocket connected. Send subscribe message to receive data.", "timestamp": "2026-07-13T08:00:00.000Z" }

3.2 订阅比分(`20200`)

过滤条件（match_id/league_id/country_id）放在订阅消息的 data 里，不再挂 URL。match_id 传 null 表示按套餐/过滤订阅全量：

{ "code": 20200, "trace": "score-sub-001", "data": { "match_id": null } }

{ "code": 20200, "trace": "score-sub-001", "data": { "match_id": null } }

推送（score_update，比分口径与 REST /livescore 完全一致）：

{
  "type": "score_update",
  "data": {
    "type": "score", "match_id": "as_3b37c382...", "home_team": "Argentina", "away_team": "Switzerland",
    "phase": "2H", "minute": 67, "home_score": 2, "away_score": 1, "ht_score": "1-0", "reg_score": "2-1"
  },
  "timestamp": "2026-07-13T15:47:01.250Z"
}

{
  "type": "score_update",
  "data": {
    "type": "score", "match_id": "as_3b37c382...", "home_team": "Argentina", "away_team": "Switzerland",
    "phase": "2H", "minute": 67, "home_score": 2, "away_score": 1, "ht_score": "1-0", "reg_score": "2-1"
  },
  "timestamp": "2026-07-13T15:47:01.250Z"
}

3.3 订阅实时赛况(`20000`)

{ "code": 20000, "trace": "situation-sub-001", "data": { "match_id": "as_3b37c382..." } }

{ "code": 20000, "trace": "situation-sub-001", "data": { "match_id": "as_3b37c382..." } }

推送（situation_update，含事件流、技术统计与球坐标）：

{
  "type": "situation_update",
  "data": {
    "type": "situation", "match_id": "as_3b37c382...", "status": "live", "minute": 67,
    "ball_xy": "0.52,0.48", "events_json": {}, "stats_json": {}
  },
  "timestamp": "2026-07-13T15:47:01.250Z"
}

{
  "type": "situation_update",
  "data": {
    "type": "situation", "match_id": "as_3b37c382...", "status": "live", "minute": 67,
    "ball_xy": "0.52,0.48", "events_json": {}, "stats_json": {}
  },
  "timestamp": "2026-07-13T15:47:01.250Z"
}

3.4 订阅滚球赔率(`20100`)/ 赛前赔率(`20300`)

{ "code": 20100, "trace": "live-odds-sub-001", "data": { "match_id": "as_3b37c382..." } }

{ "code": 20100, "trace": "live-odds-sub-001", "data": { "match_id": "as_3b37c382..." } }

推送（odds_live_update）：

{
  "type": "odds_live_update",
  "data": {
    "type": "odds", "match_id": "as_3b37c382...", "phase": "live", "main_market": "1X2",
    "home_odd": "2.10", "draw_odd": "3.40", "away_odd": "3.20", "markets_json": {}
  },
  "timestamp": "2026-07-13T15:47:01.250Z"
}

{
  "type": "odds_live_update",
  "data": {
    "type": "odds", "match_id": "as_3b37c382...", "phase": "live", "main_market": "1X2",
    "home_odd": "2.10", "draw_odd": "3.40", "away_odd": "3.20", "markets_json": {}
  },
  "timestamp": "2026-07-13T15:47:01.250Z"
}

赛前赔率订阅换成 code 20300 即可，推送 type 为 odds_prematch_update，data 结构与滚球赔率相同，区别只在 data.phase 为 prematch。

⚠️ 订阅状态不跨连接保留。 断线重连后要重新发一遍订阅消息，记得每 30 秒发一次心跳(code: 20010)，否则会因超时被断开。4xxxx 系列(如订阅失败 40301)是可修正的客户端错误，不会断连，检查消息格式/字段/套餐权限后重试即可。

四、旧版 v1 用户迁移清单(重要)

这一版有破坏性变更，旧版集成需要按下面几步升级。核心就三处：地址、认证、ID。

4.1 认证与地址(必改)

- # 旧版 v1
- GET https://api.anysport.io/v1/odds?match_id=1234567
- X-API-Key: YOUR_API_KEY                       # 或 ?api_key=YOUR_API_KEY

+ # 新版
+ GET https://data.anysport.io/v1/soccer/odds/prematch?match_id=as_3b37c382...
+ apikey: YOUR_API_KEY                           # 只认这个头,查询参数传 key 一律 401

- # 旧版 v1
- GET https://api.anysport.io/v1/odds?match_id=1234567
- X-API-Key: YOUR_API_KEY                       # 或 ?api_key=YOUR_API_KEY

+ # 新版
+ GET https://data.anysport.io/v1/soccer/odds/prematch?match_id=as_3b37c382...
+ apikey: YOUR_API_KEY                           # 只认这个头,查询参数传 key 一律 401

基础地址：api.anysport.io/v1 → data.anysport.io/v1/soccer (注意多了 /soccer 段)。
认证头：X-API-Key(或 ?api_key=)→ 只认 apikey 这个小写头。仍用 X-API-Key 或把 key 拼在 URL 上，都会返回 401 UNAUTHORIZED。

4.2 ID 从整数换成前缀字符串(必改)

旧版的 match_id/league_id/team_id 是纯整数，新版全部改为语义化前缀字符串：

前缀	实体	示例
`as_`	比赛(全接口统一)	`as_3b37c382f39a4235aa93705f053b2da4`
`asl_`	联赛	`asl_62db9cfc3ebf4b87a44570b16668b23e`
`ast_`	球队	`ast_9137ee449e3b40a68149ca319373adaf`
`asx_` `asp_` `asc_`	国家 / 球员 / 教练	—

数据库里存 ID 的字段类型、以及所有拼 URL 的地方，都要从整数改成字符串。好消息是同一个 match_id 贯穿赛程、比分、赛况、赔率以及 WebSocket,完全一致，不需要维护任何 ID 映射表。

4.3 赔率解析改按 `market_code`

原来按 market_name （”1X2″、”Over/Under”）字符串匹配的逻辑，改成按 market_code(match_winner、goals_over_under) 路由，并对未知 code 做降级。完整目录见新版文档的赛前/滚球盘口目录。

4.4 WebSocket 改用订阅协议

地址换成 wss://data.anysport.io/v1/ws/live
过滤条件从 URL 参数,改为发送订阅消息(code + data)
想要哪几路数据就订哪几个 code，并加上 30 秒心跳与断线重订逻辑

五、这些能力属于哪个套餐?

套餐	价格(USDT/月)	赔率	WebSocket
免费试用(7 天)	0	❌	❌
基础	99	❌	❌
专业	199	✅ 赛前赔率	❌
高级	399	✅ 赛前 + 滚球	✅(含全部四条数据流)

六、总结

这次升级把 AnySport 的两块核心能力顶了上去：

数据广度：赔率标准化为 market_code 字典,赛前 63 种 + 滚球 499 个，另加赛季/教练/伤停/赛况/事件等一批新端点
实时全量：WebSocket 从旧版单一比分流，扩展为比分 / 赛况 / 赛前赔率 / 滚球赔率四条可独立订阅的流，赔率首次上 WS，一条连接、一个 match_id 全打通

👉 现在就到 anysport.io 注册，免费试用 7 天，先把比分流跑通，再按需要升级到赔率与 WebSocket。

体育数据 API

AnySport 为开发者、数据平台与体育产品团队提供高性能、低延迟的体育数据 API 服务，覆盖全球主流体育赛事的实时比分、赛程、阵容及赔率数据。