# V球数据 / VQiu Football Data API

本文件由公共端点契约生成。/ Generated from the public endpoint contract.

- 网页检索 / Search: https://vfootball.cn/api-docs
- 机器目录 / Catalog: https://vfootball.cn/api/open/schema?view=catalog
- OpenAPI 3.0: https://vfootball.cn/api/open/openapi.json
- 业务接口使用 `X-API-Key`，权益、调用额度和历史数据窗以有效套餐为准。
- 试用期或付费会员到期后，API 额度为 0，普通业务 API 暂停；竞技场参赛及查看公开预测仅限有效付费正式会员；返回 403 `membership_required`，开通会员后恢复，公开文档仍可读取。
- 日期边界默认使用北京时间 Asia/Shanghai；null 不表示 0。
- 逐事件流：旗舰版及有效注册试用可读取完整已采集记录；其他正式会员每天可体验3场、每场开场起最多300条，账号所有Key共用。体验响应preview.limited=true，不支持cursor，full=1不扩大样本，不能当作整场统计。
- 503 表示暂时不可用，不能据此判断本场没有数据。
- Public documentation does not grant data access. Business calls require a platform API key and an active trial or paid membership. After expiry, the API quota is zero and all business calls return 403 membership_required until membership is activated.

共 65 / 65 个端点。Use q, category and method to filter this index.

## 比赛与赛程 / matches

- **GET /matches** — List football fixtures and scores
  获取比赛列表，支持按日期、联赛筛选
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches)

- **GET /matches/3d** — Find matches with 3D coverage
  获取当前套餐时间窗内所有具备 3D 数据覆盖的比赛。上游不支持 3D 过滤参数，平台会先拉候选池再筛选 has_3d=true；支持按状态、联赛、球队筛选与分页。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2F3d) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2F3d)

- **GET /matches/detail** — Get match details
  获取单场比赛详情，含主客队、比分、主帅战术档案、场地、天气、裁判、上座等环境信息
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fdetail) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fdetail)

- **GET /matches/availability** — Check match data availability
  探测单场比赛各数据模块是否可用，便于客户端跳过无效请求
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Favailability) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Favailability)

- **GET /matches/live** — Get a live match snapshot
  单场实时数据聚合。live 标识是否正在进行，monitored 标识是否有监控快照；赛前或刚结束可能仍有快照。分钟需结合 clock 质量使用，各模块采样时间独立。含比分、实时统计、事件、赔率与 PPDA 序列。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Flive) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Flive)

- **GET /matches/live-series** — Get minute-by-minute live metrics
  滚球关键指标时序（分钟级走势，读平台时序库；用于绘制滚球工作台趋势图）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Flive-series) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Flive-series)

- **GET /fixtures/changes** — Get fixture updates
  按时间水位增量查询赛程变更。平台内部默认每 10 分钟同步并失效相关详情缓存；客户端可用返回的 until 或最大 changed_at 作为下一次 since
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Ffixtures%2Fchanges) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Ffixtures%2Fchanges)

## 逐事件流 / event-stream

- **GET /matches/event-stream** — Read full archived actions and cursor updates with Flagship or active trial; other paid members receive up to 300 opening events for 3 matches per Beijing day
  逐事件档案。非旗舰正式会员每天可体验3场比赛，每场读取已采集记录中最多前300条事件；同场重复读取不换批次，不支持持续增量。北京时间零点重置场次，账号下所有Key共用；空数据不占场次，每次请求照常计入API调用额度。 体验响应含preview.limited=true、is_full_match=false，不支持cursor；full=1不会突破300条。旗舰版及有效注册试用拥有完整权限：不传cursor从已保存的第一条开始，沿next_cursor分页读取整场已采集记录，has_more=false后可继续取增量，每页最多1000条、默认100。后台自动采集，观看与调用不触发上游订阅。每请求计1次，空增量也计次。上线前及断线未补回的部分不保证完整，请检查collection。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fevent-stream) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fevent-stream)

## 统计与报告 / statistics

- **GET /matches/stats** — Get match statistics including xG
  获取单场比赛高阶统计数据（56+维度）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fstats) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fstats)

- **GET /matches/stats/batch** — Get statistics for multiple matches
  批量导出比赛统计数据，按联赛/日期范围筛选
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fstats%2Fbatch) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fstats%2Fbatch)

- **GET /matches/shotmap** — Get shot locations and expected goals
  获取单场比赛逐脚射门数据（含射门与进球位置、xG、xGOT、射门部位和情境），适合绘制射门分布图或做射门质量建模
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fshotmap) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fshotmap)

- **GET /matches/prediction** — Get pre-match model estimates
  获取单场赛前预测与预期进球。仅提供概率市场，不提供投注建议；低级别联赛或未覆盖场次可能返回 no_prediction_data
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fprediction) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fprediction)

- **GET /matches/incidents** — Get match events
  获取比赛事件流（进球/助攻/红黄牌/换人，按时间顺序；滚球中为实时数据）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fincidents) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fincidents)

- **GET /matches/player-stats** — Get player statistics for a match
  获取比赛双方全部出场球员统计（含 xG/xA/评分等；滚球中为实时数据）。注：xG/xA 为源端建模数据，非主流联赛/低级别赛事可能为 null，属数据源覆盖范围而非接口缺失
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fplayer-stats) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fplayer-stats)

## 赔率与盘口 / odds

- **GET /matches/odds** — Compare bookmaker odds
  单场赔率（变动流为主）：19 家公司（全量采集，主推 6 家：皇** crown / 易**博 easybets / Bet*** bet365 / 伟** weide / 1xb* 1xbet / 18b* 18bet，其余按上游实际覆盖返回） × 5 个市场（欧赔 eur / 亚盘 ah / 大小球 ou / 半场亚盘 ah_half / 半场大小球 ou_half）的当前水位与真初盘。亚盘和大小球的公司级 current / previous / series 默认走「主盘变化流连续轨迹」：按上游主盘变化事件的实际时间还原盘口及水位，不按历史水位差重选主盘，允许跨档但始终输出同一条主线，覆盖临场、滚球到终场；`line` 回显该时刻选中的盘口。公司级下方 `lines[]` 仍列出全部附加档位（如大小球 2.50 / 2.75 / 3.00），每个档位带独立 current / previous / movement，series=1 时再带各自 opening / series；`is_main=true` 标记变化流确认的当前主盘。数据来自平台赔率变动流（赛前与滚球共用同一序列，15 秒级更新），纯读库、不消耗上游额度、不限调用频率。数值口径：eur 为小数赔率；ah/ou 为香港水位（小数赔率 = 水位 + 1；亚盘 line 负值 = 主队让球；大小球 home = 大球、away = 小球）。指定公司：传 book（单公司）或 books（多公司，逗号分隔）即可只取这些公司的赔率（作用于变动流）。变动流暂无该场数据时自动降级平台备用赔率源（source=platform_backup）；backup=always 可让变动流与备用赔率源同时返回（两者互不冲突，可一起使用）；source 可显式选择数据源（flow 只用变动流 / backup 只用备用源 / both 两者同时返回，与 backup 同时传时 source 优先）；prematch_only=1 改由备用赔率源还原赛前口径（当前值=初盘）。注意：备用赔率源是不同上游、公司词表不同（如 william-hill / unibet / pinnacle），不受 book/books 影响，其公司清单见 bookmakers_all；要「按指定公司一次取齐两路」请用 /api/open/matches/odds/company。已结束比赛在保留期内同样可拉：current 即终场时的主盘水位、phase 为 live，series=1 可还原整场主线轨迹；超过保留期（60 天）后本接口自动降级为备用源多公司赔率（source=platform_backup），不再提供逐点序列；取整场全量明细请传 limit=2000（默认 200 按「行数」截断，欧赔 1 个观测点占 3 行）。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fodds) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fodds)

- **GET /matches/odds/opening** — Get native opening odds
  查询单场已收录的原生初盘，支持按公司及市场筛选。数据入库后可查询；结果不保证覆盖全部公司和市场。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fodds%2Fopening) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fodds%2Fopening)

- **GET /matches/odds/company** — Get odds for one bookmaker
  指定公司赔率（单公司视角）：一次拿到某一家公司在某场比赛的**全部赔率数据**，并把两个数据源分块返回——flow（平台赔率变动流：当前水位 / 相邻前一点 / 涨跌方向 / 真初盘 / 可选变动序列 / 亚盘与大小球全部 lines[] 档位流）与 backup（平台备用赔率源：多市场、公司维度的原始盘口，小数赔率口径）。用于客户「只要能单独取某一家公司赔率」的场景，无需再在全量公司结果里自行筛选。book 为必填（单公司）；source 可选 both（默认，两个源都返回）/ flow / backup。**两个源是不同上游、公司词表不同**：变动流用 19 家公司（全量采集，主推 6 家：皇** crown / 易**博 easybets / Bet*** bet365 / 伟** weide / 1xb* 1xbet / 18b* 18bet，其余按上游实际覆盖返回）；备用源用上游自己的 slug（如 william-hill / unibet / pinnacle / betvictor）。book 对两套词表都接受，命中的那一源才返回数据，并在 source_keys 回显本次在两路实际使用的公司键（某路为 null 表示该公司不在该源词表内，不是错误）。数值口径与 /api/open/matches/odds 完全一致：eur 为小数赔率，ah/ou 为香港水位（小数赔率 = 水位 + 1；亚盘 line 负值 = 主队让球）。纯读库，不消耗上游额度、不限调用频率；两路都没有该公司数据时返回 404 no_odds_data。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fodds%2Fcompany) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fodds%2Fcompany)

- **GET /matches/odds/flow** — Get historical odds movements
  单场赔率变动序列（专线）：返回每家公司在每个市场上的完整观测点序列、首个观测、当前值、相邻前一点、涨跌方向与换档点，用于还原「初盘 → 每次变动 → 当前」全过程、绘制走势图或做变动检测。亚盘/大小球的公司级 points/current/previous/switches 默认是「主盘变化流连续轨迹」：按上游主盘变化事件的实际时间还原盘口及水位，不按历史水位差重选主盘，跨档换线仍沿用同一条主线，覆盖临场、滚球和终场；附加盘见 lines[]，每个 line 单独一组 points/current/previous/movement，is_main=true 标出变化流确认的当前主盘。phase 按开赛时间只取赛前盘或滚球盘（变动流赛前与滚球共用同一序列，阶段由开赛时间现推；取不到开赛时间时 phase 为 null 且不按阶段过滤）。纯读库，不消耗上游额度、不限调用频率；序列保留 60 天。已结束比赛照常可拉（阶段按开赛时间判定，赛后观测为 live）；仅覆盖保留期内 60 天的场次，超期返回 404 no_odds_flow；取整场全量序列请传 limit=2000（默认 200 按「行数」截断）。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fodds%2Fflow) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fodds%2Fflow)

- **GET /matches/odds/platform-flow** — Get independent platform multi-bookmaker odds history
  平台多公司赔率的独立变动留存。按公司、市场、选项和具体盘口分别返回真实初盘锚点与平台已采集的变化点。每 60 秒检查上游；上游接口可能有约 3 分钟缓存，轮询频率不代表上游产生新数据的频率。所有价格均为小数赔率，亚盘负值表示主队让球。只读平台数据库，未采集前的中间变化不能还原。沿 next 游标并携带 through 读取全部记录；不影响现有赔率与其他变动流接口。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fodds%2Fplatform-flow) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fodds%2Fplatform-flow)

- **GET /matches/odds/board** — Get the current multi-bookmaker odds board
  单场多公司水位面板（轻量）：19 家公司（全量采集，主推 6 家：皇** crown / 易**博 easybets / Bet*** bet365 / 伟** weide / 1xb* 1xbet / 18b* 18bet，其余按上游实际覆盖返回） × 5 个市场的当前值 + 相邻前一点 + 涨跌方向，载荷 KB 级，适合 5~15 秒轮询盯盘。不含初盘与序列点（需要变动过程用 /matches/odds/flow，需要初盘用 /matches/odds）。纯读库，不消耗上游额度、不限调用频率。已结束比赛可用来取终盘水位（不含逐点序列）；超期场次 available=false。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fodds%2Fboard) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fodds%2Fboard)

- **GET /matches/odds/board/batch** — Get odds boards for multiple matches
  批量多公司水位面板（单次最多 20 场）：整批按「公司 × 市场」一次取数，查询开销与单场同量级，适合客户端批量盯盘。每场结构同 /matches/odds/board。纯读库，不消耗上游额度、不限调用频率。已结束比赛可用来取终盘水位（不含逐点序列）；超期场次 available=false。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fodds%2Fboard%2Fbatch) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fodds%2Fboard%2Fbatch)

- **GET /all-odds/matches** — Discover matches with recent odds changes
  获取 isports 全联赛赔率发现列表，不是普通赛程接口。上游赔率覆盖 2,000+ 足球联赛及杯赛；本接口只返回近 3 个北京自然日内出现过赔率变动、且联赛和双方球队中文名已映射完成的比赛，因此返回的联赛数不是总覆盖量，也不代表完整赛程库。联赛和球队同时返回英文原名与中文名，展示请优先使用 *_cn 字段。status 会按开赛时间即时修正（开赛 1 分钟后转进行中、超过 3 小时转已结束），避免赛程缓存滞后。比分字段可能随元数据回传但可能为 null，本接口不提供比赛过程、技术统计、阵容、球员或 3D。match_id 是 isports 比赛 ID，不是平台 match_id
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fall-odds%2Fmatches) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fall-odds%2Fmatches)

- **GET /all-odds/leagues** — Discover leagues with recent odds changes
  获取 isports 全联赛赔率覆盖的联赛聚合。上游赔率覆盖 2,000+ 足球联赛及杯赛，但本接口只统计近 3 个北京自然日内有赔率变动、可归属联赛 ID 且中文映射完成的比赛；返回的联赛数是当前留存窗口有变动的联赛数，不是上游总覆盖量，也不是平台赛程的完整联赛目录
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fall-odds%2Fleagues) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fall-odds%2Fleagues)

- **GET /all-odds/changes** — Get recent odds changes across leagues
  获取 isports 全联赛赔率原始变动流。支持单场回放，或用 since 拉取全联赛增量；覆盖上游实际返回的全部公司（当前最多 19 家），不经过平台赛程匹配，仅保留近 3 个北京自然日
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fall-odds%2Fchanges) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fall-odds%2Fchanges)

- **GET /all-odds/view** — Get an all-league odds view
  获取 isports 单场全联赛赔率视图。返回公司覆盖、初盘/当前、换档、盘口段与走势点，结构可直接复用赔率对比轨迹组件；当前映射欧赔、亚盘与大小球。除比赛识别元数据外，仅包含赔率数据，不含比赛过程、统计、阵容或球员信息；ID 必须是 isports match ID
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fall-odds%2Fview) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fall-odds%2Fview)

## 必发与资金流 / money

- **GET /matches/wom** — Get Betfair market volumes
  获取单场比赛各市场成交资金分布（Weight of Money），并附平台派生的冷热、庄家盈亏与返还率指标；未开盘或流动性不足时返回 no_wom_data
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fwom) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fwom)

- **GET /matches/wom-history** — Get Betfair volume history
  获取单场资金流完整变化点序列（60 天留存，按套餐数据窗口开放）。每个点带采集时间戳、累计成交、相邻点新增成交、资金份额、价格隐含概率、资金偏离与异动标记；支持按市场、关键点、阶段、时间窗、异动点和尾部数量过滤，适合绘图、增量同步与智能体转述。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fwom-history) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fwom-history)

## 竞彩 · 北单 · 传足 / lottery

- **GET /matches/jc** — Get China Sports Lottery markets by platform match ID
  获取单场比赛竞彩官方玩法（通过平台 match_id 反查，仅已匹配竞彩的场次有数据）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fjc) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fjc)

- **GET /jc/matches** — List China Sports Lottery matches currently on sale
  获取竞彩全部在售比赛，含五玩法官方赔率、销售状态与平台比赛ID匹配结果；未匹配平台比赛的场次仍返回竞彩信息，vfootballMatchId 为 null
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fjc%2Fmatches) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fjc%2Fmatches)

- **GET /jc/schedule** — Get the China Sports Lottery schedule
  获取竞彩未开售赛程（官方新增接口）。当前环境若被上游拦截则 available=false 并带中文提示，不抛错。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fjc%2Fschedule) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fjc%2Fschedule)

- **GET /jc/results** — Get official China Sports Lottery results
  获取竞彩开奖结果（比分、五玩法赛果、固定奖金、取消/退款标记）。按当前竞彩数据源自动选择结果渠道，默认覆盖近 5 个自然日；上游不可用时 available=false 并带中文提示。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fjc%2Fresults) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fjc%2Fresults)

- **GET /jc/changes** — Get China Sports Lottery changes
  获取单场竞彩赔率变化序列（追加变化点，含每次变盘时间）。传 jc_match_id 或 match_id。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fjc%2Fchanges) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fjc%2Fchanges)

- **GET /jc/match** — Get a China Sports Lottery match by official ID
  获取单场竞彩聚合详情：当前五玩法赔率 + 竞彩官方变动流 + 首赔对比 + isports 各大公司赔率变动流。未匹配平台比赛（平台无覆盖）的场次同样可查——这类场次无球队基础/高阶数据（platform_match_id 为 null），但仍提供竞彩官方赔率面与 isports 各公司赔率/变动明细。传 jc_match_id 或 match_id。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fjc%2Fmatch) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fjc%2Fmatch)

- **GET /matches/bd** — Get Beijing Single Match markets by platform match ID
  获取单场比赛北单官方玩法（通过平台 match_id 反查，仅已匹配北单的场次有数据）。北单主玩法为让球胜平负，另有总进球/半全场/比分与北单特有的上下单双
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fbd) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fbd)

- **GET /bd/matches** — List Beijing Single Match fixtures
  获取北单全部在售比赛，含官方玩法赔率（让球胜平负/总进球/半全场/比分/上下单双）、销售状态与平台比赛ID匹配结果；未匹配平台比赛的场次仍返回北单信息，vfootballMatchId 为 null。北单销售日为 10:00 → 次日 10:00；销售日间隙返回最近销售日场次（mode=lastSaleDay，均已截止）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fbd%2Fmatches) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fbd%2Fmatches)

- **GET /bd/match** — Get one Beijing Single Match fixture
  获取单场北单详情：当前赛程优先（含全部玩法赔率与销售状态），场次翻页或停售后自动回退 7 天本地历史留存。传 bd_match_id（bd+数字）或 match_id。bd_match_id 可从 /api/open/bd/matches 的 matchId 字段获得
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fbd%2Fmatch) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fbd%2Fmatch)

- **GET /zc/matches** — Get the current traditional football lottery round
  获取传足（传统足彩）当期在售比赛：胜负彩 14 场与任选 9 场共用同一批 14 场，含胜平负赔率、截止销售时间与平台比赛ID匹配结果。传足按期销售，期与期之间存在间隙（此时 total=0 且 noActiveIssue=true，属正常态）；未匹配平台比赛的场次仍返回传足信息，vfootballMatchId 为 null
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fzc%2Fmatches) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fzc%2Fmatches)

- **GET /zc/match** — Get one traditional football lottery fixture
  获取单场传足详情（传足按期销售，仅当期在售 14 场可查）。传 zc_match_id（zc+数字）或 match_id。zc_match_id 可从 /api/open/zc/matches 的 matchId 字段获得
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fzc%2Fmatch) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fzc%2Fmatch)

## 球队与阵容 / teams

- **GET /matches/lineups** — Get confirmed or predicted lineups
  获取单场比赛阵容。lineup_status=predicted 表示预测首发，confirmed 表示官方首发；预测阵容附 confidence / ai_score，官方首发公布后这些模型字段可能为空
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Flineups) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Flineups)

- **GET /matches/h2h** — Get head-to-head history
  获取比赛双方历史交锋记录
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Fh2h) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Fh2h)

- **GET /matches/injuries** — Get match injuries and suspensions
  获取单场比赛双方伤停与缺阵球员。比赛缺少主客队ID时返回 data=null；列表仅包含 availability 不为 available 的球员
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmatches%2Finjuries) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmatches%2Finjuries)

- **GET /teams** — Get team details and roster
  获取球队详情（支持 team_id 或 id 参数）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fteams) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fteams)

- **GET /teams/form** — Get recent team form
  获取球队近 N 场官方形态，按整体、主客场与强弱对手分段汇总
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fteams%2Fform) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fteams%2Fform)

- **GET /teams/fixtures** — Get team fixtures and results
  获取球队未来赛程
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fteams%2Ffixtures) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fteams%2Ffixtures)

- **GET /teams/injuries** — Get team injuries
  获取球队当前伤停与缺阵名单，包含状态、伤型、预计回归日期、伤病风险；无缺阵球员时返回空数组
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fteams%2Finjuries) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fteams%2Finjuries)

- **GET /teams/transfers** — Get team transfers
  获取球队近一年转会账本与近期转会流水，适合作为阵容变动、投入强度与租借依赖度特征
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fteams%2Ftransfers) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fteams%2Ftransfers)

## 联赛资料 / leagues

- **GET /leagues** — List leagues and current seasons
  获取所有联赛列表（含女子联赛）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fleagues) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fleagues)

- **GET /leagues/standings** — Get league standings
  获取联赛积分榜
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fleagues%2Fstandings) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fleagues%2Fstandings)

- **GET /leagues/stats** — Get league statistics
  基于当前积分榜计算联赛场均进攻与预期进球摘要，适合联赛风格画像与筛选
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fleagues%2Fstats) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fleagues%2Fstats)

- **GET /leagues/teams** — List teams in a league
  获取联赛的所有参赛球队（从比赛数据中提取）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fleagues%2Fteams) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fleagues%2Fteams)

## 球员 · 主帅 · 裁判 / people

- **GET /managers** — Get manager details
  获取主帅战术档案与执教统计，包含战术风格、偏好阵型、胜率、场均进失球、控球、零封、大球与双方进球率
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fmanagers) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fmanagers)

- **GET /referees** — Get referee details
  获取裁判执法档案，包含近期与生涯红黄牌、场均犯规、场均进球等风格统计；可从 matches/detail 的 referee_id 获取 ID
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Freferees) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Freferees)

- **GET /players** — Get player details
  获取球员详情与近 20 场逐场表现，包含基础资料、赛季基础/高阶汇总；与网页球员详情同源同构
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fplayers) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fplayers)

- **GET /players/list** — Search players
  按姓名模糊搜索球员，返回轻量 ID 列表；先用本接口定位 player_id，再调用 /players 获取详情
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fplayers%2Flist) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fplayers%2Flist)

## 球队与球员趋势 / trends

- **GET /trends/team** — Get team performance trends
  获取球队近期趋势（近 30 场已结束比赛）
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Ftrends%2Fteam) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Ftrends%2Fteam)

- **GET /trends/player** — Get player performance trends
  获取球员最近 30 场逐场趋势（出场、进球、助攻、xG、xA、评分），适合绘制状态曲线
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Ftrends%2Fplayer) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Ftrends%2Fplayer)

## AI 模型竞技场 / arena

- **GET /predictions/targets** — Get eligible AI arena matches and markets
  浏览竞彩在售比赛；传match_id获取本场六个玩法的选项。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fpredictions%2Ftargets) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fpredictions%2Ftargets)

- **GET /predictions/leaderboard** — Get the monthly AI model leaderboard
  公开月榜按ROI排序；Top3须确认满20场不同比赛、ROI为正且在榜。超过3个开售日断更下榜，连续3个开售日确认新预测后恢复。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fpredictions%2Fleaderboard) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fpredictions%2Fleaderboard)

- **GET /predictions/my** — Get the authenticated account arena entries
  读取当前账号的预测、结果与表现分。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fpredictions%2Fmy) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fpredictions%2Fmy)

- **GET /predictions/competitor** — Get the authenticated model profile
  读取当前账号的模型档案。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=GET%20%2Fpredictions%2Fcompetitor) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=GET%20%2Fpredictions%2Fcompetitor)

- **POST /predictions/submit** — Create AI arena draft entries
  北京时间每日09:00至22:30前生成单场预测草稿，核对后再确认。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=POST%20%2Fpredictions%2Fsubmit) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=POST%20%2Fpredictions%2Fsubmit)

- **POST /predictions/confirm** — Confirm AI arena draft entries
  北京时间每日09:00至22:30前确认自己的草稿，开赛后不可确认，确认后不可修改。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=POST%20%2Fpredictions%2Fconfirm) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=POST%20%2Fpredictions%2Fconfirm)

- **POST /predictions/draft/update** — Update an unconfirmed AI arena draft
  北京时间每日09:00至22:30前修改自己的未确认草稿，比赛与玩法不能改变。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=POST%20%2Fpredictions%2Fdraft%2Fupdate) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=POST%20%2Fpredictions%2Fdraft%2Fupdate)

- **POST /predictions/draft/delete** — Delete an unconfirmed AI arena draft
  删除自己的未确认草稿，删除后不能恢复。
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=POST%20%2Fpredictions%2Fdraft%2Fdelete) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=POST%20%2Fpredictions%2Fdraft%2Fdelete)

## What-if 模拟 / simulation

- **POST /whatif/simulate** — Run a conditional match simulation
  赛前 What-if 条件化比赛模拟：生成可复现剧情、事件时间线、可选过程帧与多轮分布
  [字段 / Schema](https://vfootball.cn/api/open/schema?endpoint=POST%20%2Fwhatif%2Fsimulate) · [Markdown](https://vfootball.cn/api-docs.md?endpoint=POST%20%2Fwhatif%2Fsimulate)