nba-data

NBA 数据

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

设置

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

which sports-skills || pip install sports-skills

如果 pip install 因 Python 版本错误而失败，则该软件包要求使用 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 密钥。

快速入门

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

sports-skills nba get_scoreboard
sports-skills nba get_standings --season=2025
sports-skills nba get_teams

重要：执行任何查询前

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

• 赛季年份根据系统提示中的 currentDate 推导，切勿硬编码。
• 如果只提供了球队名称，请先调用 get_teams 获取球队 ID，再使用球队专属命令。

选择赛季

根据系统提示中的日期推导当前年份（例如，currentDate: 2026-02-18 → 当前年份为 2026）。

• 如果用户指定了赛季，按指定赛季使用。
• 如果用户说“当前”“本赛季”或未指定赛季：NBA 赛季从 10 月持续到次年 6 月。如果当前月份是 10 月至 12 月，当前赛季年份与当前年份相同。如果当前月份是 1 月至 6 月，当前赛季于前一个日历年开始（将该年份作为赛季年份）。

命令

命令	描述
get_scoreboard	NBA 实时／近期比分
get_standings	按分区查看排名
get_teams	全部 30 支 NBA 球队
get_team_roster	球队完整阵容
get_team_schedule	指定球队的赛程
get_game_summary	详细的技术统计和得分回合
get_leaders	NBA 统计数据领跑者
get_news	NBA 新闻文章
get_play_by_play	比赛完整的逐回合记录
get_win_probability	胜率图表数据
get_schedule	指定日期的比赛（无赛季筛选；参见 get_team_schedule）
get_injuries	所有球队的伤病报告
get_transactions	近期交易
get_futures	未来赛果／赔率市场
get_depth_chart	球队阵容深度图
get_team_stats	球队统计概况
get_player_stats	球员统计概况
find_nba_player	搜索 NBA Stats 球员名录（涵盖所有年代）
get_nbastats_game_log	通过 NBA Stats 获取联盟比赛记录——历史数据可追溯至 1946 年，并包含 NBA 比赛 ID。使用 player_or_team="player" 或 player=<name or id> 获取球员比赛记录
get_nbastats_player_career	通过 NBA Stats 按赛季查看生涯统计数据
get_nbastats_team_stats	通过 NBA Stats 获取联盟球队统计数据——高级评级、比赛节奏、四要素
get_nbastats_shot_chart	通过 NBA Stats 获取每次投篮的球场坐标
get_nbastats_play_by_play	通过 NBA Stats 获取往季带坐标的逐回合记录
get_nbastats_advanced_boxscore	高级技术统计（评级、使用率）
get_live_scoreboard	实时比分。优先使用 cdn.nba.com，备用 ESPN
get_live_boxscore	实时技术统计。优先使用 cdn.nba.com，备用 ESPN
get_live_playbyplay	实时逐回合记录，最新回合优先
get_player_live_stats	今日比赛中单名球员的实时统计数据

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

整理较长的 NBA Stats 结果

get_nbastats_game_log、get_nbastats_team_stats 和 get_nbastats_shot_chart 支持 sort_by、descending、limit 和 fields，因此你可以指定所需的行 和列，而不必获取整个赛季的数据：

# Miami's five highest-scoring games, four columns each
sports-skills nba get_nbastats_game_log --season=2025 --team=MIA \
  --sort_by=pts --limit=5 --fields=wl,pts

• sort_by：要排序的列。数字（以及数字字符串）按数值排序；缺失值始终排在最后。
• descending：true（默认值）或 false；仅在使用 sort_by 时生效。
• limit：正整数，在排序后应用。
• fields：以逗号分隔的保留列列表。以下标识列和 sort_by 列始终保留。
• 未知的 sort_by/fields 列会返回错误，并列出有效列。
• 设置其中任意一项后，响应会增加 total_rows（应用 limit 前符合条件的行数）和 returned_rows。若均未设置，输出保持不变。这些选项会在获取数据后应用，因此不会改变上游请求或其重放记录。

命令	fields 始终保留的列
get_nbastats_game_log	game_id、game_date、team_abbreviation、matchup
get_nbastats_game_log（球员行）	game_id、game_date、player_id、team_abbreviation、matchup
get_nbastats_team_stats	team_id、team_name、team_abbreviation
get_nbastats_shot_chart	game_id、game_date、period

列名采用 NBA.com 的名称，并转换为小写（pts、fg3m、plus_minus、shot_distance）。

同时使用 ESPN 和 NBA Stats

get_nbastats_* 命令读取 stats.nba.com 的数据——这是 ESPN 端点不提供的分析层数据（高级评级、投篮坐标、详细历史记录）。两个来源使用互不相关的 ID 系统：

• 比赛 ID。 NBA Stats 使用 10 位 ID（"0022400061"）；ESPN 使用赛事 ID（"401704627"）。两者没有共同列——请通过比赛日期和两队缩写进行联接。
• 球队缩写。 六支球队的名称拼写不同：ESPN 使用 GS/NO/NY/ SA/UTAH/WSH，NBA 使用 GSW/NOP/NYK/SAS/UTA/WAS。所有 get_nbastats_* 球队筛选器都接受两种拼写，结果行也会同时包含两者 （team_abbreviation 和 team_abbreviation_espn）。
• 球员 ID。 NBA 球员 ID（"203999"）与 ESPN 运动员 ID 互不相关。 使用 find_nba_player 查找姓名；ASCII 拼写也能匹配带重音符号的姓名 （“jokic”可以查找到 “Nikola Jokić”）。
• 赛季。 传入起始年份（season=2024 表示 2024-25 赛季）。也接受 NBA 格式 （"2024-25"）。
• 日期。 比赛日志和投篮图表中的 game_date 格式均为 YYYY-MM-DD。

stats.nba.com 会根据客户端和请求量进行限流：大量突发请求（以及许多数据中心/云 IP）会遭到静默限速，而不是被拒绝。发生这种情况时，命令会快速失败并返回说明性错误——请稍后再试，不要反复发送请求。响应会缓存，基于 ESPN 的命令和 get_live_* 命令不受影响。

示例

示例 1：今日比分 用户说：“今天 NBA 的比分是多少？” 操作：

1. 调用 get_scoreboard() 结果：所有正在进行和近期 NBA 比赛的比分及状态

示例 2：分区排名 用户说：“显示西部联盟排名” 操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_standings(season=<derived_year>)
3. 筛选西部联盟的结果 结果：西部联盟排名表，列出各球队的胜-负、胜率和胜场差

示例 3：球队名单 用户说：“湖人队有哪些球员？” 操作：

1. 调用 get_team_roster(team_id="13") 结果：完整的湖人队名单，包括姓名、位置、球衣号码、身高和体重

示例 4：比赛技术统计 用户说：“显示昨晚凯尔特人比赛的完整技术统计” 操作：

1. 调用 get_scoreboard(date="<yesterday>") 查找 event_id
2. 调用 get_game_summary(event_id=<id>) 获取完整技术统计 结果：完整的技术统计，包括每位球员的数据和得分回合

示例 5：伤病报告 用户说：“湖人队有哪些球员受伤？” 操作：

1. 调用 get_injuries()
2. 筛选洛杉矶湖人队（team_id=13）的结果 结果：湖人队伤病名单，包括球员姓名、位置、状态和伤病类型

示例 6：球员统计数据 用户说：“显示勒布朗本赛季的数据” 操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_player_stats(player_id="1966", season_year=<derived_year>) 结果：按类别列出的赛季数据，包括数值、排名和场均数据

不存在的命令 — 切勿调用

• get_odds / get_betting_odds — 不可用。如需预测市场赔率，请使用 polymarket 或 kalshi skill。
• search_teams — 不存在。请改用 get_teams。
• get_box_score — 不存在。请改用 get_game_summary。
• get_player_ratings — 不存在。请改用 get_player_stats。

如果某条命令未列在上方的命令表中，则该命令不存在。

错误处理

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

1. 静默捕获错误并尝试其他方案
2. 如果用户提供的是球队名称而非 ID，请先使用 get_teams 查找 ID
3. 穷尽其他方案后，再以简洁清晰的消息说明失败

故障排除

错误：找不到 sports-skills 命令 原因：尚未安装软件包 解决方案：运行 pip install sports-skills

错误：通过 ID 找不到球队 原因：使用了错误或过时的 ESPN 球队 ID 解决方案：调用 get_teams 获取当前全部 30 支 NBA 球队及其 ID

错误：未来比赛没有返回数据 原因：ESPN 仅返回已结束或正在进行的比赛数据 解决方案：使用 get_schedule 查看即将进行的比赛详情；get_scoreboard 仅涵盖正在进行或近期的比赛

错误：休赛期 — 记分牌返回 0 场比赛 原因：休赛期（7 月至 9 月）没有安排比赛 解决方案：改用 get_standings 或 get_news；使用 get_schedule 查看赛季何时恢复