Skip to content

Instantly share code, notes, and snippets.

@nntrn

nntrn/espn-api-list.md

Last active December 26, 2024 17:54
Show Gist options
  • Save nntrn/ee26cb2a0716de0947a0a4e9a157bc1c to your computer and use it in GitHub Desktop.
Save nntrn/ee26cb2a0716de0947a0a4e9a157bc1c to your computer and use it in GitHub Desktop.
Download ZIP
List of nfl api endpoints from espn
Raw
espn-api.md

ESPN API ENDPOINTS

This page is limited to NFL endpoints but can be refashioned for other leagues (i.e. /sports/football/leagues/nfl/ => /sports/baseball/leagues/mlb/)

NFL ENDPOINTS

Leagues: sports.core.api.espn.com/v2/sports/football/leagues/nfl

Athletes: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/athletes/:athlete_id

Teams: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/teams

Team: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/teams/:team_id

Plays: sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/:game_id/competitions/:game_id/plays?limit=300

Depth charts: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/teams/:team_id/depthcharts

Whitelist dates: sports.core.api.espn.com/v2/sports/football/leagues/nfl/calendar/whitelist

Season: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year

Week: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2020/types/:season_type/weeks/:week

All weeks sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/types/:season_type/weeks

Odds

Win probabilities sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/:game_id/competitions/:game_id/probabilities*?limit=200*

Odds: sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/:game_id/competitions/:game_id/odds

Against-the-spread: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/types/2/teams/:team_id/ats

Futures: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/futures

Head-to-head (game): sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/:game_id/competitions/:game_id/odds/:bet_provider_id/head-to-heads

Odds records: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/types/0/teams/:team_id/odds-records

Odds history - Game: sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401249063/competitions/401249063/odds/:bet_provider_id/history/0/movement?limit=100

Odds history - Team: sports.core.api.espn.com/v2/sports/football/leagues/nfl/teams/:team_id/odds/:bet_provider_id/past-performances?limit=200

bet_provider_id:

  • 38: Caesars
  • 31: William Hill
  • 41: SugarHouse
  • 36: Unibet
  • 2000: Bet 365
  • 25: Westgate
  • 45: William Hill (New Jersey)
  • 1001: accuscore
  • 1004: consensus
  • 1003: numberfire
  • 1002: teamrankings

Stats

Positions (enum): sports.core.api.espn.com/v2/sports/football/leagues/nfl/positions*?limit=100*

QBR Weekly/Game stats: sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2020/types/2/weeks/:week_num/qbr/10000

List of games via date-range: site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?limit=1000&dates=20200901-20210228

  • date range cannot exceed 13 months
  • dates can also be = YYYYMMDD, YYYY
  • add &1577413600 at the end for overriding the cache

Athlete

all active athletes: sports.core.api.espn.com/v2/sports/football/leagues/nfl/athletes?active=true

site.web.api.espn.com/apis/common/v3/sports/football/nfl/athletes/:athlete_id

site.web.api.espn.com/apis/common/v3/sports/football/nfl/athletes/:athlete_id/splits?season=2020

site.web.api.espn.com/apis/common/v3/sports/football/nfl/athletes/:athlete_id/gamelog

site.web.api.espn.com/apis/common/v3/sports/football/nfl/athletes/:athlete_id/stats

site.web.api.espn.com/apis/common/v3/sports/football/nfl/athletes/:athlete_id/bio

site.web.api.espn.com/apis/common/v3/sports/football/nfl/athletes/:athlete_id/overview

sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/types/2/athletes/:athlete_id/statistics

sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2020/types/2/athletes/:athlete_id/projections

sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/:game_id/competitions/:game_id/competitors/:team_id/roster/:athlete_id/statistics/0

Team

site.api.espn.com/apis/site/v2/sports/football/nfl/teams

site.api.espn.com/apis/site/v2/sports/football/nfl/teams/:team_id

site.api.espn.com/apis/site/v2/sports/football/nfl/teams/:team_id/roster

site.api.espn.com/apis/site/v2/sports/football/nfl/teams/:team_id/schedule*{?season,seasontype}*

sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2020/types/2/teams/:team_id/statistics

sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2020/teams/:team_id/projection

sports.core.api.espn.com/v2/sports/football/leagues/nfl/teams/:team_id/odds/1002/past-performances?limit=140

sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/:game_id/competitions/:game_id/competitors/:team_id/roster?season=YYYY

site.api.espn.com/apis/site/v2/sports/football/nfl/teams/3?enable=roster

sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/teams/:team_id/projection

sports.core.api.espn.com/v2/sports/football/leagues/nfl/teams/:team_id/odds/:bet_provider_id/past-performances?limit=200

Leaders

site.api.espn.com/apis/site/v3/sports/football/nfl/leaders*{?season,seasontype}*

Scoreboard

site.api.espn.com/apis/site/v2/sports/football/college-football**/scoreboard**{?dates=YYYYMMDD}

Search

site.web.api.espn.com/apis/common/v3/search?region=us&lang=en&query=nfl&limit=5&mode=prefix

site.web.api.espn.com/apis/common/v3/search

site.web.api.espn.com/apis/fantasy/v2/games/ffl/games?dates={YYYYMMDD}-{YYYYMMDD}&pbpOnly=true

News

site.api.espn.com/apis/site/v2/sports/football/nfl/news

Header

site.web.api.espn.com/apis/v2/scoreboard/header?sport=football&league=nfl

Fantasy

fantasy.espn.com/apis/v3/games/ffl/seasons/2019/segments/0/leagues/1241838?view=mDraftDetail&view=mLiveScoring&view=mMatchupScore&view=mPendingTransactions&view=mPositionalRatings&view=mSettings&view=mTeam&view=modular&view=mNav

seasontype

  • year - Integer year in which the season started.
  • type - Integer corresponding to the season type (1 = preseason, 2 = regular season, 3 = postseason).
  • description - String representation of the season type. For example, "regular" for season type 2.

Misc

sports.core.api.espn.com/v2/sports/football/leagues/nfl/athletes/2/statisticslog

sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/teams/:team_id

sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/:year/teams/:team_id/athletes?limit=200

Resources

Raw
extending-espn-api.md

ESPN Leagues API List

Starting endpoint: https://sports.core.api.espn.com/v2/sports

BASEBALL

BASKETBALL

FOOTBALL

GOLF

HOCKEY

LACROSSE

MMA

RACING

RUGBY

RUGBY-LEAGUE

SOCCER

VOLLEYBALL

AUSTRALIAN-FOOTBALL

TENNIS

WATER-POLO

FIELD-HOCKEY

@JimNayzium
Copy link

Does anyone have an exhaustive list of the play "types" with ids that ESPN drive or plays items has? Here is what I have found in the first two games i have manuallyl gone through.

[ { "id": "53", "text": "Kickoff", "abbreviation": "K" }, { "id": "5", "text": "Rush", "abbreviation": "RUSH" }, { "id": "24", "text": "Pass Reception", "abbreviation": "REC" }, { "id": "3", "text": "Pass Incompletion" }, { "id": "21", "text": "Timeout", "abbreviation": "TO" }, { "id": "74", "text": "Official Timeout", "abbreviation": "Off TO" }, { "id": "52", "text": "Punt", "abbreviation": "PUNT" }, { "id": "68", "text": "Rushing Touchdown", "abbreviation": "TD" }, { "id": "61", "text": "Extra Point Good", "abbreviation": "Extra Point Good", "value": 1 }, { "id": "2", "text": "End Period", "abbreviation": "EP" }, { "id": "7", "text": "Sack" }, { "id": "59", "text": "Field Goal Good", "abbreviation": "FG" }, { "id": "8", "text": "Penalty", "abbreviation": "PEN" }, { "id": "67", "text": "Passing Touchdown", "abbreviation": "TD" }, { "id": "75", "text": "Two-minute warning", "abbreviation": "2Min Warn" }, { "id": "65", "text": "End of Half", "abbreviation": "EH" }, { "id": "12", "text": "Kickoff Return (Offense)" }, { "id": "9", "text": "Fumble Recovery (Own)" }, { "id": "66", "text": "End of Game", "abbreviation": "EG" }, { "id": "29", "text": "Fumble Recovery (Opponent)" }, { "id": "26", "text": "Pass Interception Return", "abbreviation": "INTR" }, { "id": "29", "text": "Fumble Recovery (Opponent)" }, { "id": "52", "text": "Punt", "abbreviation": "PUNT" } ]

@ryanbuckner
Copy link

Can you share the API where you saw these so we can try to dig?

@JimNayzium
Copy link

JimNayzium commented Aug 22, 2024 •
edited
Loading

Sure! I just went to one of the links above:
https://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401249063/competitions/401249063/plays?limit=300

Also, Here is an updated list, as GitHut Co-Pilot auto filled a few of them and I uncommented them if I was able to confirm then on an end point. I clicked the above one as well as few others like events or similar. Anything I could find that showed individual plays.
`

[
// { "id": "1", "text": "Period Start", "abbreviation": "PS" },
{ "id": "2", "text": "End Period", "abbreviation": "EP" },
{ "id": "3", "text": "Pass Incompletion" },
// { "id": "4", "text": null },
{ "id": "5", "text": "Rush", "abbreviation": "RUSH" },
// { "id": "6", "text": null },
{ "id": "7", "text": "Sack" },
{ "id": "8", "text": "Penalty", "abbreviation": "PEN" },
{ "id": "9", "text": "Fumble Recovery (Own)" },
// { "id": "10", "text": null },
// { "id": "11", "text": null },
{ "id": "12", "text": "Kickoff Return (Offense)" },
// { "id": "13", "text": null },
// { "id": "14", "text": null },
// { "id": "15", "text": null },
// { "id": "16", "text": null },
// { "id": "17", "text": null },
// { "id": "18", "text": null },
// { "id": "19", "text": null },
// { "id": "20", "text": null },

{ "id": "21", "text": "Timeout", "abbreviation": "TO" },
// { "id": "22", "text": null },
// { "id": "23", "text": null },
{ "id": "24", "text": "Pass Reception", "abbreviation": "REC" },
// { "id": "25", "text": null },
{ "id": "26", "text": "Pass Interception Return", "abbreviation": "INTR" },
// { "id": "27", "text": null },
// { "id": "28", "text": null },
{ "id": "29", "text": "Fumble Recovery (Opponent)" },
// { "id": "30", "text": null },
// { "id": "31", "text": null },
// { "id": "32", "text": null },
// { "id": "33", "text": null },
// { "id": "34", "text": null },
// { "id": "35", "text": null },
// { "id": "36", "text": null },
// { "id": "37", "text": null },
// { "id": "38", "text": null },
// { "id": "39", "text": null },
// { "id": "40", "text": null },
// { "id": "41", "text": null },
// { "id": "42", "text": null },
// { "id": "43", "text": null },
// { "id": "44", "text": null },
// { "id": "45", "text": null },
// { "id": "46", "text": null },
// { "id": "47", "text": null },
// { "id": "48", "text": null },
// { "id": "49", "text": null },
// { "id": "50", "text": null },
// { "id": "51", "text": null },
{ "id": "52", "text": "Punt", "abbreviation": "PUNT" },
{ "id": "53", "text": "Kickoff", "abbreviation": "K" },
// { "id": "54", "text": null },
// { "id": "55", "text": null },
// { "id": "56", "text": null },
// { "id": "57", "text": null },
// { "id": "58", "text": null },
{ "id": "59", "text": "Field Goal Good", "abbreviation": "FG" },
{ "id": "60", "text": "Field Goal Missed", "abbreviation": "FG Miss" },
{ "id": "61", "text": "Extra Point Good", "abbreviation": "Extra Point Good", "value": 1 },
// { "id": "62", "text": "Extra Point Missed", "abbreviation": "Extra Point Miss" },
// { "id": "63", "text": "Safety", "abbreviation": "SAF" },
// { "id": "64", "text": "Safety Free Kick", "abbreviation": "SAF FK" },
{ "id": "65", "text": "End of Half", "abbreviation": "EH" },
{ "id": "66", "text": "End of Game", "abbreviation": "EG" },
{ "id": "67", "text": "Passing Touchdown", "abbreviation": "TD" },
{ "id": "68", "text": "Rushing Touchdown", "abbreviation": "TD" },
// { "id": "69", "text": null },
{ "id": "70", "text": "Coin Toss" },
// { "id": "71", "text": null },
// { "id": "72", "text": null },
// { "id": "73", "text": null },
{ "id": "74", "text": "Official Timeout", "abbreviation": "Off TO" },
{ "id": "75", "text": "Two-minute warning", "abbreviation": "2Min Warn" }

]
`

@ryanbuckner
Copy link

ryanbuckner commented Aug 23, 2024 •
edited
Loading

What happens if we exceed 2500 calls per day? Do we get our IP banned for good? Or do responses just not work after that for the day?

You'll receive an error on the next calls until your quota resets. I don't think it's as cut and dry as 2500 per day. I think there are restrictions on frequency too. I've had errors come back saying I've hit a limit and then waited an hour or two to rerun successfully.

The APIs are not supported so I think the 2500 number is a guess.

@JimNayzium
Copy link

I appreciate your input and experience! Thanks for helping me.
In your opinion if I was attempting to generate some live-play-by-play data, and of course would be pulling up to 16 games on any given Sunday depending on the date of the game, what frequency do you think would be wise to go under the block-radar? 5 minutes? 3 minutes?

I realize this is your best guess and won't hold you to anything!!

@ryanbuckner
Copy link

ryanbuckner commented Aug 24, 2024 via email

@JimNayzium
Copy link

Thanks man!
Here is an updated list of play_type_ids I have found so far in preseason and verified.
(Some of the abbreviations are not verified as some of them do not carry abbreviations so I use my own. Also, espn uses the full word "abbreviation" not "abv")

But the numbers on the indexes as the play_type_id are verified for these:

"PLAY_TYPE_IDS" => [ 2 => ["text" => "End Period", "abv" => "EP"], 3 => ["text" => "Pass Incompletion", "abv" => "Pass Inc"], 5 => ["text" => "Rush", "abv" => "RUSH"], 7 => ["text" => "Sack", "abv" => "SACK"], 8 => ["text" => "Penalty", "abv" => "PEN"], 9 => ["text" => "Fumble Recovery (Own)", "abv" => "Fumble Rec (Own)"], 12 => ["text" => "Kickoff Return (Offense)", "abv" => "KOR"], 16 => ["text" => "Two Point Rush", "abv" => "Two Point Rush"], 21 => ["text" => "Timeout", "abv" => "TO"], 24 => ["text" => "Pass Reception", "abv" => "REC"], 26 => ["text" => "Pass Interception Return", "abv" => "INTR"], 29 => ["text" => "Fumble Recovery (Opponent)", "abv" => "Fumble Rec (Opp)"], 36 => ["text" => "Interception Return Touchdown", "abv" => "TD"], 40 => ["text" => "Missed Field Goal Return", "abv" => "AFG"], 52 => ["text" => "Punt", "abv" => "PUNT"], 53 => ["text" => "Kickoff", "abv" => "K"], 59 => ["text" => "Field Goal Good", "abv" => "FG"], 60 => ["text" => "Field Goal Missed", "abv" => "FG Miss"], 61 => ["text" => "Extra Point Good", "abv" => "Extra Point Good", "value" => 1], 65 => ["text" => "End of Half", "abv" => "EH"], 66 => ["text" => "End of Game", "abv" => "EG"], 67 => ["text" => "Passing Touchdown", "abv" => "TD"], 68 => ["text" => "Rushing Touchdown", "abv" => "TD"], 70 => ["text" => "Coin Toss", "abv" => "CT"], 74 => ["text" => "Official Timeout", "abv" => "Off TO"], 75 => ["text" => "Two-minute warning", "abv" => "2Min Warn"] ],

@chriscampana
Copy link

Does ESPN use a different API call for their schedule (eg https://www.espn.com/college-football/schedule) page vs scoreboard (eg https://www.espn.com/college-football/scoreboard) page? What the heck is the difference in those pages anyways ?

What I really want is all college football games by week. When I enter the week, I only get top 25 (ie http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?week=4) but if I enter exact date I get all the games (ie http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=20240907)

@BarryLaminack
Copy link

Does ESPN use a different API call for their schedule (eg https://www.espn.com/college-football/schedule) page vs scoreboard (eg https://www.espn.com/college-football/scoreboard) page? What the heck is the difference in those pages anyways ?

What I really want is all college football games by week. When I enter the week, I only get top 25 (ie http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?week=4) but if I enter exact date I get all the games (ie http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=20240907)

try adding:

&groups=80

to the end of your path.
80 is the "group" or "conference" designation for "FBS", or all the FBS games.

Here's a list of all the "group" or "conference" IDs:
Default = Top 25
80 = FBS (I-A)
81 = FCS (I-AA)
1 = ACC
4 = Big 12
5 = Big Ten
8 = SEC
9 = Pac 12
12 = CUSA
15 = MAC
17 = Mountain West
18 = FBS Indep
20 = Big Sky
21 = MVFC
22 = Ivy
24 = MEAC
25 = NEC
27 = Patriot
28 = Pioneer
29 = Southern
30 = Southland
31 = SWAC
32 = FCS Indep.
35 = DIV II/III
37 = Sun Belt
48 = CAA
151 = American
177 = UAC
179 = BIg South-0VC

So this path for example:
https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?week=2&groups=80
returns all the FBS games for week 2

and this path:
https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?week=2&groups=5
returns all the Big Ten games for week 2

@JimNayzium
Copy link

JimNayzium commented Sep 8, 2024 •
edited
Loading

Here are the play types I have confirmed so far in addition to the above.

$confirmedWithJavascript = [ 2 => ["text" => 'End Period', "abv" => 'EP'], 3 => ["text" => 'Pass Incompletion', "abv" => null], 5 => ["text" => 'Rush', "abv" => 'RUSH'], 7 => ["text" => 'Sack', "abv" => null], 8 => ["text" => 'Penalty', "abv" => 'PEN'], 9 => ["text" => 'Fumble Recovery (Own)', "abv" => null], 12 => ["text" => 'Kickoff Return (Offense)', "abv" => null], 18 => ['text' => 'Blocked Field Goal', 'abv' => 'BFG'], 21 => ["text" => 'Timeout', "abv" => 'TO'], 24 => ["text" => 'Pass Reception', "abv" => 'REC'], 26 => ["text" => 'Pass Interception Return', "abv" => 'INTR'], 36 => ["text" => 'Interception Return Touchdown', "abv" => 'TD'], 51 => ["text" => 'Pass', "abv" => 'PASS'], 52 => ["text" => 'Punt', "abv" => 'PUNT'], 53 => ["text" => 'Kickoff', "abv" => 'K'], 59 => ["text" => 'Field Goal Good', "abv" => 'FG'], 60 => ["text" => 'Field Goal Missed', "abv" => 'FGM'], 65 => ["text" => 'End of Half', "abv" => 'EH'], 66 => ["text" => 'End of Game', "abv" => 'EG'], 67 => ["text" => 'Passing Touchdown', "abv" => 'TD'], 68 => ["text" => 'Rushing Touchdown', "abv" => 'TD'], 74 => ["text" => 'Official Timeout', "abv" => 'Off TO'], 75 => ["text" => 'Two-minute warning', "abv" => '2Min Warn'], 79 => ["text" => 'End of Regulation', "abv" => 'ER'] ];

Anyone else know where to find a comprehensive list of these from the ESPN play-by-play or drive end-points?

@JimNayzium
Copy link

JimNayzium commented Sep 10, 2024 •
edited
Loading

Here is the list I have compiled of the play_type_id's (which are my index numbers in the array, with the text and abbreviation for espn's play by play feeds.

If the value is null, it means I have not found and confirmed a play with that number play_type_id yet.

I have imported and digested all the 2023 season and searched through it fully.
I am working on other past seasons to try and fill in the gaps.

`
$play_types = [

1 => null,
2 => ["text" => 'End Period', "abv" => 'EP'],
3 => ["text" => 'Pass Incompletion', "abv" => null],
4 => null,
5 => ["text" => 'Rush', "abv" => 'RUSH'],
6 => null,
7 => ["text" => 'Sack', "abv" => null],
8 => ["text" => 'Penalty', "abv" => 'PEN'],
9 => ["text" => 'Fumble Recovery (Own)', "abv" => null],
10 => null,
11 => null,
12 => ["text" => 'Kickoff Return (Offense)', "abv" => null],
13 => null,
14 => null,
15 => null,
16 => null,
17 => ['text' => 'Blocked Punt', 'abv' => 'BP'],
18 => ['text' => 'Blocked Field Goal', 'abv' => 'BFG'],
19 => null,
20 => ['text' => 'Safety', 'abv' => 'SF'],
21 => ["text" => 'Timeout', "abv" => 'TO'],
22 => null,
23 => null,
24 => ["text" => 'Pass Reception', "abv" => 'REC'],
25 => null,
26 => ["text" => 'Pass Interception Return', "abv" => 'INTR'],
27 => null,
28 => null,
29 => ['text' => 'Fumble Recovery (Opponent)', 'abv' => null],
30 => null,
31 => null,
32 => ['text' => 'Kickoff Return Touchdown', 'abv' => 'TD'],
33 => null,
34 => ['text' => 'Punt Return Touchdown', 'abv' => 'TD'],
35 => null,
36 => ["text" => 'Interception Return Touchdown', "abv" => 'TD'],
37 => ['text' => 'Blocked Punt Touchdown', 'abv' => 'TD'],
38 => ['text' => 'Blocked Field Goal Touchdown', 'abv' => 'TD'],
39 => ['text' => 'Fumble Return Touchdown', 'abv' => 'TD'],
40 => ['text' => 'Missed Field Goal Return', 'abv' => 'AFG'],
41 => null,
42 => null,
43 => null,
44 => null,
45 => null,
46 => null,
47 => null,
48 => null,
49 => null,
50 => null,
51 => ["text" => 'Pass', "abv" => 'PASS'],
52 => ["text" => 'Punt', "abv" => 'PUNT'],
53 => ["text" => 'Kickoff', "abv" => 'K'],
54 => null,
55 => null,
56 => null,
57 => ['text' => 'Defensive 2pt Conversion', 'abv' => 'D2P'],
58 => null,
59 => ["text" => 'Field Goal Good', "abv" => 'FG'],
60 => ["text" => 'Field Goal Missed', "abv" => 'FGM'],
61 => null,
62 => null,
63 => null,
64 => null,
65 => ["text" => 'End of Half', "abv" => 'EH'],
66 => ["text" => 'End of Game', "abv" => 'EG'],
67 => ["text" => 'Passing Touchdown', "abv" => 'TD'],
68 => ["text" => 'Rushing Touchdown', "abv" => 'TD'],
69 => null,
70 => null,
71 => null,
72 => null,
73 => null,
74 => ["text" => 'Official Timeout', "abv" => 'Off TO'],
75 => ["text" => 'Two-minute warning', "abv" => '2Min Warn'],
76 => null,
77 => null,
78 => null,
79 => ["text" => 'End of Regulation', "abv" => 'ER']

];
`

@JimNayzium
Copy link

Does anyone know if this endpoint updates live during the games if an injury occurs?

https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/14/roster

Or if there is an endpoint that does indeed update live during the game upon injury?

I noticed for Cooper Kupp on Sunday evening on the roster end point above, his injuries object did have him as Doubtful and did have a time that was around 5:46pm so that would represent a mid-game date/time update. But I was not watching the feed as the game happened and was curious if that is the date/time assigned to the update and possibly put there at a later time, or if that is the actual date/time assigned to the update as it appeared in the endpoint's data feed. So at 5:46pm and after, calling the endpoint above would indeed list Kupp as Doubtful from that point on.

Because if you call that end point now, it will give the date and time associated with McVay's presser when he gave the update about him, so it does not archive the "initial time of injury" in a super user-friendly way to recall later.

What I am trying to accomplish is to assign the most accurate game-clock times to injuries and just looking for the most direct path to get there.

Any advice would be greatly appreciated.

I have a scoreboard feed for each game mapping the game-clocks to wall-clock times, so I think if I can just get a wall clock time for each injury occurence I can get there.

@nntrn
Copy link
Author

nntrn commented Sep 21, 2024 •
edited
Loading

Get injuries in realtime from plays by plays

https://cdn.espn.com/core/nfl/game?xhr=1&gameId=GAME_ID

Map injured athlete from text: {team_abbreviation}-{shortName}

Example from 401671808:

  • gamepackageJSON > drives > previous > [plays]

    // in javascript:
//   $  pre=JSON.parse($('pre').textContent)
//   $  pre.gamepackageJSON.drives.previous.map(e=>e.plays).flat(2).filter(e=>/inju/gi.test(e.text))
{
  "sequenceNumber": "94700",
  "period": { "number": 2 },
  "homeScore": 7,
  "start": {
    "shortDownDistanceText": "3rd & 6",
    "possessionText": "NYJ 13",
    "downDistanceText": "3rd & 6 at NYJ 13",
    "distance": 6,
    "yardLine": 13,
    "team": { "id": "20" },
    "down": 3,
    "yardsToEndzone": 87
  },
  "scoringPlay": false,
  "clock": { "displayValue": "15:00" },
  "type": { "id": "24", "text": "Pass Reception", "abbreviation": "REC" },
  "priority": false,
  "statYardage": 27,
  "awayScore": 0,
  "wallclock": "2024-09-20T00:53:02Z",
  "modified": "2024-09-20T06:32Z",
  "end": {
    "shortDownDistanceText": "1st & 17",
    "possessionText": "NYJ 40",
    "downDistanceText": "1st & 17 at NYJ 40",
    "distance": 17,
    "yardLine": 40,
    "team": { "id": "20" },
    "down": 1,
    "yardsToEndzone": 60
  },
  "id": "401671808947",
  "text": "(Shotgun) A.Rodgers pass short left to A.Lazard to NYJ 40 for 27 yards (K.White). NE-J.Peppers was injured during the play."
}

  • gamepackageJSON > winprobability > [play]

    // in javascript:
//   $  pre=JSON.parse($('pre').textContent)
//   $  pre.gamepackageJSON.winprobability.map(({play,...rest})=>({...play,...rest})).filter(e=>/inju/gi.test(e.text))

{
  "period": { "number": 2 },
  "homeScore": 7,
  "awayScore": 0,
  "start": {
    "shortDownDistanceText": "3rd & 6",
    "possessionText": "NYJ 13",
    "downDistanceText": "3rd & 6 at NYJ 13",
    "distance": 6,
    "yardLine": 13,
    "team": { "id": "20" },
    "down": 3,
    "yardsToEndzone": 87
  },
  "text": "(Shotgun) A.Rodgers pass short left to A.Lazard to NYJ 40 for 27 yards (K.White). NE-J.Peppers was injured during the play.",
  "clock": { "displayValue": "15:00" },
  "type": { "id": "24", "text": "Pass Reception", "abbreviation": "REC" },
  "homeWinPercentage": 0.8,
  "playId": "401671808947",
  "tiePercentage": 0,
  "secondsLeft": 0
},

@JimNayzium

@JimNayzium
Copy link

This is awesome, and very similar to what I am already doing for the play-by-play data to get the injury game clock.
However, for the Cooper Kupp example, he came out of the half and was then deemed Doubtful, so in the play-by-play data of the Rams game Cooper Kupp has no text that describes him being injured.

So his player ID end-point, and the team injuries end-point does describe it via a news release during the game, but then the next morning when the update occurs that time/date is replaced with the monday morning time date of the news release, so if my system "misses" the time of the game the injury status changes, I am looking for a way to retro-actively put it back in place if that makes sense?

Does that make sense? And the team updates and player updates news feed is a little wonky as it has some info from years ago and some info from theprevious game all in one place type thing, so it's seemingly less reliable to predict how to parse through it and find the infomration I would need.

I was just hoping there would be an endpoint that litearlly documents the changes in the injury status of a player with time/date info attached.

@nntrn
Copy link
Author

nntrn commented Sep 22, 2024 •
edited
Loading

At first I thought only minor injuries are reported in play by plays - (minor as in: they're back in the field before the game ends). But after poking around, I came across injuries more serious than Kupp's that were reported in the play by play text. So why wasn't Kupps??!! And how often does this happen?!!!

Maybe injuries recorded in plays are influenced by a team's coach?!

  • The Rams have had a rough run of injuries through the first two weeks, putting three key players on injured reserve this week. McVay said postgame he wasn't sure about the extent of Kupp's injury.
    Source

  • It was only a matter of time, as the conversation surrounding Kupp has been more about injured reserve than his Week 3 availability. The Rams can only bring eight players back from IR all season and have six or seven return candidates on the list already, so they may keep Kupp on the active roster even if he's expected to miss four or more games. The team hasn't specifically commented on that aspect, but coach Sean McVay did say Monday that Kupp is likely out for an "extended period of time."
    Source

Anyways - I think I get what you're trying to do. Have you tried using the search query endpoint for getting the news?

https://site.web.api.espn.com/apis/search/v2?query=kupp&limit=100

Output:

2024-09-19 16:25:49: Fantasy football buzz: No IR for Cooper Kupp, but no timeline for return, either
2024-09-18 22:28:08: Rams put pair on injured reserve, hold off on Cooper Kupp
2024-09-17 14:11:59: Stephania Bell provides Cooper Kupp injury update for fantasy managers
2024-09-16 22:40:36: Rams' Cooper Kupp (ankle) expected to be out extended time
2024-09-16 01:07:19: Rams' Cooper Kupp suffers ankle injury in loss to Cardinals
2024-09-15 17:51:04: Mark the Rams' words: 'This is the Cooper Kupp revenge tour'
2024-09-12 14:35:36: Matchup rankings: Stafford, Kupp, Nabers poised for success in Week 2
2024-05-14 13:12:39: Can Rams WR Cooper Kupp return to triple-crown status?
2024-04-26 15:05:09: Fantasy Football Daily Notes: McLaurin shines on MNF, Kupp injury serious, McCaffrey-Mitchell RB committee
2024-04-23 21:05:34: Fantasy Football Daily Notes: Injuries to Kupp, Herbert, Jeudy and Smith-Schuster mar Sunday's action
2024-04-23 20:01:14: Fantasy Football Daily Notes: Kupp injury not serious, Allen misses practice again, Ravens banged up
2024-04-23 19:54:43: Fantasy Football Daily Notes: Allen injury gets worse; Kupp, Taylor miss practice; Watson will start in Week 13
[..]
2022-09-30 10:00:29: Cooper Kupp off to great start, but Rams' offense still work in progress
2020-05-07 22:32:53: Will Kupp catch over or under 7.5 TDs?
2019-11-07 21:37:43: Cruz: Goff and Kupp will lead Rams to a win over the Steelers

curl -s 'https://site.web.api.espn.com/apis/search/v2?query=kupp&limit=100' |
  jq '.results | map(.contents | map( select(.date) | select(.displayName|contains("Kupp")) |
        [ (.date|strptime("%Y-%m-%dT%H:%M:%S.000+00:00")|strflocaltime("%F %T")),
          .displayName ]
      ))|add|sort_by(.[0])'

@JimNayzium

@raunaqsingh2020
Copy link

does anybody know how to get the box scores from either of the following v3 routes?
https://sports.core.api.espn.com/v3/sports/football/nfl/events/401671617
https://sports.core.api.espn.com/v3/sports/football/nfl/competitions/401671617

also, not sure if there's any good way to figure out which toggles exist for each route (i.e. the ?enable=...), or if that's mostly just a guessing game.

appreciate any help, thanks!

@nntrn
Copy link
Author

nntrn commented Sep 22, 2024

@JimNayzium - I found it!!!!! Search player news using playerId and map it back to plays

https://site.api.espn.com/apis/fantasy/v2/games/ffl/news/players?limit=50&playerId=2977187

$ curl -s -o data.json 'https://site.api.espn.com/apis/fantasy/v2/games/ffl/news/players?limit=50&playerId=2977187'
$ jq -r '.feed[]|select(.type == "Rotowire")|[.published,.headline]|join(": ")' data.json

2024-09-20: Kupp (ankle) has been ruled out for Sunday's game against San Francisco, Gary Klein of the Los Angeles Times reports.
2024-09-18: Head coach Sean McVay said Wednesday that the Rams aren't sure whether Kupp (ankle) will be placed on injured reserve, Jourdan Rodrigue of The Athletic reports.
2024-09-16: Rams head coach Sean McVay said Monday that Kupp (ankle) is expected to be out for "an extended period of time" and could land on injured reserve, Adam Schefter of ESPN reports.
2024-09-15: Kupp was spotted leaving the Rams' locker room with his left ankle in a walking boot after Sunday's 41-10 loss to the Cardinals, Jourdan Rodrigue of The Athletic reports.
2024-09-15: Kupp suffered an ankle injury during Sunday's game at Arizona.
2024-09-11: Kupp is expected to take on greater volume in the Los Angeles passing attack for at least the next four games after the Rams placed Puka Nacua (knee) on injured reserve Wednesday, Stu Jackson of the team's official site reports.
2024-09-09: Kupp hauled in 14 of his game-high 21 targets for 110 yards and a touchdown in Sunday's 26-20 overtime loss to the Lions. He added two carries for 10 yards.
2024-08-24: Kupp (coach's decision) was held out of all the Rams' preseason contests this season.
2024-08-16: The Rams plan to rest Kupp and other key players for Saturday's preseason game against the Chargers, Cameron DaSilva of USA Today reports.
2024-06-06: Coach Sean McVay suggested Tuesday that Kupp was never truly healthy last season but is now back at full strength, Cameron DaSilva of Rams Wire reports.
2024-01-15: Kupp caught five of nine targets for 27 yards in Sunday's 24-23 wild-card round loss to the Lions.
2024-01-07: Kupp (coach's decision) is inactive for Sunday's game against the 49ers, Jourdan Rodrigue of The Athletic reports.
2024-01-03: Head coach Sean McVay said Kupp won't play Sunday at San Francisco, Greg Beacham of the Associated Press reports.
2023-12-31: Kupp caught four of six targets for 27 yards and a touchdown in Sunday's 26-25 win over the Giants.
2023-12-22: Kupp brought in six of 12 targets for 52 yards and rushed once for minus-3 yards in the Rams' 30-22 win over the Saints on Thursday night.
2023-12-18: Kupp recorded eight receptions on eight targets for 111 yards and a touchdown in Sunday's 28-20 win over the Commanders.
2023-12-10: Kupp recorded eight receptions on 10 targets for 115 yards and a touchdown in Sunday's 37-31 loss to the Ravens.
2023-12-04: Kupp caught six of eight targets for 39 yards and a touchdown in Sunday's 36-19 win over the Browns.

@JimNayzium
Copy link

@nntrn - Thanks so much! This is pretty slick! However, what I need is the Date/Time of the accouncements, not just the Date. Like if the Date was 2024-09-15 17:53:21 UTC type thing.

There is now way to reverse engineer from this data the game-clock time and period number of the announcment. But I appreciate your attempts and love what you did!

@psuTickleMonster
Copy link

Good morning. Any idea why this link wouldn't display the post season? It is an eventlog for each player, only makes sense it would display post as well. https://sports.core.api.espn.com/v2/sports/basketball/leagues/wnba/seasons/2024/athletes/4066533/eventlog?limit=100

@AdrianMachado
Copy link

For fans of OpenAPI/Swagger, I started working on a document here. I would appreciate any contributions - the current format is a bit hard for me to work with.

@RyanGiles
Copy link

RyanGiles commented Oct 11, 2024 •
edited
Loading

Does anyone know why the request for all active player ids [https://sports.core.api.espn.com/v3/sports/football/nfl/athletes?limit=20000&active=true] is returning players with the value active = false as well? I could sort manually on my end, but if the api request worked correctly it would cut down on load time drastically (returning 18738 player -> returning about 1700 players).

@JimNayzium
Copy link

I am not sure about your referenced end-point, but what I do is a two part call. One to the current rosters, then parse that by player_id/id and then only ask for the rostered players. Not sure it's what you want, but it is a lot better than getting all the athlete ids!

@JimNayzium
Copy link

@RyanGiles : To actually show what I do a little more usefully, I call this end-point:

site.api.espn.com/apis/site/v2/sports/football/nfl/teams/{{teamId}}?enable=roster

Inside a loop that pools the fetches and lets them run asynchroniously so I can loop through the teamIds, and then I just pull the players from the actual rosters after I have that, if that makes sense.

@RyanGiles
Copy link

@RyanGiles : To actually show what I do a little more usefully, I call this end-point:

site.api.espn.com/apis/site/v2/sports/football/nfl/teams/{{teamId}}?enable=roster

Inside a loop that pools the fetches and lets them run asynchroniously so I can loop through the teamIds, and then I just pull the players from the actual rosters after I have that, if that makes sense.

I see how that workaround can work for getting all rostered players. I'll try that out and see how the runtime compares. It would still be great to just have it return active players like how it's supposed to.

@RyanGiles
Copy link

@RyanGiles : To actually show what I do a little more usefully, I call this end-point:

site.api.espn.com/apis/site/v2/sports/football/nfl/teams/{{teamId}}?enable=roster

Inside a loop that pools the fetches and lets them run asynchroniously so I can loop through the teamIds, and then I just pull the players from the actual rosters after I have that, if that makes sense.

After doing some testing, it's significantly faster (3 sec vs 12 sec) to do the single api call for all players and then filter through them manually than it is to make 32 different api calls for each team's roster

@JimNayzium
Copy link

JimNayzium commented Oct 13, 2024 •
edited
Loading

I know the ESPN and Sleeper API calls for all the players waists a huge amount of loading time. Sleeper's has over 10,000 players when we only need 10-15 percent that. And ESPN's has maybe more than that I can't remember.

I know in my application, calling the all athletes and parsing it after the fact was way way slower. I use PHP to load my API so maybe if you are using python or R or something it may be faster than PHP, I don't really know. I just now when I did the way I describe above I removed all my timeout errors that I was having on my app.

I will add though that I use laravel's Http::pool() methods which allow us to make 32 team calls all at once and call them asynchroniously, which really solved my issues too!

@augarrett
Copy link

is there any endpoint that will let me pull or compile defense tendencies data? for instance man% zone% etc

@JimNayzium
Copy link

Not from ESPN that I know of. You may want to check the roto sites, and maybe PFF. I think you are most likely looking at a scraping solution over an API solution based on the stuff I've found in general. And of course you can always roll with sportsdata.io, but it's exepensive.

@RhettTitus
Copy link

Is there a way to reach power rankings or football power indexes (fpi) through an api on ESPN?

@sraben
Copy link

sraben commented Dec 25, 2024

Would love to know if you found a way to pull the FPI. I would also be interested in this ability.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment