V球数据提供 RESTful API，方便个人分析师和 AI 系统接入足球高阶数据。 所有 API 均需通过 API Key 鉴权，返回统一 JSON 格式。
注册账号并登录后，此处将自动显示您的专属 API Key。
在 HTTP 请求头中携带 X-API-Key 字段：
X-API-Key: vq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxhttps://vfootball.cn/api/open/所有接口返回统一 JSON 格式：
{
"success": true,
"data": { ... },
"error": "错误信息（仅失败时）"
}包月 / 每日
10,000 次
突发 200 次/分钟
包季 / 每日
20,000 次
突发 600 次/分钟
包年 / 每日
50,000 次
突发 1,200 次/分钟
每日额度按北京时间自然日重置；/api/open/schema 不消耗额度，数据端点进入合法路由后计 1 次（参数错误或上游错误也计入）。超出返回 429，请按 Retry-After 退避重试，并通过 X-RateLimit-Remaining 与 X-RateLimit-Burst-Remaining 观察剩余额度。赔率相关接口读取的是平台自有赔率变动流，仍计入平台每日调用额度。
import requests
API_KEY = "你的_API_Key"
BASE_URL = "https://vfootball.cn/api/open"
headers = {
"X-API-Key": API_KEY
}
# 获取今日比赛列表
response = requests.get(
f"{BASE_URL}/matches",
headers=headers,
params={"status": "notstarted", "limit": 10}
)
data = response.json()
print(data)const API_KEY = "你的_API_Key";
const BASE_URL = "https://vfootball.cn/api/open";
// 获取比赛详情（含赔率 + 统计）
async function getMatchAnalysis(matchId) {
const headers = { "X-API-Key": API_KEY };
const [detail, odds, stats] = await Promise.all([
fetch(`${BASE_URL}/matches/detail?match_id=${matchId}`, { headers }),
fetch(`${BASE_URL}/matches/odds?match_id=${matchId}`, { headers }),
fetch(`${BASE_URL}/matches/stats?match_id=${matchId}`, { headers }),
]);
return {
detail: await detail.json(),
odds: await odds.json(),
stats: await stats.json(),
};
}
getMatchAnalysis(12345).then(console.log);# 获取联赛积分榜
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/leagues/standings?league_id=1"
# 获取比赛赔率
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds?match_id=12345"
# 获取比赛必发指数（各市场成交资金分布）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/wom?match_id=12345"
# 获取资金流完整变化点（时间戳 + 新增成交 + 异动标记）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/wom-history?match_id=12345&market=1X2_HOME_FT&limit=500"
# 获取赔率变动序列（初盘 → 每次变动 → 当前，可按 phase 只看滚球盘）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds/flow?match_id=12345&phase=live"
# 获取多公司水位面板（轻量，适合 5~15 秒轮询）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds/board?match_id=12345"
# 批量获取多场水位面板（最多 20 场）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/odds/board/batch?match_ids=12345,67890"
# 获取竞彩官方在售比赛（聚合）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/jc/matches"
# 获取单场竞彩玩法（平台 match_id 反查）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/jc?match_id=12345"
# 获取滚球实时数据（实时比分/xG/事件流/实时赔率，仅进行中比赛）
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/live?match_id=12345"
# 获取滚球关键指标分钟级时序
curl -H "X-API-Key: 你的_API_Key" \
"https://vfootball.cn/api/open/matches/live-series?match_id=12345&minutes=30"/api/open/leagues获取所有联赛列表
示例：
https://vfootball.cn/api/open/leagues/api/open/leagues/standings获取联赛积分榜
参数：
league_idint必填联赛 ID示例：
https://vfootball.cn/api/open/leagues/standings?league_id=1/api/open/leagues/stats获取联赛统计数据（场均 xG/xGA 等）
参数：
league_idint必填联赛 ID示例：
https://vfootball.cn/api/open/leagues/stats?league_id=1/api/open/leagues/teams获取联赛球队列表
参数：
league_idint必填联赛 ID示例：
https://vfootball.cn/api/open/leagues/teams?league_id=1/api/open/matches获取比赛列表（支持筛选；包月及以上套餐不传日期时默认返回近 30 天的比赛，可直接拉近一个月）。已完赛场次含半场比分字段 home_score_ht / away_score_ht。每场含 has_3d 字段（3D 数据覆盖标识：true = 该场有 3D 直播/3D 回放数据覆盖，可用于筛选与徽标展示）。队伍/联赛名同时返回原文（home_team 等，英文/西语等原始命名）与平台中文译名（home_team_cn / away_team_cn / league_name_cn，未收录为 null）
参数：
league_idint可选联赛 ID 筛选team_idint可选球队 ID 筛选statusstring可选状态筛选。live=所有进行中比赛（聚合值）；单值白名单：notstarted / firsthalf / halftime / secondhalf / overtime / inprogress / finished / postponed / canceled / interrupted，非法值返回 400 及合法值列表date_fromstring可选开始日期（YYYY-MM-DD）；数据窗按套餐分级：试用24小时/包月30天/包季90天/包年365天，早于套餐窗口返回 400date_tostring可选结束日期（YYYY-MM-DD），缺省为今天limitint可选每页条数（默认 50，拉取近一个月全量请配合 offset 分页，见响应 pagination.total）offsetint可选分页偏移orderingstring可选排序（如 -event_date）示例：
https://vfootball.cn/api/open/matches?status=finished&limit=200&offset=0/api/open/matches/detail获取比赛详情（含场地、天气、裁判、上座等环境信息；has_3d 字段标识该场是否有 3D 直播/回放数据覆盖）
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/detail?match_id=600981/api/open/matches/availability获取单场数据能力探测结果：stats / lineups / incidents / shotmap / xg / momentum / average_positions / player_stats / prediction / broadcasts / odds 哪些模块可用，并返回 lineup_status、stat_keys、odds_markets，便于客户端跳过无效请求
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/availability?match_id=223067/api/open/fixtures/changes按 since 水位增量查询赛程变更（开赛时间、状态、场地、转播等）。返回 changes[] 与 truncated；平台内部默认每 10 分钟同步并失效相关详情缓存，客户端可用 until 或最大 changed_at 作为下一次水位
参数：
sincestring必填查询起点（ISO 8601）league_idint可选联赛 ID 筛选changestring可选变更类型筛选，如 kickoff_changed / status_changed / venue_changed / broadcast_addedlimitint可选返回上限，默认 200，最大 500示例：
https://vfootball.cn/api/open/fixtures/changes?since=2026-09-26T00:00:00Z/api/open/matches/stats获取比赛统计数据（控球率、射门、xG 等）。口径说明：tackles_won 为抢断成功率（0-100 百分数，非次数；0% 时可能返回 null，请按 0 处理）；xg 为对象 {actual: 数值, estimated: 是否估算值}
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/stats?match_id=12345/api/open/matches/stats/batch批量获取比赛统计（按联赛+日期范围，或按指定比赛 ID 列表）
参数：
league_idint可选联赛 ID（与 ids 二选一）idsstring可选比赛 ID 列表，逗号分隔（与 league_id 二选一，如 213523,213524）date_fromstring可选开始日期 YYYY-MM-DDdate_tostring可选结束日期 YYYY-MM-DDstatusstring可选比赛状态，默认 finishedhas_xgboolean可选是否仅含有 xG 的比赛limitint可选每页数量offsetint可选偏移量示例：
https://vfootball.cn/api/open/matches/stats/batch?ids=213523,213524/api/open/matches/prediction获取赛前预测数据（含预期进球 xG），未开赛比赛生成、可用于赛前 xG 取值（expected_goals.home/away）；开赛后仍返回赛前生成值。meta 字段说明：generated_at 生成时间 / feature_cutoff_at 特征截止时间（上游未单独提供，赛前模型截止即生成时刻，为 null）/ includes_lineups 是否含首发（恒 false）/ includes_latest_odds 是否保证含最新赔率（恒 false）。仅含概率数据，不含投注建议。404 时区分 error_code：match_not_found（比赛不存在）/ no_prediction_data（比赛存在但无预测）
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/prediction?match_id=213559/api/open/matches/odds【变动流·单场赔率】全量公司（上游有多少家就返回多少家，主推 6 家：皇**/易**博/Bet***/伟**/1xb*/18b*）× 3 个市场（欧赔/亚盘/大小球）的当前水位与真初盘，来自平台赔率变动流（赛前与滚球共用同一序列，15 秒级更新）。半场盘（半场亚盘/半场大小球）已下架。纯读库、不消耗上游额度、不限调用频率。数值口径：eur 为小数赔率；亚盘/大小球为香港水位（小数赔率 = 水位 + 1；亚盘负值 = 主队让球；大小球 home = 大球、away = 小球）。变动流暂无该场数据时自动降级平台备用赔率源（source=platform_backup）；backup=always 可让两路一起返回；prematch_only=1 取赛前口径（当前值=初盘）。main_lines 返回平台主盘口元数据（无主盘信息为 null）。series=1 附带变动序列。已结束比赛在保留期内照常可拉：current 即终盘水位、phase 为 live，series=1 可还原整场轨迹；超出保留期（30 天）后本接口自动降级为备用源多公司赔率（source=platform_backup），不再提供逐点序列
参数：
match_idint必填比赛 ID（也可用路径 /matches/{id}/odds）booksstring可选公司过滤：crown/easybets/bet365/weide/1xbet/18bet/ladbrokes/williamhill/vcbet/mansion88/interwetten/10bet/12bet/sbobet/bwin 等（逗号分隔），默认全部（只返回该场有数据的公司）marketsstring可选市场过滤：eur/ah/ou，逗号分隔，默认全部（半场盘已下架，传入会被忽略；别名 market）seriesint可选series=1 附带每家公司每个市场的变动序列观测点backupstring可选auto（默认，变动流无数据才降级）/ always（两路一起返回）/ never（只用变动流）prematch_onlyint可选prematch_only=1 只取赛前口径（由备用源还原，当前值=初盘）since / since_minutesstring可选只取该时刻之后（ISO 8601）或最近 N 分钟的观测点（上限 30 天）limitint可选每组观测点上限，默认 200，上限 2000；上限按「行数」计，欧赔 1 个观测点占 3 行、亚盘/大小球占 2 行，默认 200 只覆盖尾部窗口，要取整场完整轨迹请传 limit=2000示例：
https://vfootball.cn/api/open/matches/odds?match_id=12345&series=1/api/open/matches/odds/flow【变动流·序列专线】返回每家公司在每个市场上的完整观测点序列、首个观测、当前值、相邻前一点、涨跌方向与换档点，用于还原「初盘 → 每次变动 → 当前」全过程或绘制走势图。phase 按开赛时间只取赛前盘/滚球盘。纯读库、不消耗上游额度；序列保留 30 天。已结束比赛照常可拉（阶段按开赛时间判定，赛后观测为 live）；仅覆盖保留期内的场次，超期返回 404 no_odds_flow
参数：
match_idint必填比赛 ID（也可用路径 /matches/{id}/odds/flow）booksstring可选公司过滤，逗号分隔，默认全部marketsstring可选市场过滤，逗号分隔，默认全部phasestring可选prematch=赛前盘 / live=滚球盘 / all=全部（默认）since / since_minutesstring可选只取该时刻之后或最近 N 分钟的观测点（上限 30 天）limitint可选每组观测点上限，默认 200，上限 2000；上限按「行数」计，欧赔 1 个观测点占 3 行、亚盘/大小球占 2 行，默认 200 只覆盖尾部窗口，要取整场完整轨迹请传 limit=2000示例：
https://vfootball.cn/api/open/matches/odds/flow?match_id=12345&phase=live&limit=200/api/open/matches/odds/board【变动流·轻量面板】全量公司 × 5 个市场的当前值 + 相邻前一点 + 涨跌方向，载荷 KB 级，适合 5~15 秒轮询盯盘（不含初盘与序列点）。纯读库、不消耗上游额度、不限调用频率。已结束比赛可用它取终盘水位（current），超期或该场无变动流数据时 available=false
参数：
match_idint必填比赛 ID（也可用路径 /matches/{id}/odds/board）booksstring可选公司过滤，逗号分隔，默认全部marketsstring可选市场过滤，逗号分隔，默认全部示例：
https://vfootball.cn/api/open/matches/odds/board?match_id=12345/api/open/matches/odds/board/batch【变动流·批量面板】一次取多场（最多 20 场）的当前水位与涨跌方向，整批按「公司 × 市场」一次取数，查询开销与单场同量级。每场结构同 /matches/odds/board。纯读库、不消耗上游额度
参数：
match_idsstring必填比赛 ID 列表，逗号分隔（最多 20 场，超出截断并返回 truncated=true）booksstring可选公司过滤，逗号分隔，默认全部marketsstring可选市场过滤，逗号分隔，默认全部limitint可选每组观测点上限，默认 60示例：
https://vfootball.cn/api/open/matches/odds/board/batch?match_ids=12345,67890/api/open/matches/wom获取比赛必发指数数据（Weight of Money），随进阶版会员开放、无需另行购买。返回各市场资金分布和成交额。单位口径（2026-09 修正统一）：share 资金占比(%)、implied_probability 隐含概率(%)、pnl_pct 庄家盈亏率(%)（如 5.23 表示 5.23%，百分点值非小数）、payout 市场返还率(%)；volume 成交额单位 EUR。404 时区分 error_code：match_not_found（比赛不存在）/ no_wom_data（比赛存在但未开盘或流动性不足）
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/wom?match_id=12345/api/open/matches/wom-history【资金流·变化点序列】返回单场从赛前、滚球到完赛的资金流变化点。每个点带采集时间戳、累计成交、相邻点新增成交、资金份额、价格隐含概率、资金偏离与异动标记；适合绘图、增量同步、资金异动检测和智能体赛后转述。留存 30 天，实际可查窗口按套餐开放；留存优先，缺失或过旧时实时回源并归档
参数：
match_idint必填比赛 ID（也可用路径 /matches/{id}/wom-history）market / marketsstring可选市场键或逗号分隔市场键列表，默认全部；如 1X2_HOME_FTpoint / pointsstring可选关键点快捷查询：first=首个记录，last_prematch=开赛前最后一条赛前记录，latest=最新/终盘记录（closing 为别名）；逗号分隔可组合，可与 since/until 限定时间窗，但不能与 phase/anomaly/limit 组合phasestring可选all=全部 / prematch=赛前 / live=滚球 / postmatch=完赛后（默认 all）since / untilstring可选时间窗过滤，ISO 8601 格式；增量拉取时传上一轮最后一个点的 tanomalyint可选=1 时只返回异动事件点：初始偏离超阈、进入 ±5pp 偏离带，或带内单点变化 ≥2pplimitint可选每个市场返回的尾部变化点数量，默认不截断，上限 5000；只需要尾部窗口时可传 limit示例：
https://vfootball.cn/api/open/matches/wom-history?match_id=12345&market=1X2_HOME_FT&point=first,last_prematch,latest/api/open/matches/h2h获取历史交锋记录
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/h2h?match_id=12345/api/open/matches/lineups获取阵容信息。lineup_status=predicted 为预测首发，每队含 confidence（整体置信度），首发/替补球员含 ai_score（模型置信度）；lineup_status=confirmed 为官方首发，官方名单公布后预测字段可能为 null
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/lineups?match_id=12345/api/open/matches/shotmap获取射门地图数据
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/shotmap?match_id=12345/api/open/matches/injuries获取伤病信息
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/injuries?match_id=12345/api/open/matches/jc获取单场比赛竞彩官方玩法（胜平负/让球胜平负/总进球/半全场/比分赔率）。通过平台 match_id 反查竞彩，仅展示已匹配竞彩的场次
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/jc?match_id=12345/api/open/matches/live滚球实时数据聚合（仅进行中比赛有实时数据；已结束比赛返回赛果快照）。含实时比分/半场比分/实时统计（实时 xG、每分钟 xG 曲线、攻防势头、射门地图）/实时事件流/滚球实时赔率/PPDA 序列。odds 赔率对象含元信息：update_time 平台抓取时间（疑似数日前的旧盘可用此判断新鲜度）、phase 盘口阶段（prematch=赛前盘 / live=滚球盘）、is_live 是否滚球盘（布尔）。单点按需刷新：仅被调用时触发该场数据更新，无人调用不打上游
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/live?match_id=12345/api/open/matches/incidents获取比赛事件流（进球/红黄牌/换人/角球等关键事件），滚球中为实时数据
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/incidents?match_id=12345/api/open/matches/player-stats获取单场球员统计（评分/进球/助攻/xG/xA/传球/抢断/对抗等），滚球中为实时数据
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/player-stats?match_id=12345/api/open/matches/live-series获取滚球关键指标分钟级时序（势头/PPDA 等按分钟序列），用于绘制滚球走势图
参数：
match_idint必填比赛 IDminutesint可选回看分钟数（5~180，默认 60）示例：
https://vfootball.cn/api/open/matches/live-series?match_id=12345&minutes=30/api/open/jc/matches获取竞彩官方全部在售比赛（含全部玩法赔率与平台匹配信息），供竞彩用户集中查看
示例：
https://vfootball.cn/api/open/jc/matches/api/open/bd/matches获取北单官方全部在售比赛（含让球胜平负/总进球/半全场/比分/上下单双玩法赔率与平台匹配信息），供北单用户集中查看
示例：
https://vfootball.cn/api/open/bd/matches/api/open/bd/match获取单场北单详情（当前赛程优先，翻页/停售后退 7 天本地留存）。传 bd_match_id（bd+数字，从 /bd/matches 的 matchId 获得）
参数：
bd_match_idstring必填北单场次 ID（bd+数字）示例：
https://vfootball.cn/api/open/bd/match?bd_match_id=bd2041616/api/open/matches/bd获取单场比赛北单官方玩法（让球胜平负/总进球/半全场/比分/上下单双赔率）。通过平台 match_id 反查北单，仅展示已匹配北单的场次
参数：
match_idint必填比赛 ID示例：
https://vfootball.cn/api/open/matches/bd?match_id=12345/api/open/teams获取球队详情
参数：
team_idint必填球队 ID示例：
https://vfootball.cn/api/open/teams?team_id=678/api/open/teams/form获取球队近 N 场官方形态：overall / home / away / vs_stronger / vs_weaker 分段，每段含胜平负、进失球、form、points_per_match 与 stats
参数：
team_idint必填球队 ID（也可用路径 /teams/{team_id}/form）lastint可选回看场次，1-20，默认 10league_idint可选联赛 ID 筛选venuestring可选home / away 主客场筛选示例：
https://vfootball.cn/api/open/teams/form?team_id=678&last=10/api/open/teams/fixtures获取球队近期赛程
参数：
team_idint必填球队 ID示例：
https://vfootball.cn/api/open/teams/fixtures?team_id=678/api/open/teams/injuries获取球队当前伤停与缺阵名单：状态、伤型、预计回归日期、伤病风险；无缺阵球员时返回空数组
参数：
team_idint必填球队 ID（也可用路径 /teams/{team_id}/injuries）示例：
https://vfootball.cn/api/open/teams/injuries?team_id=678/api/open/teams/transfers获取球队近一年转会账本与近期流水：净支出、转入 / 转出结构、租借依赖度、转会费与球员方向
参数：
team_idint必填球队 ID（也可用路径 /teams/{team_id}/transfers）示例：
https://vfootball.cn/api/open/teams/transfers?team_id=678/api/open/managers获取主帅战术档案：风格、偏好阵型、胜率、场均进失球、控球、零封、大球与双方进球率；ID 可从比赛详情的 home_manager_profile / away_manager_profile 获取
参数：
manager_idint必填主帅 ID（也可用路径 /managers/{manager_id}）示例：
https://vfootball.cn/api/open/managers?manager_id=318/api/open/referees获取裁判执法档案：近期与生涯红黄牌、场均犯规、场均进球；ID 可从比赛详情的 referee_id 获取
参数：
referee_idint必填裁判 ID（也可用路径 /referees/{referee_id}）示例：
https://vfootball.cn/api/open/referees?referee_id=128/api/open/players获取球员完整详情：profile（身高/体重/身价/合同）+ basic（赛季汇总）+ advanced（赛季 xG/xA/射门/传球/防守等）+ match_stats（近 20 场逐场明细，含每场 xG/xA/xGOT、对手、赛果）
参数：
player_idint必填球员 ID示例：
https://vfootball.cn/api/open/players?player_id=901/api/open/players/list搜索球员列表
参数：
searchstring必填球员名称搜索limitint可选每页条数（默认 20）示例：
https://vfootball.cn/api/open/players/list?search=Messi&limit=5/api/open/trends/team获取球队近期趋势（近 30 场）
参数：
team_idint必填球队 ID示例：
https://vfootball.cn/api/open/trends/team?team_id=678/api/open/trends/player获取球员近期趋势（近 30 场）
参数：
player_idint必填球员 ID示例：
https://vfootball.cn/api/open/trends/player?player_id=901每个接口返回的 JSON 字段可通过 /api/open/schema 端点获取字段说明，方便程序化对接。
GET https://vfootball.cn/api/open/schemaGET https://vfootball.cn/api/open/schema?endpoint=GET%20/matches/detailendpoint 参数值可从端点列表返回的 name 字段获取，需要对空格进行 URL 编码（%20）
📖 字段说明示例
{
"success": true, // 请求是否成功
"data": {
"id": 12345, // 比赛ID
"status": "finished", // 比赛状态
"event_date": "2026-08-15 02:30:00", // 开赛时间
"venue": "...", // 球场
"round": "...", // 轮次
"home_team": { "id": 678, "name": "Bournemouth", "logo": "..." }, // 主队
"away_team": { "id": 679, "name": "Man City", "logo": "..." }, // 客队
"home_score": 2, // 主队进球
"away_score": 1, // 客队进球
"league_name": "英超", // 联赛名
"league_id": 383 // 联赛ID
}
}平台赔率数据来自赔率变动流：赛前盘与滚球盘共用同一条序列底座，15 秒级落库，只记录每次变动。本接口按「市场 → 公司」返回当前水位与真初盘，一次调用即可拿到全量公司（上游有多少家就返回多少家）× 3 个市场的全部盘口（半场盘已下架）；纯读库、不消耗上游额度、不限调用频率（受平台通用限流约束）。
公司与市场：
books）：crown 皇** · easybets 易**博 · bet365 Bet*** · weide 伟** · 1xbet 1xb* · 18bet 18b*markets）：eur 欧赔 1X2 · ah 亚盘 · ou 大小球（半场盘已下架）unit 字段标明）：eur 为小数赔率；亚盘与大小球为香港水位，换算 小数赔率 = 水位 + 1。亚盘 line 为负表示主队让球；大小球 home 为大球、away 为小球。movement 为 up 涨 / down 跌 / steady 未变 / none 不可比，均以相邻前一点为基准。响应格式（节选：皇**亚盘 + 易**博欧赔）：
{
"success": true,
"data": {
"match_id": 12345,
"source": "platform_flow",
"available": true,
"updated_at": "2026-09-20T11:02:13.000Z",
"data_age_seconds": 42,
"series_retention_days": 30,
"market_order": ["eur", "ah", "ou"],
"markets": {
"ah": {
"key": "ah",
"label": "亚盘 · 全场让球",
"unit": "hk_water_level",
"line_based": true,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"line": -0.75,
"phase": "live",
"current": { "home": 0.93, "away": 0.95 },
"previous": { "home": 0.95, "away": 0.93 },
"movement": { "home": "down", "away": "up" }
}
]
},
"eur": {
"key": "eur",
"label": "欧赔 1X2（胜平负）",
"unit": "decimal",
"line_based": false,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"line": null,
"phase": "live",
"current": { "home": 2.86, "draw": 3.40, "away": 2.45 },
"previous": { "home": 2.87, "draw": 3.38, "away": 2.44 },
"movement": { "home": "down", "draw": "up", "away": "up" }
}
]
}
},
"backup": false
}
}初盘与变动序列：传 series=1 时，每家公司会额外返回opening（真初盘：首次观测到的 home/draw/away 与时刻）与series（观测点数组，每点含 t 秒级时间戳 / line / home / away / draw / phase）。 只想要「初盘 → 当前 → 每次变动」的完整过程与换档点，推荐直接用序列专线/api/open/matches/odds/flow。
已结束比赛的赔率怎么拉：端点与参数完全一致，只要该场仍在保留期（30 天）内就能照常取——终盘水位看/matches/odds/board 或/matches/odds 的current（即终盘），完整变动轨迹看/matches/odds/flow 或/matches/odds?series=1。 注意默认 limit=200 按「行数」截断，只够当前与邻近的观测点，要整场全量明细请显式传limit=2000。 超出 30 天后序列点已清理：/matches/odds/flow 返回404 no_odds_flow，/matches/odds 自动降级为备用源多公司赔率 （source=platform_backup，没有逐点序列），/matches/odds/board 返回available=false；需要更早的历史请在采集期自行落库。
关于半场盘（ah_half / ou_half）：半场亚盘与半场大小球仅由变动流主源（source=platform_flow）提供，主流赛事通常在开赛前 1~3 天开出； 备用赔率源（source=platform_backup，降级时响应带 coverage_note） 不含半场市场；部分小赛事博彩公司全程不开半场盘，此时变动流下 half 市场的 companies 为空（available=false），属上游正常行为而非接口故障。
变动序列专线响应格式（/matches/odds/flow，节选）：
{
"success": true,
"data": {
"match_id": 12345,
"source": "platform_flow",
"available": true,
"updated_at": "2026-09-20T11:02:13.000Z",
"series_retention_days": 30,
"markets": {
"ah": {
"key": "ah",
"label": "亚盘 · 全场让球",
"unit": "hk_water_level",
"line_based": true,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"samples": 128,
"line": -0.75,
"phase": "live",
"first": { "t": 1787582100, "line": -0.5, "home": 0.99, "away": 0.89 },
"current": { "home": 0.93, "away": 0.95 },
"previous": { "home": 0.95, "away": 0.93 },
"movement": { "home": "down", "away": "up" },
"switches": [
{ "t": 1787589741, "from": -0.5, "to": -0.75 }
],
"points": [
{ "t": 1787582100, "line": -0.5, "home": 0.99, "away": 0.89, "phase": "prematch" },
{ "t": 1787589741, "line": -0.75, "home": 0.95, "away": 0.93, "phase": "live" },
{ "t": 1787590120, "line": -0.75, "home": 0.93, "away": 0.95, "phase": "live" }
]
}
]
}
}
}
}phase 阶段过滤：传 phase=prematch 只看赛前盘，phase=live 只看滚球盘（默认 all）。 变动流赛前与滚球共用同一条序列，阶段由开赛时间现推；若该场未记录开赛时间，phase 为null 且不做阶段过滤，请按 null 兼容处理。
盯盘场景推荐用面板接口：仅返回全量公司 × 5 个市场的当前值 + 相邻前一点 + 涨跌方向，载荷 KB 级，适合5~15 秒轮询；批量面板一次可取最多 20 场，服务端整批按「公司 × 市场」一次取数，查询开销与单场同量级。面板不含初盘与序列点（初盘用/matches/odds，变动过程用 /matches/odds/flow）。
批量面板响应格式（节选）：
{
"success": true,
"data": {
"requested": 2,
"returned": 2,
"truncated": false,
"available": 1,
"matches": [
{
"match_id": 12345,
"source": "platform_flow",
"available": true,
"updated_at": "2026-09-20T11:02:13.000Z",
"data_age_seconds": 42,
"market_order": ["eur", "ah", "ou"],
"markets": {
"ou": {
"key": "ou",
"label": "大小球 · 全场",
"unit": "hk_water_level",
"line_based": true,
"companies": [
{
"book": "crown",
"book_name": "皇**",
"available": true,
"line": 2.5,
"phase": "live",
"current": { "home": 0.90, "away": 0.98 },
"previous": { "home": 0.92, "away": 0.96 },
"movement": { "home": "down", "away": "up" }
}
]
}
}
},
{
"match_id": 67890,
"source": "platform_flow",
"available": false
}
]
}
}接入建议：
/matches/odds/board（批量用 /board/batch），轮询间隔 5~15 秒。/matches/odds/flow，配合 since_minutes 只取增量窗口。/matches/odds、/matches/odds/flow、/matches/odds/board 都照常返回（current 即终盘水位，phase=live 为滚球段）；要拿全部变动明细必须显式传 limit=2000，默认 200 只返回尾部窗口。超期后 flow 返回 404 no_odds_flow，/matches/odds 降级为备用源（source=platform_backup，多公司赔率、无逐点序列）。available=false，可传 backup=always 让备用赔率源一起返回。返回必发指数（Weight of Money，各市场真实成交资金经上游二次加工的加权分布）数据，覆盖全场/上半场等全时段、全部市场（含大小球各盘口、波胆、角球、红牌等）的资金分布与成交额；随进阶版会员开放、无需另行购买。打开页面时实时拉取最新成交快照（上游随滚球/赛前持续更新）。
响应格式：
{
"success": true,
"data": {
"id": 587703,
"home_team": "NEC Nijmegen",
"away_team": "Bodø/Glimt",
"league": "UEFA Champions League",
"status": "notstarted",
"total_volume": 58184.30,
"money": [
{
"kind": "1X2", // 市场类型（枚举见下方说明）
"line": null, // 盘口线（AH/OU/CORNERS 等带线市场有效，如 2.5/8.5）
"selection": "HOME", // 投注选项：HOME/AWAY/DRAW/OVER/UNDER/YES/NO/比分/组合
"period": "FT", // 时段：FT=全场/1H=上半场/2H=下半场（同一市场分期独立成交）
"name": "Match Odds 1", // 上游市场名
"volume": 12000.50, // 该选项成交额
"market_volume": 30280.00, // 该市场总成交额
"share": 39.63, // 资金占比（%）= volume/market_volume，即必发指数
"league_avg_volume": 80000.00, // 联赛该市场平均成交额（资金热度对比基准）
"price": 2.86, // 当前成交价位（欧盘赔率口径）
"previous_price": 2.87, // 上一价位
"implied_probability": 34.97, // 价位隐含概率（%）= 1/price
"is_live": false, // 是否滚球阶段
"captured_at": "2026-08-19T14:21:00Z" // 数据时间
}
]
}
}市场类型（kind）枚举：1X2=胜平负 OU=大小球（按 line 分盘） AH=亚盘让球 BTTS=双方进球 DNB=不让球（平局退款） DC=双重机会 CS=波胆（正确比分） HTFT=半场/全场 TG=总进球 CORNERS=角球（按 line 分盘） SENDOFF=红牌
解读口径：share 即该选项的必发指数（资金占比）；implied_probability 为价位隐含概率； 两者差值（share − implied）即「冷热偏离」，正数代表资金实际配置高于价格隐含（热门/资金流入），负数代表低于价格隐含（冷门/资金流出）； 某市场内各选项成交并非同时刻，不同盘口（line）为相互独立市场。
金额单位：EUR（欧元）。派生字段：每个 money 条目另含 hot（冷热指数 = share − implied，正=热/负=冷）、pnl（庄家盈亏金额 = market_volume − volume×price，负=该方向若胜出兑付缺口）、pnl_pct（盈亏率 = pnl / market_volume × 100）、payout（市场返还率 = Σvolume / Σ(volume×price) × 100）。热卖(share高)的选项 pnl 为负 —— 资金过热方向若打出庄家即亏，同一判断的两种视角。
用于还原一场比赛的资金流过程：不是只看当前快照，而是拿「每次变化」的时间戳与数值。适合绘制资金曲线、做资金异动提醒，或让智能体在赛后转述“什么时间、哪个方向、流入了多少”。
响应格式（已截取单市场示例）：
{
"success": true,
"data": {
"match_id": 601971,
"source": "retained",
"status": "inplay",
"retention_days": 30,
"anomaly_threshold_pp": 5,
"anomaly_change_threshold_pp": 2,
"point_count": 35,
"returned_point_count": 35,
"anomaly_point_count": 3,
"series": {
"1X2_HOME_FT": [
{
"t": "2026-10-07T08:12:30.000Z", // 变化点时间戳
"phase": "live", // prematch / live / postmatch
"key_points": ["latest"], // 关键点模式标记，可同点命中多个
"volume": 1280.40, // 累计成交（EUR）
"volume_delta": 86.20, // 相邻点新增成交（EUR）
"market_volume": 9260.00, // 所属市场累计成交（EUR）
"share": 13.83, // 资金份额（%）
"price": 4.30, // 当前价格
"implied_probability": 23.26, // 价格隐含概率（%）
"divergence": -9.43, // share − implied_probability（百分点）
"is_anomaly": true, // 异动事件
"anomaly_reason": "sharp_divergence_change" // 初始超阈/进入偏离带/偏离快速变化
}
]
}
}
}全量与关键点：不传 limit 即返回完整序列；只要首个记录、开赛前最后赛前记录、最新/终盘记录时，传point=first,last_prematch,latest，返回点会带key_points 标记。增量拉取时用本地最后一个点的t 作为 since，只取新增点。 若只关心异动，直接加 anomaly=1；若只看滚球段，加phase=live。
口径提示：volume 是累计成交，重复求和会放大金额；volume_delta 才是本变化点新增成交。首个点没有前值时volume_delta=null。异动采用事件口径：初始偏离超过 5pp、进入 ±5pp 偏离带，或在带内单点变化至少 2pp；持续停留在偏离带内不会每个点重复标记。异动是市场结构描述，不构成建议。
平台全部 xG 数据均已通过开放 API 提供，按使用场景选择端点：
/matches/prediction → markets.expected_goals.home / away（模型在开赛前生成，开赛后仍返回赛前值）/matches/live → stats.home.xg / stats.away.xg，逐分钟累积曲线在 xg_per_minute（仅进行中比赛）/matches/stats → stats.{home,away}.xg.actual（estimated=true 表示估算值）；批量筛选有 xG 的场次用 /matches/stats/batch?has_xg=true/matches/player-stats → player_stats[].expected_goals / expected_assists；赛季累计用 /trends/player/{player_id} 的 expected_goals/trends/team/{team_id} → expected_goals 趋势序列/matches/shotmap → shots[].xg（射门期望值）与 xgot（射后值，滚球/完赛阶段）status 主状态（查询与返回通用）：notstarted 未开赛 / firsthalf 上半场 / halftime 中场休息 / secondhalf 下半场 / overtime 加时 / inprogress 进行中（滚球总态）/ interrupted 中断 / finished 已完赛 / postponed 推迟 / canceled 取消。 查询聚合值 live 等价于全部进行中状态。
阶段（period）字段命名对照：比赛快照 period = 1st_half / halftime / 2nd_half（与 status 对应）； 必发指数 money[].period = FT 全场 / 1H 上半场 / 2H 下半场； 盘口类数据中的 1T / HT 为「上半场」的缩写变体，语义同 1H。跨端点比对请按语义映射，不要按字符串相等比对；主状态以 status 字段为准。
平台对接中国竞彩官方在售比赛与全部玩法赔率（胜平负/让球胜平负/总进球/半全场/比分），并匹配到平台比赛，供竞彩用户集中查看或 AI 分析。
全部在售竞彩比赛及玩法赔率，含平台匹配信息。无需 match_id。
{
"success": true,
"data": {
"fetchedAt": "2026-08-20T10:00:00Z",
"updatedAt": "2026-08-20T10:01:20Z",
"total": 32, // 在售总场数（=0 且 dataSource=live 才是「官方当前未开售」）
"matched": 28, // 命中平台比赛数
"dataSource": "live", // live=实时拉取 / cache=新鲜缓存 / stale=上游异常已回退旧数据
"cacheAgeMs": 120000, // 当前数据距今年龄（毫秒），便于判断时效
"upstreamError": null, // 仅 dataSource=stale 时给出上游失败原因
"matches": [
{
"matchup": "日本J联赛", // 竞彩官方联赛名
"matchNo": "周三001",
"homeTeam": "大阪钢巴",
"awayTeam": "东京FC",
"had": {"v": "1.85", "f": 0}, // 胜平负（v=赔率字符串，f=浮动）
"hhad": {"v": "3.20", "f": 0}, // 让球胜平负
"ttg": {"v": "2.10", "f": 0}, // 总进球
"hafu": {"v": "4.00", "f": 0}, // 半全场
"crs": {"v": "8.50", "f": 0}, // 比分
"updateTime": "2026-08-20T09:55:00Z",
"platform": { // 平台匹配（未命中为 null）
"matchId": 213523,
"homeTeam": "大阪钢巴",
"awayTeam": "东京FC",
"eventDate": "2026-08-20T10:00:00Z",
"leagueId": 88,
"status": "notstarted"
}
}
]
}
}通过平台 match_id 反查该场的全部官方玩法赔率（仅已匹配竞彩的场次有数据）。
{
"success": true,
"data": {
"match": {
"homeTeam": "大阪钢巴",
"awayTeam": "东京FC",
"homeRank": 2,
"awayRank": 5,
"league": "日本J联赛",
"had": {"v": "1.85", "f": 0}, // 胜平负
"hhad": {"v": "3.20", "f": 0}, // 让球胜平负（含让球数）
"ttg": {"v": "2.10", "f": 0}, // 总进球
"hafu": {"v": "4.00", "f": 0}, // 半全场
"crs": {"v": "8.50", "f": 0}, // 比分
"updateTime": "2026-08-20T09:55:00Z",
"sellStatus": "Selling"
}
}
}玩法说明：had=胜平负 hhad=让球胜平负 ttg=总进球 hafu=半全场 crs=比分；赔率统一为 {v, f} 结构，f 为官方浮动标记（0 固定 / 1 升 / -1 降）。
传 jc_match_id（竞彩官方场次ID）获取单场：当前五玩法赔率 + 竞彩官方变动流 + isports 各大公司赔率变动流。未匹配平台的竞彩场次同样可查——这类场次平台无球队基础/高阶数据（platform_match_id 为 null），但仍提供竞彩官方赔率面与 isports 各公司赔率/变动明细。
GET /api/open/jc/match?jc_match_id=2041616&api_key=YOUR_KEY
{
"success": true,
"data": {
"available": true,
"source": "live", // live=当前在售 / history=已下架读留存
"match": {
"match_id": "2041616",
"platform_match_id": null, // 未匹配平台为 null（无平台基础/高阶数据）
"league": "亚运会女足",
"home_team": "中国女足",
"away_team": "菲律宾女足",
"match_num": "1001",
"match_date": "2026-09-21",
"match_time": "15:00:00"
},
"current": { "had": {}, "hhad": {...}, "ttg": {...}, "hafu": {...}, "crs": {...} }, // 当前五玩法赔率 {v,f}
"changes": { "total": 3, "points": [ { "captured_at": "...", "update_time": "...", "odds": {...} } ] }, // 竞彩官方变动流
"diff": { "total": 5, "rows": [ { "time": "...", "market": "hhad", "outcome": "h", "from": "1.80", "to": "1.78" } ] },
"first_vs_current": [ { "market": "hhad", "outcome": "h", "first": "1.80", "current": "1.78" } ],
"isports": { // isports 各公司赔率变动流（未匹配平台场次的主数据面）
"enabled": true,
"matched": true,
"isports_match_id": 261088036, // 匹配到的 isports 场次ID（未匹配为 null，reason 说明原因）
"reason": "cached",
"updated_at": 1789950660, // 上游盘口最后更新时间（秒）
"has_data": true,
"market_types": ["1X2", "AH_2.25", "OU_3", "..."],
"market_type_labels": { "1X2": "欧赔", "AH_2.25": "亚盘 2.25", "OU_3": "大小球 3" },
"companies": [ { "slug": "crown", "name": "皇**" }, { "slug": "macauslot", "name": "澳*" }, ... ],
"odds": {
"1X2": { "crown": { "home": "2.10", "draw": "3.30", "away": "3.40", "home_prematch": "2.05", "home_movement": "up" } },
"AH_2.25":{ "crown": { "line": 2.25, "home_price": "0.95", "away_price": "0.85", "home_prematch": "0.92", "away_movement": "up" } },
"OU_3": { "crown": { "line": 3, "over_price": "0.90", "under_price": "0.90", "over_movement": "down" } }
}
}
}
}变动字段：各公司 odds[市场][公司] 含当前值、初盘值与变动方向（*_movement：up 升 / down 降 / steady 稳）。
平台对接中国体育彩票北京单场（北单）在售比赛与全部玩法赔率（让球胜平负/总进球/半全场/比分/上下单双），并匹配到平台比赛，供北单用户集中查看或 AI 分析。北单销售日为 10:00 → 次日 10:00；销售日间隙返回最近销售日的已截止场次（mode=lastSaleDay）。
全部在售北单比赛及玩法赔率，含平台匹配信息。无需参数。
{
"success": true,
"data": {
"updatedAt": "2026-09-27 09:45:00", // 赔率最新更新时间
"total": 32, // 在售总场数（=0 且 dataSource=live 才是「官方当前未开售」）
"matched": 28, // 命中平台比赛数
"dataSource": "cache", // live=实时拉取 / cache=新鲜缓存 / stale=上游异常已回退旧数据
"mode": "live", // live=当前在售 / lastSaleDay=销售日间隙回退最近销售日（均已截止）
"cacheAgeMs": 120000,
"matches": [
{
"matchId": "bd2041616", // 北单场次ID（用于 /bd/match 查单场）
"vfootballMatchId": 223067, // 平台比赛ID（未匹配为 null，可直接查 /matches/detail）
"matchNum": "26", // 北单场次号
"league": "意大利甲级联赛",
"homeTeam": "罗马",
"awayTeam": "佛罗伦萨",
"goalLine": "-1", // 让球数（正=主队受让，负=主队让球）
"wdl": { "h": {"v":"1.85","f":0}, "d": {"v":"3.40","f":0}, "a": {"v":"4.20","f":0} }, // 让球胜平负
"ttg": { "s0": {"v":"8.5","f":0}, "s1": {"v":"4.3","f":0} /* s0~s7，s7=7球及以上 */ },
"hafu": { "hh": {"v":"3.2","f":0} /* hh/ha/hd/ah/aa/ad/dh/da/dd 九项 */ },
"crs": { "s10": {"v":"6.5","f":0} /* 比分 25 档 */ },
"uo": { "us": {"v":"1.9","f":0}, "ud": {"v":"1.9","f":0}, "ds": {"v":"1.9","f":0}, "dd": {"v":"1.9","f":0} }, // 上下单双（北单特有）
"score": null, // 彩果：全场比分（未开奖为 null）
"result": null, // 彩果：让球胜平负结果
"sellStatus": 1, // 1=在售 0=停售
"platform": { "matchId": 223067, "homeTeam": "Roma", "awayTeam": "Fiorentina",
"eventDate": "2026-09-27T18:30:00Z", "leagueId": 1, "status": "notstarted" }
}
]
}
}传 bd_match_id（bd+数字）获取单场全部玩法赔率与销售状态；当前赛程优先，场次翻页或停售后自动回退 7 天本地历史留存（source=history）。
GET /api/open/bd/match?bd_match_id=bd2041616&api_key=YOUR_KEY
{
"success": true,
"data": {
"available": true,
"source": "live", // live=当前在售赛程 / history=读 7 天本地留存
"provider": "okooo",
"match": { "matchId": "bd2041616", "matchNum": "26", "league": "意大利甲级联赛",
"homeTeam": "罗马", "awayTeam": "佛罗伦萨", "goalLine": "-1",
"wdl": {...}, "ttg": {...}, "hafu": {...}, "crs": {...}, "uo": {...},
"updateTime": "2026-09-27 09:45:00", "sellStatus": 1 }
}
}通过平台 match_id 反查该场的北单玩法赔率（仅已匹配北单的场次有数据；未匹配时 matched=false 并带 reason）。
GET /api/open/matches/bd?match_id=223067&api_key=YOUR_KEY
{
"success": true,
"data": {
"matched": true,
"match": { "matchId": "bd2041616", "homeTeam": "罗马", "awayTeam": "佛罗伦萨",
"goalLine": "-1", "wdl": {...}, "ttg": {...}, "hafu": {...},
"crs": {...}, "uo": {...}, "updateTime": "2026-09-27 09:45:00" }
}
}玩法说明：wdl=让球胜平负 ttg=总进球 hafu=半全场 crs=比分 uo=上下单双（北单特有）；赔率统一为 {v, f} 结构，v='-' 表示该项未开售，f 为浮动标记。
您的 AI 智能体可通过 API Key 直接调用 V球数据接口，获取实时足球数据进行分析。
复制场景提示词（12 条精品模板）在 V球数据平台注册账号并登录后，此处将自动显示您的专属 API Key。
在您的 AI 智能体（如 Codex、扣子、WorkBuddy、豆包、Zcode、DeepSeek、智谱清言、Kimi 等平台，或自定义 Agent）中，添加 HTTP 工具或 Function Calling， 配置请求头 X-API-Key， 指向对应的数据接口即可。
智能体可根据用户提问，自动调用相应的接口获取比赛详情、赔率、统计、历史交锋等数据， 结合大模型能力生成分析报告。
💡 推荐组合接口
对于赛前分析场景，建议同时调用：matches/detail + matches/odds + matches/odds/flow + matches/h2h + teams/fixtures
联系管理员
购买激活码 / API Key / 技术支持 · QQ 2771440771