---
name: qiuzhong-basketball-client
description: Query basketball v2 schedules, scores, leagues, teams, players, game statistics, available prematch odds, and linked Chinese sports-lottery basketball data using a customer's API Key.
---
# 球中篮球 v2

基址 `https://qiuzhong.fastoffice.site/v1`。新版篮球使用 `/basketball/v2/`，客户一次查询取得服务器已整理的资料。按问题选择最少的接口，完整复用同一次响应，不为了队名、ID或盘口重复请求。

## 首次接入

每个新会话先读取本 Skill，长会话距上次读取满24小时再读取。首次使用或更换 Key 调用一次 `/usage`，核对 `数据.篮球` 的已开通、状态、到期时间、今日剩余、每分钟限额、总额度和总剩余。同一会话复用核验结果；未开通、过期或额度耗尽停止业务请求。到期时间为null表示长期有效，总额度非null表示有效期累计上限。成功业务请求计一次，与返回场数无关。

Key取当前会话或环境变量 `QIUZHONG_API_KEY`，只放在 `X-Api-Key` 请求头，只发送到上述HTTPS域名，不跟随跨域重定向，不在回答、日志或URL中输出。读取Skill不发送Key。参数不确定时查 [接口文档](https://qiuzhong.fastoffice.site/openapi.json)，只读篮球相关内容。

核验后简短回复：“篮球已开通，有效期至××，今日剩余×次，每分钟最多×次。支持竞彩篮球、NBA及其他已收录篮球比赛的赛程、比分和已有盘口，以及联赛排名、球队与球员资料和技术统计。”有累计额度时补充总剩余。用户已有问题就直接查询；没有问题可问“想看明天竞彩、今天NBA，还是某场盘口？”不要复述整份说明。

## 查询入口

聚合列表日期以北京时间解释，支持昨天、今天、明天，默认今天。完整比赛查询 /basketball/v2/games 支持按目录实际覆盖的日期、联赛、赛季、球队或比赛ID查询。ID来自实际响应，不自行构造。下列路径相对基址。

| 需要的数据 | 一次请求 |
| --- | --- |
| 篮球比赛、比分和已有盘口 | `/basketball/v2/matches?date={YYYY-MM-DD}` |
| NBA比赛、比分和已有盘口 | `/basketball/v2/matches?league=nba&date={YYYY-MM-DD}` |
| 指定编号日的竞彩，含跨日开赛比赛 | `/basketball/v2/jc?date={YYYY-MM-DD}` |
| 指定实际开赛日的竞彩，含前一编号日跨日比赛 | `/basketball/v2/jc?date={YYYY-MM-DD}&dateBasis=kickoff` |
| 某个竞彩编号 | `/basketball/v2/jc?date={YYYY-MM-DD}&number={完整竞彩编号}` |
| NBA赛季球队、排名和球队统计 | `/basketball/v2/nba?season={YYYY-YYYY}` |
| 某队赛季统计 | `/basketball/v2/nba/teams/{basketballTeamIdV2}?season={YYYY-YYYY}` |
| 仅官方赛程、固定奖金及彩果 | `/jclq/matches`；有该入口返回的数字竞彩ID时可用 `/jclq/matches/{jcId}` |

```text
GET /basketball/v2/matches?league=nba&date=2026-11-14
GET /basketball/v2/jc?date=2026-11-14&dateBasis=kickoff
GET /basketball/v2/nba?season=2026-2027
```

示例日期与赛季需按用户问题替换。今天进行中／未开赛比赛，在一次列表响应内按 `比赛状态` 筛选“进行中”／“未开赛”。不要用整季资料寻找某日赛程。

“明天竞彩有哪些比赛”默认按实际开赛日，即 `dateBasis=kickoff`；明确说“明天编号”才按编号日。显示真实编号和开赛时间，不能把次日凌晨比赛遗漏。问“301”时在对应编号日已有列表内定位，或使用真实完整编号如“周五301”，不把301当比赛ID。

v2比赛、球队、联赛、竞彩和公司ID分别以 `bm_`、`bt_`、`bl_`、`bj_`、`bc_` 开头并以 `_v2` 结尾；不能传入旧版或足球入口。v2的 `bj_…_v2` 不能传给要求数字ID的 `/jclq/matches/{jcId}`。竞彩聚合列表已含已有奖金、彩果与前瞻，普通查询无需再调用官方单场入口。

## 完整篮球查询

以下均以 `/basketball/v2/` 为前缀。字段和筛选详见 [篮球接口文档](https://qiuzhong.fastoffice.site/docs/?sport=basketball)。先复用会话已有目录和ID，不反复请求相同数据。

| 路径 | 用途 |
| --- | --- |
| `timezone`、`seasons`、`countries` | 时区、赛季、国家地区 |
| `leagues` | 联赛目录、各赛季数据覆盖 |
| `teams`、`players` | 球队与球员资料 |
| `statistics` | 指定联赛、赛季、球队的赛季汇总 |
| `standings`、`standings/stages`、`standings/groups` | 排名、阶段、分组 |
| `games`、`games/h2h` | 比赛、两队交锋 |
| `games/statistics/teams` | 比赛球队统计 |
| `games/statistics/players` | 比赛球员统计，或指定球员与赛季的逐场统计 |
| `odds`、`bookmakers`、`bets` | 完整公司报价、公司目录、盘口类型 |

完整查询响应使用 `总数`、`分页`、`列表`；业务字段保留英文名称，名称不擅自翻译或合并。`分页`非空且仍有下一页时才按page读取，不把第一页称为全部。ID都用响应中的_v2标识，h2h是两个球队ID以逗号分隔；ids最多20个比赛ID，以逗号分隔。不要使用足球ID或数字编号。未知头像／标志链接可为空。

空缓存返回503，后台统一准备；首次最多等待后重试一次，不连续轮询、不直接请求其他网站。新接口全部开放不表示每个联赛、赛季或球员都有完整数据，先看覆盖与实际返回。账号状态与本服务权限只查 `/usage`，不查询来源账号。

## 盘口、比分与统计

- 竞彩查询读聚合行的 `赛前盘口`，NBA 查询用 `matches?league=nba` 的 `公司赔率`。关联缺失显示待关联。同公司已有皇冠兼容字段时，只展示一次。
- 竞彩和 NBA 优先展示该公司对应玩法的 `初盘`、`赛前即时盘`。有 `赛前终盘` 时按终盘展示。让分、大小分为香港盘水位，胜负为十进制赔率。让分正数表示主队让分，负数表示主队受让。其余 `市场` 或 `odds` 返回的报价按原玩法解释，不归入初盘或终盘。缺失盘口留空，不编造滚球或变化历史。
- 比分与分节直接取返回值；列表消失、停售或开奖不能单独判断完赛。未知值为null，不填0:0。
- NBA包含可确认的常规赛、附加赛和季后赛，排除季前赛。球队赛季汇总、排名和单场球队技术统计按实际已有数据返回；汇总不冒充逐阶段独立统计。球员名单使用 players，单场或赛季内球员逐场统计使用 games/statistics/players。不要把逐场明细冒充已计算的赛季平均值。
- 竞彩前瞻包括已有特征分析、历史交锋、比赛近况和积分榜；缺一项不隐藏其他项。固定奖金与公司赔率分别展示。奖金历史中胜分差 `w1..w6` 为主胜、`l1..l6` 为客胜，依次为1–5、6–10、11–15、16–20、21–25、26分以上；大小分历史以返回玩法字段为准。

## 回答与错误处理

只给用户需要的比赛、比分、盘口或统计，常规回答不披露内部来源、采集时间、更新频率或缓存诊断。“调用频率”仅指客户每分钟调用限额。数据完整性为“部分”时，按实际缺项简短说明；不能将未准备好的NBA阶段说成没有比赛。

空列表只说明当前没有该范围可查的记录，不推算未公布赛程。null是缺失，真实0保留；没有报价不等于未关联。旧 `/basketball/*` 入口保留已有资料兼容读取，停止新增采集后不承诺更新；新查询统一用v2，不用旧球员入口补新版能力。

400修正参数后再请求；401／403核实Key、权限或到期，不原样重试。429按 `Retry-After`，缺失时至少60秒，最多重试一次；额度耗尽停止。503说明暂不可用，最多退避重试一次。请求未完成不重复发送，不自动轮询、不另找网站补齐，不把历史权限月份当成列表可查日期。
