pro-football-reference.com APIpro-football-reference.com ↗
Access NFL schedules, standings, boxscores, play-by-play, and player profiles from Pro-Football-Reference via 7 structured endpoints.
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'
Get the full NFL schedule for a given season, including game results, scores, and boxscore links for all regular season and playoff games.
| Param | Type | Description |
|---|---|---|
| yearrequired | string | NFL season year (e.g. '2023'). |
{
"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, and other metadata"
},
"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",
"boxscore_word": "boxscore",
"game_location": "@",
"game_day_of_week": "Thu"
}
]
},
"status": "success"
}
}About the pro-football-reference.com 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.
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.
- 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 | 250 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.