nfl — Python SDK for ESPN's NFL API

A small, typed Python client for the public (but undocumented) JSON API behind ESPN's NFL pages. No API key or account is needed.

• Typed dataclasses for teams, rosters, scoreboards, game summaries (boxscore, drives, scoring plays, leaders), standings, athletes and news — with .raw on every model for anything not modelled.
• Retries on 5xx responses, optional rate limiting, and a small exception hierarchy (NFLError, NFLNotFoundError, NFLRateLimitError, ...).
• Depends only on requests and urllib3. Python 3.10+.

ESPN publishes no developer program or documentation for this API. It has been stable, but it can change without notice.

Install

pip install nfl-espn
# or, from a checkout:
pip install -e .

Quick start

from nfl import NFLClient

client = NFLClient()

# A week's scores
for game in client.scoreboard.get(week=1, season=2026).games:
    print(f"{game.short_name:12} {game.score_display:8} [{game.status.short_detail}]")

# Division standings
standings = client.standings.get(season=2026)
for entry in standings.get_division("AFC West").entries:
    print(f"{entry.team_display_name:25} {entry.overall}")

# A team and its roster
broncos = client.teams.get(client.teams.BRONCOS)
print(broncos.display_name, broncos.record_str, broncos.standing_summary)
for player in client.teams.roster(client.teams.BRONCOS)[:5]:
    print(f"#{player.jersey or '??'}  {player.full_name}  {player.position_abbreviation}")

See examples/lions.py for a fuller example.

Choosing a season

A season is named by the year it starts. season=2026 is the 2026-27 season: September 2026 through the Super Bowl in February 2027. The playoffs played in January 2027 are season=2026, not 2027.

Leave season out and you get the current season.

games, athletes, news and teams.get/roster take no season: a game is looked up by its id (from a scoreboard or schedule), and the rest are always current.

client.scoreboard.get(week=1, season=2026)      # opening week, 2026-27
client.scoreboard.playoffs(season=2025)         # the playoffs played Jan-Feb 2026
client.standings.get(season=2025)               # final 2025 standings
client.standings.get()                          # the current season so far

Endpoints

Full reference: docs/.

Things the API does that you might not expect

Tests

pip install -e '.[dev]'
python3 -m pytest tests -q

The tests are integration tests against the live API (no mocks), so they need network access.

Disclaimer

Not affiliated with or endorsed by ESPN or the NFL. The data belongs to them; this library only makes the requests.

License

GNU General Public License v3.0 only (GPL-3.0-only) — see LICENSE.