Pro-Football-Reference APIpro-football-reference.com ↗
Access NFL schedules, standings, boxscores, play-by-play, and player profiles from Pro-Football-Reference via 7 structured endpoints.
What is the Pro-Football-Reference API?
The Pro-Football-Reference API exposes 7 endpoints covering NFL season schedules, team standings, individual game boxscores, play-by-play data, and player profiles. The get_game_boxscore endpoint returns player-level offensive and defensive stats alongside game metadata including weather, attendance, and Vegas lines. Season coverage spans regular season and playoff games, with player lookup available through search_players.
curl -X GET 'https://api.parse.bot/scraper/68f10b93-1fc8-410d-af5c-7f1b3d6e618d/get_season_schedule?year=2023' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace pro-football-reference-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.pro_football_reference_api import (
ProFootballReference, StatCategory, GameTable
)
pfr = ProFootballReference()
# Get the 2023 season schedule and find a high-scoring game
schedule = pfr.season("2023").schedule()
for game in schedule.games[:5]:
print(game.winner, game.pts_win, "-", game.loser, game.pts_lose)
# Get passing leaders for 2023
leaders = pfr.season("2023").stats(category=StatCategory.PASSING)
for stat in leaders.stats[:3]:
print(stat["name_display"], stat["pass_yds"], "yards", stat["pass_td"], "TDs")
# Get standings
standings = pfr.season("2023").standings()
for team in standings.AFC[:3]:
print(team.team, team.wins, team.losses, team.points_diff)
# Get boxscore for Super Bowl LVIII
box = pfr.game("202402110kan").boxscore()
for t in box.teams:
print(t.name, t.score)
print(box.game_info["vegas_line"])
# Get home drives for the same game
detail = pfr.game("202402110kan").details(table_id=GameTable.HOME_DRIVES)
for row in detail.data[:3]:
print(row["drive_num"], row["end_event"], row["net_yds"])
# Search for a player and get their profile
for player in pfr.players.search(query="Tom Brady"):
print(player.name, player.player_id)
prof = player.profile()
print(prof.name, prof.position, prof.college)
break
Retrieve the full NFL schedule for a given season. Returns every regular-season and playoff game with final scores, yardage totals, turnover counts, and a game_id suitable for drill-down into boxscores and play-by-play. One request per season; no pagination.
| Param | Type | Description |
|---|---|---|
| yearrequired | string | NFL season year as a four-digit string (e.g. '2023' for the 2023-24 season). |
{
"type": "object",
"fields": {
"year": "string, the requested season year",
"games": "array of game objects with week_num, game_date, winner, loser, pts_win, pts_lose, game_id, yards_win, yards_lose, to_win, to_lose"
},
"sample": {
"data": {
"year": "2023",
"games": [
{
"loser": "Kansas City Chiefs",
"to_win": "1",
"winner": "Detroit Lions",
"game_id": "202309070kan",
"pts_win": "21",
"to_lose": "1",
"gametime": "8:20PM",
"pts_lose": "20",
"week_num": "1",
"game_date": "2023-09-07",
"yards_win": "368",
"loser_abbr": "kan",
"yards_lose": "316",
"winner_abbr": "det",
"game_location": "@",
"game_day_of_week": "Thu"
}
]
},
"status": "success"
}
}About the Pro-Football-Reference API
Schedule and Standings
The get_season_schedule endpoint accepts a year parameter and returns a full array of game objects for that NFL season, each with fields like week_num, game_date, winner, loser, pts_win, pts_lose, and a game_id you can pass to other endpoints. The get_season_team_standings endpoint returns conference-split results with each team's wins, losses, points scored, and strength of schedule, organized under AFC and NFC arrays.
Game-Level Data
get_game_boxscore accepts a game_id (available from schedule results) and returns two team objects with scores, arrays of player-level offense and defense stat objects, a scoring_summary, and a game_info object with metadata keys including roof, surface, duration, attendance, and vegas_line. For deeper game analysis, get_game_details accepts the same game_id plus a table_id — accepted values are pbp (play-by-play), home_drives, vis_drives, and drive_chart — returning row-level data arrays appropriate to each table type.
Player Data and Season Stats
search_players takes a name query string and returns an array of matches with name, player_id, and url. A matched player_id feeds into get_player_profile, which returns biographical fields (name, college, position) and career stat arrays — career_passing_stats is present for QBs, with other stat arrays varying by position. The get_season_stats endpoint accepts a year and a category parameter (passing, rushing, receiving, defense, kicking, returns, or scoring) and returns all qualifying players ranked by the primary stat for that category.
The Pro-Football-Reference API is a managed, monitored endpoint for pro-football-reference.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when pro-football-reference.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official pro-football-reference.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a season recap tool that pulls full schedules via
get_season_scheduleand displays weekly results with scores. - Track AFC and NFC playoff picture using
get_season_team_standingsto display win-loss records and strength of schedule. - Power a game analysis dashboard with player-level offense and defense stats from
get_game_boxscore. - Analyze Vegas line accuracy by comparing
vegas_linefromgame_infoagainst finalpts_winandpts_lose. - Build play-by-play timelines using
get_game_detailswithtable_id=pbpfor any historical game. - Look up career passing stats for quarterbacks by combining
search_playerswithget_player_profile. - Generate season statistical leaderboards for rushing or receiving using
get_season_statswith the appropriate category.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Pro-Football-Reference have an official developer API?+
What does `get_game_details` return for play-by-play data?+
table_id=pbp, the endpoint returns a data array where each row object represents one play. Available fields vary by play type and include down, distance, field position, description, and scoring context. Drive-level tables (home_drives, vis_drives, drive_chart) return row objects summarizing each possession.How does `get_season_stats` handle different positions within a single category?+
stats array for each category contains all qualifying players ranked by that category's primary stat. Field names vary by category — for example, passing objects include pass_yds, while rushing objects include rush_yds. Not all fields are present across categories; each player object contains only the fields relevant to the requested category.Does the API cover historical seasons or only recent years?+
year parameter on get_season_schedule, get_season_stats, and get_season_team_standings accepts historical season values, and Pro-Football-Reference itself covers NFL history back to 1920. In practice, the depth of structured data (particularly play-by-play via get_game_details) is richer for modern seasons. There is no explicit lower-bound year enforced by the endpoint, but very early seasons may have sparse fields.