nfl-data

NFL 数据

编写查询前，请查阅 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 密钥。

对于由 nflverse 提供数据支持的命令（get_nflverse_*），请安装 NFL extra：

pip install sports-skills[nfl]

在 Python 3.10 及以上版本中，这会安装 nflreadpy（推荐的后端）和 pyarrow；除赛程外，大多数 nflverse 数据都需要 pyarrow。在 Python 3.9 中，由于 nflreadpy 需要 Python 3.10 及以上版本，因此会改为安装 nfl-data-py。

nfl-data-py 后端是功能受限的备用方案：它无法提供 get_nflverse_team_stats，调用时会返回说明性错误。若要完整使用 nflverse 数据，请使用 Python 3.10 及以上版本。

快速开始

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

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

Python SDK（替代方案）：

from sports_skills import nfl

scores = nfl.get_scoreboard({})
standings = nfl.get_standings({"params": {"season": "2025"}})

重要：执行任何查询前

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

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

选择赛季

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

• 如果用户指定了赛季，按原样使用。
• 如果用户说“当前”“本赛季”或未指定赛季：NFL 赛季从 9 月持续到次年 2 月。如果当前月份为 3 月至 8 月，使用 season = current_year（即将开始的赛季）。如果当前月份为 9 月至次年 2 月，那么若当前月份为 1 月或 2 月，正在进行的赛季始于上一日历年；否则始于当前年份。

命令

命令	说明
get_scoreboard	NFL 实时／近期比分
get_standings	按联盟和分区划分的排名
get_teams	全部 32 支 NFL 球队
get_team_roster	球队完整名单
get_team_schedule	指定球队的赛程；会报告数据覆盖范围限制
get_game_summary	详细技术统计和得分回合
get_leaders	NFL 统计数据领先者
get_news	NFL 新闻文章
get_play_by_play	比赛完整逐档记录
get_win_probability	获胜概率图表数据
get_schedule	某赛季的某一周，或 ESPN 当前时间范围；不会返回整个赛季
get_injuries	伤病报告，身份信息采用数据源原生格式或标记为未解析
get_transactions	近期球员交易
get_futures	未来赛果／赔率市场
get_depth_chart	球队阵容深度图
get_team_stats	球队统计概况
get_player_stats	球员统计概况
get_nflverse_schedule	由 nflverse 提供数据支持的赛程／结果表（包含 espn_event_id）
get_nflverse_weekly_rosters	由 nflverse 提供数据支持的每周球员名单
get_nflverse_player_stats	由 nflverse 提供数据支持的球员统计数据——默认按赛季汇总
get_nflverse_team_stats	由 nflverse 提供数据支持的球队统计数据——默认按赛季汇总
get_nflverse_play_by_play	由 nflverse 提供数据支持的逐档记录
get_fantasy_trending	Sleeper 梦幻橄榄球热门新增／移除球员（热度计数、Sleeper 球员 ID）

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

不要根据 get_schedule 返回空结果就推断球队轮空：请检查其 coverage 块；其完整性始终为 unknown 或 partial，不会是 complete。若要获取球队整个赛季的赛程，请使用 get_team_schedule；仅指定赛季的 get_schedule 请求会被拒绝，因为 ESPN 的记分板会混合并截断相关数据。 伤病记录缺失或身份未解析，不能证明球员身体健康。

Fantasy Trending（Sleeper）

get_fantasy_trending 读取 Sleeper 的公开趋势端点：近期时间窗口内，Sleeper Fantasy 联赛中添加（或移除）人数最多的 NFL 球员。

sports-skills nfl get_fantasy_trending --trend_type=add --lookback_hours=24 --limit=10
sports-skills nfl get_fantasy_trending --trend_type=drop

• trend_type：add（默认）或 drop。lookback_hours：整数小时，范围为 1-168（默认值为 24）。limit：1-100（默认值为 10）。
• count 是 Sleeper 趋势 API 报告的该球员在此时间窗口内被添加或移除的次数。它是人气信号，而非预测、排名或投注优势——报告时请明确说明。
• 球员 ID 为 sleeper_player_id，属于 Sleeper 自己的命名空间——请将其作为标识符使用。它与 ESPN 运动员 ID 或 nflverse GSIS ID 之间没有映射：不要为其附加此类 ID，也不要将与其他提供方的姓名或球队匹配结果说成是已确认的同一名球员。
• name_resolved: false 表示 Sleeper 球员目录中没有该 ID 的姓名。team 和 position 会分别解析，仍可能有值。如果无法获取目录本身，catalog_status 为 unavailable，且 warnings[] 会说明原因；次数和 ID 仍然有效。
• 请根据 source.trending_fetched_at 报告数据的新鲜度。趋势结果会在内存中缓存 5 分钟，且仅限当前进程使用——每次新的 CLI 调用都会重新获取结果。Sleeper 球员目录（精简后仅包含 ID、姓名、球队和位置）也会保存到 $XDG_CACHE_HOME/sports-skills/sleeper/（默认位置为 ~/.cache/...），并在获取后 24 小时内跨进程复用，因为 Sleeper 要求客户端每天最多获取一次。该磁盘缓存尽力而为：如果无法写入，调用仍会成功，下一个进程会再次获取目录。

精简宽幅 nflverse 结果

nflverse 表格很宽：get_nflverse_player_stats 一周的数据约有 960 行、100 多个统计列（数百万个字符）。每个 get_nflverse_* 命令都接受 sort_by、descending、limit 和 fields，让你只获取所需行：

# Week 5 passing leaders, 5 rows, 2 stat columns
sports-skills nfl get_nflverse_player_stats --season=2025 --week=5 --position=QB \
  --sort_by=passing_yards --limit=5 --fields=passing_yards,attempts

• sort_by：用于排序的单个列。数字（和数字字符串）按数值排序；缺失值始终排在最后。
• descending：true（默认值）或 false；仅在使用 sort_by 时生效。
• limit：正整数，在排序后应用。
• fields：以逗号分隔的保留列列表。下方的身份列和 sort_by 列始终保留。
• 未知的 sort_by/fields 列会返回错误，并列出有效列。
• 设置其中任意一项后，响应会添加 total_rows（应用 limit 前符合条件的行数）和 returned_rows。如果这些选项均未设置，输出保持不变。它们会在获取数据后应用，因此不会更改上游请求或其重放条目。
• stats 中的统计列（例如 passing_yards）可以直接寻址；fields 会将 stats 保留为一个仅包含所选键的对象。

命令	fields 始终保留的列
get_nflverse_player_stats	player_id、player_name、position、team、week
get_nflverse_team_stats	team、season、week、game_id
get_nflverse_play_by_play	play_id、game_id
get_nflverse_weekly_rosters	player_id、player_name、team、position
get_nflverse_schedule	game_id、week、away_team、home_team

同时使用 ESPN 和 nflverse

这两个后端使用不同的标识符系统。get_nflverse_schedule 是桥梁：每场赛事都带有 espn_event_id，它就是 ESPN 赛事 ID。

如需将 nflverse 分析数据（EPA、胜率、盘口）与 ESPN 详情（比赛统计、进攻推进）结合起来查看同一场比赛：

1. 调用 get_nflverse_schedule(season=..., week=...)。
2. 从所需赛事中读取 espn_event_id。
3. 将其作为 event_id 传入 get_game_summary、get_play_by_play 或 get_win_probability。

有两项无法自动对应：

• 球队缩写。 ESPN 使用 LAR 和 WSH；nflverse 使用 LA 和 WAS。 get_nflverse_* 函数接受两种缩写并进行转换。反向转换 （nflverse → ESPN）时，请通过 get_teams 查找对应项。
• 球员 ID。 ESPN 球员 ID 和 nflverse GSIS ID（00-0033873） 没有关联，也没有可用的交叉映射表。请改用姓名和球队进行匹配。

赛程行中需要留意的字段：total 是实际得分总和，而 total_line 是博彩大小分盘口。进行市场分析时请使用 total_line。

示例

示例 1：今日比分 用户说：“今天 NFL 的比分如何？” 操作：

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

示例 2：联盟排名 用户说：“给我看看 AFC 排名” 操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_standings(season=<derived_year>)
3. 筛选 AFC 联盟的结果 结果：AFC 排名表，列出每支球队的 W-L-T、PCT、PF、PA

示例 3：球队阵容 用户说：“酋长队阵容里有哪些人？” 操作：

1. 调用 get_team_roster(team_id="12") 结果：完整的酋长队阵容，包含姓名、位置、球衣号码、身高和体重

示例 4：超级碗比赛统计 用户说：“超级碗打得怎么样？” 操作：

1. 调用 get_schedule(week=23) 查找超级碗的 event_id
2. 调用 get_game_summary(event_id=<id>) 获取完整比赛统计 结果：完整比赛统计，包含传球、冲球、接球数据及得分进攻

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

1. 调用 get_injuries()
2. 筛选堪萨斯城酋长队（team_id=12）的结果 结果：酋长队伤病名单，包含球员姓名、位置、状态和伤病类型

示例 6：球员数据 用户说：“给我看看 Patrick Mahomes 本赛季的数据” 操作：

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

示例 7：nflverse 每周阵容 用户说：“给我数据表后端里的第 1 周酋长队阵容” 操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_nflverse_weekly_rosters(season=<derived_year>, week=1, team="KC") 结果：按球队、球员、位置、球衣号码和状态规范化的每周阵容行

示例 8：nflverse 逐档比赛数据 用户说：“调取比尔队第 3 周的逐档比赛数据” 操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_nflverse_play_by_play(season=<derived_year>, week=3, team="BUF") 结果：逐档数据行，包含 game_id、档数/距离、描述、EPA、WP/WPA 和比分状态

示例 9：梦幻橄榄球弃将市场热度 用户说：“这周有哪些球员受到梦幻橄榄球玩家关注并被加入阵容？” 操作：

1. 调用 get_fantasy_trending(trend_type="add", lookback_hours=24, limit=10)
2. 报告姓名、球队、位置和次数，并附上 source.trending_fetched_at 结果：Sleeper 上被加入阵容次数最多的球员；说明这是 Sleeper 用户中的人气情况，而非推荐

不存在的命令——绝不要调用

• get_odds / get_betting_odds——不可用。若要查询预测市场赔率，请使用 polymarket 或 kalshi 技能。
• 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。如果 PyPI 上没有该软件包，请从 GitHub 安装：pip install git+https://github.com/machina-sports/sports-skills.git

错误：nflverse 后端不可用
原因：未安装可选的 NFL 后端扩展
解决方案：安装 sports-skills[nfl]，以启用 nflverse 提供程序（nflreadpy 或兼容性回退方案）

错误：通过 ID 找不到球队
原因：使用了错误或过时的 ESPN 球队 ID
解决方案：调用 get_teams，获取当前 32 支 NFL 球队及其 ID 的完整列表

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

错误：季后赛周数未返回结果
原因：季后赛使用统一周数（19-23），与常规赛不同
解决方案：外卡赛使用第 19 周，分区赛使用第 20 周，联盟冠军赛使用第 21 周，超级碗使用第 23 周