volleyball-data

排球数据（Nevobo — 荷兰排球）

编写查询前，请查阅 references/api-reference.md，了解端点、ID 约定和数据结构。

设置

首次使用前，请检查 CLI 是否可用：

which sports-skills || pip install sports-skills

如果 pip install 失败（找不到软件包或 Python 版本错误），请从 GitHub 安装：

pip install git+https://github.com/machina-sports/sports-skills.git

此软件包要求 Python 3.10+。如果默认 Python 版本较旧，请指定版本：

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

无需 API 密钥。所有数据均来自 Nevobo（Nederlandse Volleybalbond）开放 API。

快速开始

优先使用 CLI — 可避免 Python 导入路径问题：

sports-skills volleyball get_competitions
sports-skills volleyball get_standings --competition_id=nevobo-eredivisie-heren
sports-skills volleyball get_results --competition_id=nevobo-eredivisie-dames
sports-skills volleyball get_schedule --competition_id=nevobo-topdivisie-heren-a

Python SDK（替代方案）：

from sports_skills import volleyball

standings = volleyball.get_standings(competition_id="nevobo-eredivisie-heren")
results = volleyball.get_results(competition_id="nevobo-eredivisie-dames")

重要：执行任何查询前

重要：调用任何数据端点前，请确认：

• competition_id 使用 references/competition-ids.md 中的有效值 — 切勿猜测。
• 对于特定俱乐部的命令，请确保你有有效的 Nevobo club_id（使用 get_clubs 查找 — 查看 organisatiecode 字段）。
• 不要猜测俱乐部 ID 或赛事 ID。使用 get_competitions 或 get_clubs 查找。

competition_id 参数

荷兰排球前三个级别的 8 个联赛已预先配置。competition_id 遵循以下模式：nevobo-<league>-<gender>[-<pool>]：

• Eredivisie（第 1 级，8 支队伍）：nevobo-eredivisie-heren、nevobo-eredivisie-dames
• Topdivisie（第 2 级，每组 10 支队伍）：nevobo-topdivisie-heren-a、nevobo-topdivisie-heren-b、nevobo-topdivisie-dames-a、nevobo-topdivisie-dames-b
• Superdivisie（第 3 级，10 支队伍）：nevobo-superdivisie-heren、nevobo-superdivisie-dames

对于较低级别（1e/2e/3e Divisie、地区联赛、青少年、沙滩排球 — 6,400 多个小组），请使用 get_poules 查找。

完整参考资料（含队伍数量和荷兰排球金字塔）请参阅 references/competition-ids.md。

命令

命令	描述
get_competitions	列出所有可用赛事和联赛
get_standings	联赛排名表（排名、队伍、比赛场次、积分）
get_schedule	即将进行的比赛（队伍、场馆、日期）
get_results	比赛结果（比分、每局比分）
get_clubs	列出排球俱乐部（名称、城市、省份）
get_club_schedule	俱乐部所有队伍即将进行的比赛
get_club_results	俱乐部所有队伍的比赛结果
get_poules	浏览 Nevobo 小组（用于查找较低级别联赛）
get_tournaments	锦标赛日历
get_news	协会新闻

完整参数列表和返回结构请参阅 references/api-reference.md。

仅限当前赛季。 Nevobo 会移除往季的小组和导出数据，因此 get_standings、get_schedule 和 get_results 始终涵盖当前赛季。其可选参数 season（"2026-2027" 或 2026）在指定其他赛季时会返回明确错误。尚无日期的比赛会显示 date: null；已取消的比赛会显示 status: "vervallen"。

示例

示例 1：Eredivisie 排名 用户说：“荷兰排球当前的排名是什么？” 操作：

1. 为男子组调用 get_standings(competition_id="nevobo-eredivisie-heren")
2. 为女子组调用 get_standings(competition_id="nevobo-eredivisie-dames") 结果：联赛排名表，包含名次、球队名称、已赛场次和积分

示例 2：近期比赛结果 用户说：“给我看看近期的 Eredivisie 排球比赛结果” 操作：

1. 调用 get_results(competition_id="nevobo-eredivisie-heren") 结果：比赛结果，包含主队/客队、比赛比分（例如 "3-1"）和每局比分（例如 ["25-21", "25-18", "21-25", "25-20"]）

示例 3：俱乐部赛程 用户说：“LSV 接下来有哪些比赛？” 操作：

1. 调用 get_clubs(limit=10)，找到 LSV 的 organisatiecode（CKL5C67）
2. 调用 get_club_schedule(club_id="CKL5C67") 结果：LSV 所有球队的后续比赛，包含场馆和日期

示例 4：第二级联赛排名 用户说：“给我看看 Topdivisie 的排名” 操作：

1. 为男子 A 组调用 get_standings(competition_id="nevobo-topdivisie-heren-a")
2. 为男子 B 组调用 get_standings(competition_id="nevobo-topdivisie-heren-b") 结果：两个分组的排名表，每组各有 10 支球队

示例 5：探索较低级别联赛 用户说：“荷兰排球有哪些级别的联赛？” 操作：

1. 调用 get_poules(regio="nationale-competitie", limit=20) 结果：国家级分组列表，包括 1e/2e/3e Divisie，以及相应的缩写和说明

不存在的命令——切勿调用

• get_scoreboard — 不存在。近期比赛结果请使用 get_results。
• get_rankings — 不存在。排球联赛排名请使用 get_standings。
• get_team_roster — 不存在。俱乐部信息请使用 get_clubs。
• get_player_info — 不存在。此 API 不提供球员级别的数据。

如果某个命令未列在上方的 Commands 表中，该命令就不存在。

错误处理

命令失败时，不要向用户显示原始错误。请改为：

1. 静默捕获错误并尝试其他方法
2. 如果提供的是俱乐部名称而非 ID，先使用 get_clubs 查找 organisatiecode
3. 如果 competition_id 未返回数据，使用 get_competitions 验证可用联赛
4. 尝尽其他方法后，才用清晰易懂的消息报告失败

故障排除

错误：找不到 sports-skills 命令 原因：未安装软件包 解决方案：运行 pip install sports-skills。如果 PyPI 上没有该软件包，请从 GitHub 安装：pip install git+https://github.com/machina-sports/sports-skills.git

错误：排名返回空列表 原因：该项赛事的常规赛阶段可能已结束，或者赛季尚未开始 解决方案：使用 get_results 查看近期比赛结果，或使用 get_poules 查找当前活跃分组的路径

错误：赛程返回 0 场比赛 原因：该分组的赛事阶段已结束，且没有安排更多比赛 解决方案：这在赛季阶段之间是正常情况。请查看其他联赛（Topdivisie/Superdivisie 可能仍在进行）

错误：俱乐部赛程/比赛结果返回错误 原因：club_id 可能不正确 解决方案：使用 get_clubs 查找有效的俱乐部 ID（organisatiecode 字段，例如 "CKL5C67"）

错误：连接错误或超时 原因：Nevobo API 可能暂时不可用 解决方案：稍等片刻后重试。该 API 公开且无需身份验证，但可能会短暂中断