Skip to content

Instantly share code, notes, and snippets.

@akeaswaran

akeaswaran/espn-api-docs.md

Last active September 25, 2024 05:15
Show Gist options
  • Save akeaswaran/b48b02f1c94f873c6655e7129910fc3b to your computer and use it in GitHub Desktop.
Save akeaswaran/b48b02f1c94f873c6655e7129910fc3b to your computer and use it in GitHub Desktop.
Download ZIP
ESPN hidden API Docs
Raw
espn-api-docs.md

ESPN's hidden API endpoints

Football

College Football

Latest News: http://site.api.espn.com/apis/site/v2/sports/football/college-football/news

Latest Scores: http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard

  • query params:

    • calendar: 'blacklist'
    • dates: any date in YYYYMMDD

Game Information: http://site.api.espn.com/apis/site/v2/sports/football/college-football/summary?event=:gameId

  • params:

    • gameId: identifier of some game (EX: 400934572 for 2017 Army vs Navy)

Team Information: http://site.api.espn.com/apis/site/v2/sports/football/college-football/teams/:team

  • params:

    • team: some team abbreviation (EX: 'all' for Allegheny, 'gt' for Georgia Tech, 'wisconsin' for Wisconsin)

Rankings: http://site.api.espn.com/apis/site/v2/sports/football/college-football/rankings

NFL

Scores: http://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard

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

All Teams: http://site.api.espn.com/apis/site/v2/sports/football/nfl/teams

Specific Team: http://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/:team

Baseball

MLB

Scores: http://site.api.espn.com/apis/site/v2/sports/baseball/mlb/scoreboard

News: http://site.api.espn.com/apis/site/v2/sports/baseball/mlb/news

All Teams: http://site.api.espn.com/apis/site/v2/sports/baseball/mlb/teams

Specific Team: http://site.api.espn.com/apis/site/v2/sports/baseball/mlb/teams/:team

College Baseball

Scores: https://site.api.espn.com/apis/site/v2/sports/baseball/college-baseball/scoreboard

Hockey

Scores: http://site.api.espn.com/apis/site/v2/sports/hockey/nhl/scoreboard

News: http://site.api.espn.com/apis/site/v2/sports/hockey/nhl/news

All Teams: http://site.api.espn.com/apis/site/v2/sports/hockey/nhl/teams

Specific Team: http://site.api.espn.com/apis/site/v2/sports/hockey/nhl/teams/:team

Basketball

NBA

Scores: http://site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard

News: http://site.api.espn.com/apis/site/v2/sports/basketball/nba/news

All Teams: http://site.api.espn.com/apis/site/v2/sports/basketball/nba/teams

Specific Team: http://site.api.espn.com/apis/site/v2/sports/basketball/nba/teams/:team

WNBA

Scores: http://site.api.espn.com/apis/site/v2/sports/basketball/wnba/scoreboard

News: http://site.api.espn.com/apis/site/v2/sports/basketball/wnba/news

All Teams: http://site.api.espn.com/apis/site/v2/sports/basketball/wnba/teams

Specific Team: http://site.api.espn.com/apis/site/v2/sports/basketball/wnba/teams/:team

Women's College Basketball

Scores: http://site.api.espn.com/apis/site/v2/sports/basketball/womens-college-basketball/scoreboard

News: http://site.api.espn.com/apis/site/v2/sports/basketball/womens-college-basketball/news

All Teams: http://site.api.espn.com/apis/site/v2/sports/basketball/womens-college-basketball/teams

Specific Team: http://site.api.espn.com/apis/site/v2/sports/basketball/womens-college-basketball/teams/:team

Men's College Basketball

Scores: http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard

News: http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/news

All Teams: http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/teams

Specific Team: http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/teams/:team

Soccer

Scores: http://site.api.espn.com/apis/site/v2/sports/soccer/:league/scoreboard

  • params:

    • league: some league abbreviation (EX: 'eng.1' for EPL, 'usa.1' for MLS)

Latest News: http://site.api.espn.com/apis/site/v2/sports/soccer/:league/news

List of Team Information: http://site.api.espn.com/apis/site/v2/sports/soccer/:league/teams

Will update with more information as I find more...

@stern1978
Copy link

@hawkseye76 is this what you are looking for?
https://site.api.espn.com/apis/v2/scoreboard/header?sport=volleyball&league=womens-college-volleyball

@hawkseye76
Copy link

hawkseye76 commented Dec 6, 2022 •
edited
Loading

@stern1978 That is exactly what i'm looking for! Thank you!

Wonder why https://site.api.espn.com/apis/site/v2/sports/volleyball/womens-college-volleyball/scoreboard doesn't work like the other sports?

Edit: Well, now that link works. Maybe i just had a typo or something. Regardless, Thanks @stern1978!!

@makeniii
Copy link

makeniii commented Dec 14, 2022 •
edited
Loading

Is there a id for a NBA season? Doesn't seem like there is but thought I'd ask anyways.

Also, does anyone know what 4/5 means for this variable for example, schedule_json['events']['competitions'][0]['status']['type']['id']? Currently, I know that:

1 = scheduled
2 = live
3 = completed
6 = postponed

So I'm assuming that 4/5 must mean something too but I haven't come across it yet.

@CyrilNb
Copy link

CyrilNb commented Jan 10, 2023

Does any one succeed to get leader of a soccer league (like Premiere league for example?). Scoreboard endpoint does not give current standings of the season

@CyrilNb
Copy link

CyrilNb commented Jan 10, 2023

Same for NBA, I am trying to get the current standing for both conferences. Is there a way someone managed to get it?

@zhayes84
Copy link

I wrote a Python "handler" (I don't know the proper label) that handles most of the College Football Ranking data:

https://github.com/zhayes84/espn-college-football-rankings-api-python/blob/main/ncaa_rankings_json.py

@nworbdier
Copy link

Does anyone know the endpoints for:

PGA Schedule (List of all tournaments and info for a given year/month/date)

PGA Player Scorecards for a Specific Tournament (Ideally only the details for a single golfer for a specific tournament

@ryanbuckner
Copy link

ryanbuckner commented Jan 24, 2023 •
edited
Loading

Is there a way to use the NCAA Men's Basketball feed to get all March Madness games and scores?
http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard

@ryanbuckner
Copy link

ryanbuckner commented Jan 24, 2023 •
edited
Loading

Let me add a couple of specific responses to replies: the NFL API calls can be slow if event calls & scoreboard calls are done quickly in succession, as in when automated. I abandoned the ticker idea, as Python I/O libraries always have some crucial lack of functionality that make automation unusable. For example, PyAutoGUI has automatic vertical scrolling, which would have been nice, but there's no flag, ......
I'll post basketball as I have time. The code is lengthier than expected because there ended up being significantly more error checking than I could have imagined. REST API databases make me love MySQL databases all over again.

I created a public google sheets that uses the NFL API and updates every 15 minutes
Sheets

@collinstork
Copy link

Just found out you can use "all" for the league, if the team is in multiple leagues.
so if you want to see the nextEvent for USMNT:
https://site.api.espn.com/apis/site/v2/sports/soccer/all/teams/usa

@athleticmistud
Copy link

does anyone know of the link for the live scores for the now depreciated https://feeds.nfl.com/feeds-rs/scores.json is there an alternative for the live scores?

@daverz06
Copy link

Is there a way to use the NCAA Men's Basketball feed to get all March Madness games and scores? http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard

The last "date" is 3-12 but the season end date in column I says 4-05, so I'm hoping we get data for the tournament. Do you know how to get all games right now instead of just ranked games?

@CN120
Copy link

CN120 commented Feb 3, 2023 •
edited
Loading

@makeniii

Is there a id for a NBA season? Doesn't seem like there is but thought I'd ask anyways.

Also, does anyone know what 4/5 means for this variable for example, schedule_json['events']['competitions'][0]['status']['type']['id']? Currently, I know that:

1 = scheduled
2 = live
3 = completed
6 = postponed

So I'm assuming that 4/5 must mean something too but I haven't come across it yet.

Pulled from here

ID ESPN Status
0 TBD
1 SCHEDULED
2 IN PROGRESS
3 FINAL
4 FORFEIT
5 CANCELLED
6 POSTPONED
7 DELAYED
8 SUSPENDED
9 FORFEIT OF HOME TEAM
10 FORFEIT OF AWAY TEAM
17 RAIN DELAY
21 BEGINNING OF PERIOD
22 END OF PERIOD
23 HALFTIME
24 OVERTIME
25 FIRST HALF
26 SECOND HALF
27 ABANDONED
28 FULL TIME
29 RESCHEDULED
30 START LIST
31 INTERMEDIATE
32 UNOFFICIAL
33 MEDAL OFFICIAL
34 GROUPINGS OFFICIAL
35 PLAY COMPLETE
36 OFFICIAL - EVENT SHORTENED
37 CORRECTED RESULT
38 RETIRED
39 BYE
40 WALKOVER
41 VOID
42 PRELIMINARY
43 GOLDEN TIME
44 SHOOTOUT
45 FINAL SCORE - AFTER EXTRA TIME
46 FINAL SCORE - AFTER GOLDEN GOAL
47 FINAL SCORE - AFTER PENALTIES
48 END EXTRA TIME
49 EXTRA TIME HALF TIME
50 FIXTURE - NO LIVE COVERAGE
51 FINAL SCORE - ABANDONED

@ryanbuckner
Copy link

does anyone know of the link for the live scores for the now depreciated https://feeds.nfl.com/feeds-rs/scores.json is there an alternative for the live scores?

Regular Season:
https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?seasontype=2&week= + weeknumber

Post Season
https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?seasontype=3&week= + weeknumber

@athleticmistud
Copy link

athleticmistud commented Feb 3, 2023 via email

@ryanbuckner
Copy link

ryanbuckner commented Feb 3, 2023 •
edited
Loading

What week number are we on in post season?...the best is yet to come...

Short answer, 22.

Here's my function for post season to build my live tracker

function getPostWeekName(weeknum) {
  var weekName;
  if (weeknum == 19){
      weekName = "WildCard";
    } else if (weeknum == 20){
      weekName = "Divisional";
    } else if (weeknum == 21){
      weekName = "Conference";
    } else if (weeknum == 22){
      weekName = "Pro Bowl";
    } else if (weeknum == 23){
      weekName = "SuperBowl";
  }
  return weekName;
}

@chrisblakley
Copy link

For anyone who may be interested (doesn't look like this has been mentioned here yet), the XFL works with this API:
Example: https://site.api.espn.com/apis/site/v2/sports/football/xfl/scoreboard

Nothing for the USFL that I can find, however.

@PIC954
Copy link

PIC954 commented Feb 8, 2023

hey!

Does anyone know the nascar/F1 API call?

@chrisblakley
Copy link

Nascar is no longer available, but here is an example endpoint for Formula 1:
https://site.api.espn.com/apis/site/v2/sports/racing/f1/scoreboard

There is a different endpoint for drivers, but you need the competition ID and the driver ID:
https://sports.core.api.espn.com/v2/sports/racing/leagues/f1/events/GAMEIDHERE/competitions/COMPETITIONIDHERE/competitors/DRIVERIDHERE/statistics

@tonycarnevale
Copy link

tonycarnevale commented Feb 9, 2023 •
edited
Loading

Is there a way to use the NCAA Men's Basketball feed to get all March Madness games and scores? http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard

@daverz06 @ryanbuckner this might be late but a way to do this would be adding groups=

for example https://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard?groups=7
or http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard?dates=20230123&groups=0

for some reason the college basketball api only has limited data by default. My answer now is turning into a question. Does anyone know how to do a range of groups for ncaab?

@ischmidt20
Copy link

ischmidt20 commented Feb 9, 2023 •
edited
Loading

for some reason the college basketball api only has limited data by default

@tonycarnevale You need to add the limit argument to ensure all games for a day are returned. I usually set limit to 363 as there will never be more than 363 D1 games in a day

Set groups equal to 50 to get all NCAA D1 games (regular season and conference tournaments). The postseason tournaments have different identifiers which unfortunately I can't recall at the moment.

@athleticmistud
Copy link

What week number are we on in post season?...the best is yet to come...

Short answer, 22.

Here's my function for post season to build my live tracker

function getPostWeekName(weeknum) {
  var weekName;
  if (weeknum == 19){
      weekName = "WildCard";
    } else if (weeknum == 20){
      weekName = "Divisional";
    } else if (weeknum == 21){
      weekName = "Conference";
    } else if (weeknum == 22){
      weekName = "Pro Bowl";
    } else if (weeknum == 23){
      weekName = "SuperBowl";
  }
  return weekName;
}

Thank you! So how real time is it? is there much delay ?
so if I use your function and wanted it for regular season do I just do the same function but starting with 1?)

@ryanbuckner
Copy link

Thank you! So how real time is it? is there much delay ? so if I use your function and wanted it for regular season do I just do the same function but starting with 1?)

You can call this to see the regular season week 1 - if you click the link below you'll see the events JSON payload for all the games in week 1. The data is real time and sometimes faster than my YouTube TV feed. But I would caution that there is a limit on how many times per day you can call it. That goes for all these APIs.

I usually call it every 60 minutes when there is no game, to get schedule updates and odds / lines changes. When games are on I switch to every 5 minutes. This way I avoid the limits, which I think is 2500 calls per day.

https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?seasontype=2&week=1

@ITIRadio
Copy link

ITIRadio commented Feb 12, 2023 •
edited
Loading

does anyone know of the link for the live scores for the now depreciated https://feeds.nfl.com/feeds-rs/scores.json is there an alternative for the live scores?

Regular Season:
https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?seasontype=2&week= + weeknumber

Post Season
https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?seasontype=3&week= + weeknumber

I use the following syntax for a date range, although it seems to work better if the second date is one day after the required date for a weekend's set of games (usually like a Thursday to Tuesday):

http://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?dates=YYYYMMDD-YYYYMMDD , where the first date in chronological order is first, and then the second date.

@ITIRadio
Copy link

for some reason the college basketball api only has limited data by default

@tonycarnevale You need to add the limit argument to ensure all games for a day are returned. I usually set limit to 363 as there will never be more than 363 D1 games in a day

Set groups equal to 50 to get all NCAA D1 games (regular season and conference tournaments). The postseason tournaments have different identifiers which unfortunately I can't recall at the moment.

I'm not sure about tournaments yet, but groups = 50 is all Division I, on given dates, so this should work throughout the remainder of the season & post-season:

http://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard?groups=50&limit=200&dates=YYYYMMDD-YYYYMMDD

with the dates in the desired range (though the second date, the latter, sometimes needs to be one day after the desired date). This syntax has worked all season so far, for every game involving a Division I team.

@ryanbuckner
Copy link

I use the following syntax for a date range, although it seems to work better if the second date is one day after the required date for a weekend's set of games (usually like a Thursday to Tuesday):

http://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?dates=YYYYMMDD-YYYYMMDD , where the first date in chronological order is first, and then the second date.

Where most sports are played on a daily basis, the NFL is played by week. I wasn't able to get the above syntax to work with the nfl feed. I also tried to plug in a year, and I still get back data from this season.

@RONJ0N
Copy link

RONJ0N commented Feb 14, 2023

is using this api illegal in any way? or is it just free range anybody can use it?

@opendoug
Copy link

opendoug commented Feb 14, 2023 •
edited
Loading

For anyone needing JSON of NFL games, this URL seems to work:

http://site.api.espn.com/apis/site/v2/sports/football/nfl/summary?event= + {game ID}

@athleticmistud
Copy link

athleticmistud commented Feb 14, 2023 via email

@ryanbuckner
Copy link

for some reason the college basketball api only has limited data by default

@tonycarnevale You need to add the limit argument to ensure all games for a day are returned. I usually set limit to 363 as there will never be more than 363 D1 games in a day

I was able to get data for 63 games today with the following based on a few tips above

https://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard?groups=50&limit=500

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