nfl-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NFL Data

NFL 数据工具

Setup

安装配置

Before first use, check if the CLI is available:

bash

which sports-skills || pip install sports-skills

pip install

fails (package not found or Python version error), install from GitHub:

bash

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

The package requires Python 3.10+. If your default Python is older, use a specific version:

bash

python3 --version  # check version

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

bash

which sports-skills || pip install sports-skills

如果

pip install

失败（包未找到或Python版本错误），请从GitHub安装：

bash

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

该包要求Python 3.10及以上版本。如果你的默认Python版本较低，请使用指定版本：

bash

python3 --version  # 检查版本

If < 3.10, try: python3.12 -m pip install sports-skills

如果版本 < 3.10，尝试：python3.12 -m pip install sports-skills

On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

在使用Homebrew的macOS系统上：/opt/homebrew/bin/python3.12 -m pip install sports-skills

No API keys required.

无需API密钥。

Quick Start

快速开始

Prefer the CLI — it avoids Python import path issues:

bash

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

Python SDK (alternative):

python

from sports_skills import nfl

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

推荐使用CLI——可避免Python导入路径问题：

bash

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

Python SDK（替代方案）：

python

from sports_skills import nfl

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

Choosing the Season

赛季选择规则

Derive the current year from the system prompt's date (e.g.,

currentDate: 2026-02-16

→ current year is 2026).

If the user specifies a season, use it as-is.
If the user says "current", "this season", or doesn't specify: The NFL season runs September–February. If the current month is March–August, use
```
season = current_year
```
(upcoming season). If September–February, the active season started in the previous calendar year if you're in Jan/Feb, otherwise current year.
Never hardcode a season. Always derive it from the system date.

从系统提示的日期中提取当前年份（例如：

currentDate: 2026-02-16

→ 当前年份为2026）。

如果用户指定赛季：直接使用用户指定的赛季。
如果用户说“当前”、“本赛季”或未指定：NFL赛季为9月至次年2月。如果当前月份为3-8月，使用
```
season = 当前年份
```
（即将到来的赛季）；如果当前月份为9-2月，若处于1-2月则活跃赛季起始于上一自然年，否则使用当前年份。
禁止硬编码赛季：始终从系统日期推导赛季。

Commands

命令列表

get_scoreboard

Get live/recent NFL scores.

```
date
```
(str, optional): Date in YYYY-MM-DD format
```
week
```
(int, optional): Week number (1-18 regular season, 19-23 postseason)

Returns

events[]

with game info, scores, status, and competitors.

获取NFL实时/近期比分。

```
date
```
（字符串，可选）：日期格式为YYYY-MM-DD
```
week
```
（整数，可选）：周数（常规赛1-18周，季后赛19-23周）

返回包含赛事信息、比分、状态和参赛队伍的

events[]

数组。

get_standings

Get NFL standings by conference and division.

```
season
```
(int, optional): Season year

Returns

groups[]

with AFC/NFC conferences, divisions, and team standings including W-L-T, PCT, PF, PA.

获取NFL分区及联盟排名。

```
season
```
（整数，可选）：赛季年份

返回包含AFC/NFC联盟、分区及球队排名（胜-负-平、胜率、得分、失分）的

groups[]

数组。

get_teams

Get all 32 NFL teams. No parameters.

Returns

teams[]

with id, name, abbreviation, logo, and location.

获取全部32支NFL球队信息，无参数。

返回包含球队ID、名称、缩写、队徽和所在地的

teams[]

数组。

get_team_roster

Get full roster for a team.

```
team_id
```
(str, required): ESPN team ID (e.g., "12" for Broncos)

Returns

athletes[]

with name, position, jersey number, height, weight, experience.

获取指定球队的完整球员名单。

```
team_id
```
（字符串，必填）：ESPN球队ID（例如：Broncos的ID为"12"）

返回包含球员姓名、位置、球衣号码、身高、体重、参赛经验的

athletes[]

数组。

get_team_schedule

Get schedule for a specific team.

```
team_id
```
(str, required): ESPN team ID
```
season
```
(int, optional): Season year

Returns

events[]

with opponent, date, score (if played), and venue.

获取指定球队的赛程。

```
team_id
```
（字符串，必填）：ESPN球队ID
```
season
```
（整数，可选）：赛季年份

返回包含对手、日期、比分（已完赛赛事）和场馆的

events[]

数组。

get_game_summary

Get detailed box score and scoring plays.

```
event_id
```
(str, required): ESPN event ID

Returns

game_info

competitors

boxscore

(passing/rushing/receiving stats),

scoring_plays

, and

leaders

获取赛事详细技术统计和得分记录。

```
event_id
```
（字符串，必填）：ESPN赛事ID

game_info

、

competitors

、

boxscore

（传球/冲球/接球数据）、

scoring_plays

和

leaders

。

get_leaders

Get NFL statistical leaders (passing, rushing, receiving).

```
season
```
(int, optional): Season year

Returns

categories[]

with leader rankings per stat category.

获取NFL数据领跑者（传球、冲球、接球）。

```
season
```
（整数，可选）：赛季年份

返回包含各数据类别排名的

categories[]

数组。

get_news

Get NFL news articles.

```
team_id
```
(str, optional): Filter by team

Returns

articles[]

with headline, description, published date, and link.

获取NFL新闻资讯。

```
team_id
```
（字符串，可选）：按球队筛选

返回包含标题、摘要、发布日期和链接的

articles[]

数组。

get_play_by_play

Get full play-by-play data for a game.

```
event_id
```
(str, required): ESPN event ID

Returns

drives[]

with play-by-play detail including down, distance, yard line, play description, and scoring plays.

获取赛事完整逐次进攻记录。

```
event_id
```
（字符串，必填）：ESPN赛事ID

返回包含进攻回合详情（档数、码数、码线位置、进攻描述、得分记录）的

drives[]

数组。

get_win_probability

Get win probability chart data for a game.

```
event_id
```
(str, required): ESPN event ID

Returns timestamped home/away win probability percentages throughout the game.

获取赛事获胜概率变化数据。

```
event_id
```
（字符串，必填）：ESPN赛事ID

返回赛事全程带时间戳的主客场获胜概率百分比数据。

get_schedule

Get NFL season schedule by week.

```
season
```
(int, optional): Season year
```
week
```
(int, optional): Week number (1-18 regular season, 19-23 postseason)

Returns

events[]

for the specified week/season.

获取NFL赛季周赛程。

```
season
```
（整数，可选）：赛季年份
```
week
```
（整数，可选）：周数（常规赛1-18周，季后赛19-23周）

返回指定周/赛季的

events[]

数组。

get_injuries

Get current NFL injury reports across all teams. No parameters.

Returns

teams[]

with per-team injury lists including player name, position, status (Out/Doubtful/Questionable/Day-To-Day), injury type, and detail.

获取全NFL球队当前伤病报告，无参数。

返回包含各球队伤病名单（球员姓名、位置、状态（缺席/存疑/每日观察）、伤病类型、详情）的

teams[]

数组。

get_transactions

Get recent NFL transactions (trades, signings, waivers).

```
limit
```
(int, optional): Max transactions to return. Defaults to 50.

Returns

transactions[]

with date, team, and description.

获取NFL近期交易信息（转会、签约、弃权）。

```
limit
```
（整数，可选）：返回的最大交易数量，默认50条。

返回包含日期、球队和交易描述的

transactions[]

数组。

get_futures

Get NFL futures/odds markets (Super Bowl winner, MVP, etc.).

```
limit
```
(int, optional): Max entries per market. Defaults to 25.
```
season_year
```
(int, optional): Season year. Defaults to current.

Returns

futures[]

with market name and entries (team/player name + odds value).

获取NFL期货/赔率市场（超级碗冠军、MVP等）。

```
limit
```
（整数，可选）：每个市场返回的最大条目数，默认25条。
```
season_year
```
（整数，可选）：赛季年份，默认为当前赛季。

返回包含市场名称和条目（球队/球员名称+赔率）的

futures[]

数组。

get_depth_chart

Get depth chart for a specific team.

```
team_id
```
(str, required): ESPN team ID

Returns

charts[]

with offense/defense/special teams positions and player depth order.

获取指定球队的深度阵容图。

```
team_id
```
（字符串，必填）：ESPN球队ID

返回包含进攻/防守/特勤组位置及球员深度排序的

charts[]

数组。

get_team_stats

Get full team statistical profile for a season.

```
team_id
```
(str, required): ESPN team ID
```
season_year
```
(int, optional): Season year. Defaults to current.
```
season_type
```
(int, optional): 1=preseason, 2=regular (default), 3=postseason.

Returns

categories[]

(Passing, Rushing, Receiving, etc.) with detailed stats including value, rank, and per-game averages.

获取球队赛季完整统计数据。

```
team_id
```
（字符串，必填）：ESPN球队ID
```
season_year
```
（整数，可选）：赛季年份，默认为当前赛季。
```
season_type
```
（整数，可选）：1=季前赛，2=常规赛（默认），3=季后赛。

返回包含各数据类别（传球、冲球、接球等）的

categories[]

数组，包含详细数据、排名和场均数据。

get_player_stats

Get full player statistical profile for a season.

```
player_id
```
(str, required): ESPN athlete ID
```
season_year
```
(int, optional): Season year. Defaults to current.
```
season_type
```
(int, optional): 1=preseason, 2=regular (default), 3=postseason.

Returns

categories[]

with detailed stats including value, rank, and per-game averages.

获取球员赛季完整统计数据。

```
player_id
```
（字符串，必填）：ESPN球员ID
```
season_year
```
（整数，可选）：赛季年份，默认为当前赛季。
```
season_type
```
（整数，可选）：1=季前赛，2=常规赛（默认），3=季后赛。

返回包含各数据类别的

categories[]

数组，包含详细数据、排名和场均数据。

Team IDs (Common)

常用球队ID

Team	ID	Team	ID
Cardinals	22	Rams	14
Falcons	1	Ravens	33
Bills	2	Bears	3
Panthers	29	Bengals	4
Cowboys	6	Browns	5
Broncos	7	Lions	8
Packers	9	Texans	34
Colts	11	Jaguars	30
Chiefs	12	Raiders	13
Chargers	24	Dolphins	15
Vikings	16	Patriots	17
Saints	18	Giants	19
Jets	20	Eagles	21
Steelers	23	49ers	25
Seahawks	26	Buccaneers	27
Titans	10	Commanders	28

球队	ID	球队	ID
Cardinals	22	Rams	14
Falcons	1	Ravens	33
Bills	2	Bears	3
Panthers	29	Bengals	4
Cowboys	6	Browns	5
Broncos	7	Lions	8
Packers	9	Texans	34
Colts	11	Jaguars	30
Chiefs	12	Raiders	13
Chargers	24	Dolphins	15
Vikings	16	Patriots	17
Saints	18	Giants	19
Jets	20	Eagles	21
Steelers	23	49ers	25
Seahawks	26	Buccaneers	27
Titans	10	Commanders	28

Examples

使用示例

User: "What are today's NFL scores?"

bash

sports-skills nfl get_scoreboard

User: "Show me the AFC standings"

bash

sports-skills nfl get_standings --season=2025

Then filter results for AFC conference.

User: "Who's on the Chiefs roster?"

bash

sports-skills nfl get_team_roster --team_id=12

User: "How did the Super Bowl go?"

Find the event_id from
```
get_scoreboard --week=23
```
(Super Bowl = week 23)
Call
```
get_game_summary --event_id=<id>
```
for full box score Alternatively, use
```
get_schedule --week=23
```
to find the event.

User: "Who's injured on the Chiefs?"

bash

sports-skills nfl get_injuries

Then filter results for Kansas City Chiefs (team_id=12).

User: "Show me the Chiefs depth chart"

bash

sports-skills nfl get_depth_chart --team_id=12

User: "What are the Super Bowl odds?"

bash

sports-skills nfl get_futures --limit=10

User: "Show me Patrick Mahomes' stats this season"

bash

sports-skills nfl get_player_stats --player_id=3139477

用户：“今天的NFL比分是多少？”

bash

sports-skills nfl get_scoreboard

用户：“展示AFC联盟排名”

bash

sports-skills nfl get_standings --season=2025

然后筛选AFC联盟的结果。

用户：“Chiefs的球员名单有哪些？”

bash

sports-skills nfl get_team_roster --team_id=12

用户：“超级碗的结果如何？”

从
```
get_scoreboard --week=23
```
中获取event_id（超级碗为第23周）
调用
```
get_game_summary --event_id=<id>
```
获取完整技术统计或者使用
```
get_schedule --week=23
```
查找赛事ID。

用户：“Chiefs有哪些球员受伤？”

bash

sports-skills nfl get_injuries

然后筛选堪萨斯城酋长队（team_id=12）的结果。

用户：“展示Chiefs的深度阵容图”

bash

sports-skills nfl get_depth_chart --team_id=12

用户：“超级碗的赔率是多少？”

bash

sports-skills nfl get_futures --limit=10

用户：“展示Patrick Mahomes本赛季的数据”

bash

sports-skills nfl get_player_stats --player_id=3139477

Error Handling

错误处理

When a command fails, do not surface raw errors to the user. Instead:

Catch silently and try alternatives
If team name given instead of ID, use
```
get_teams
```
to find the ID first
Only report failure with a clean message after exhausting alternatives

当命令执行失败时，请勿向用户暴露原始错误信息，请遵循以下步骤：

静默捕获错误并尝试替代方案
如果用户提供的是球队名称而非ID，先使用
```
get_teams
```
查找对应ID
仅在穷尽所有替代方案后，向用户展示简洁的失败提示

Troubleshooting

故障排除

sports-skills
command not found: Run

pip install sports-skills

. If the package is not found on PyPI, install from GitHub:

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

Team not found: Use
```
get_teams
```
to list all teams and find the correct ID
No data for future games: ESPN only returns data for completed or in-progress games
Week numbers: Regular season is weeks 1-18. Postseason uses unified numbering: Wild Card=19, Divisional=20, Conference Championship=21, Pro Bowl=22, Super Bowl=23. The connector translates these to ESPN's internal
```
seasontype=3
```
automatically.
Team schedule includes postseason:
```
get_team_schedule
```
returns both regular-season and postseason games.

sports-skills
命令未找到：运行

pip install sports-skills

。如果PyPI上未找到该包，从GitHub安装：

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

球队未找到：使用
```
get_teams
```
列出所有球队并查找正确ID
未来赛事无数据：ESPN仅返回已完赛或进行中赛事的数据
周数说明：常规赛为1-18周。季后赛使用统一编号：外卡赛=19，分区赛=20，联盟冠军赛=21，职业碗=22，超级碗=23。工具会自动将这些编号转换为ESPN内部的
```
seasontype=3
```
参数。
球队赛程包含季后赛：
```
get_team_schedule
```
会同时返回常规赛和季后赛赛事。