Skip to content

Instantly share code, notes, and snippets.

@akeaswaran

akeaswaran/espn-api-docs.md

Last active September 18, 2024 14:26
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...

@brettshumaker
Copy link

What I've been doing for getting game data after weekend's games is using this endpoint https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=$start_date-$end_date&limit=200 where $start_date and $end_date are using YYYYMMDD formatting. That lists all games that happened between the given dates (assuming there are less than 200 games between your dates).

@nrnrnr
Copy link

nrnrnr commented Sep 18, 2022

The scheduling endpoint, which returned JSON until a week or two ago, is now suddenly returning a web page. For example, https://www.espn.com/nfl/schedule/_/year/2022/week/2/seasontype/2?xhr=1

Is it still possible to get schedule information in JSON?

@drewcoble
Copy link

The scheduling endpoint, which returned JSON until a week or two ago, is now suddenly returning a web page. For example, https://www.espn.com/nfl/schedule/_/year/2022/week/2/seasontype/2?xhr=1

Is it still possible to get schedule information in JSON?

It looks like you are calling a url for a webpage. It should look something like: “https://sports.core.api.espn.com/v2/sports/football/leagues/nfl/“ and then add the endpoint you are looking for.

@nrnrnr
Copy link

nrnrnr commented Sep 29, 2022 •
edited
Loading

@drewcoble using that base URL I am having trouble composing an endpoint that does anything except "application error." However, the original URL seems to work if the parameter is called _xhr with an initial underscore instead of just xhr.

@rondog
Copy link

rondog commented Sep 29, 2022

@nrnrnr remove the quote at the end of the link drew posted

@famictech2000
Copy link

Does anyone know the API for world cup soccer scores coming soon?

@ZachManno
Copy link

How to know in NFL which team has possession?

@ryanbuckner
Copy link

if (gameStatus == "in") {
try {
situation = game['situation']['downDistanceText'];
possessionId = game['situation']['possession'];
}

You then have to match the possessionId to the teamId to determine which team has the ball

@srivastr14
Copy link

Anyone able to find how you can get the starting lineup either during or before an MLB game? I can't seem to find that at all

@bobgodwin
Copy link

bobgodwin commented Oct 9, 2022 •
edited
Loading

Anyone able to find how you can get the starting lineup either during or before an MLB game? I can't seem to find that at all

http://site.api.espn.com/apis/site/v2/sports/baseball/mlb/summary?event=401246334

rosters[0] (0 = home, 1 = away) roster[n]. Roster has batting order, athlete, position, jersey, stats etc. Be aware that there may be more then 9 entries. But this is the closest I've got.
Edit: Just noticed roster[n]starter(true or false). So loop and check for starter=true or something like that.

@bobgodwin
Copy link

bobgodwin commented Oct 9, 2022 •
edited
Loading

Just going to leave a few of my projects here if it's alright. Other than my football sites (Football Pool and Squares), most every thing I build is to replace the various home pages (Yahoo, MSN, Bing) that I've used throughout the years. Thanks to the ESPN API (And The National Weather Service API), I can pretty much do that. I've built a lot web pages (I guess they call them apps now) that use that datas:

Live games for multiple sports
https://bigearthweb.net/sports/sports-live/
Standings for multiple sports:
https://bigearthweb.net/sports/standings/
And my latest, one I've always wanted to do but never got around to, a live visual representation of a football game (NFL & NCAA):
https://bigearthweb.net/sports/football_field/

I also have multiple ways of extracting data to JSON or SQL (All PHP) if you want to store it locally (One is included in the sports-live archive. JSON only. Schedule and all dates. The JSON-Leagues archives are those files). Here are links to the archives for anyone interested:

https://bigearthweb.net/sports/sports-live.7z
https://bigearthweb.net/sports/standings.7z
https://bigearthweb.net/sports/football_field.7z
https://bigearthweb.net/sports/json-leagues.7z

Just extract to your site. I know Sports-Live is Americentric, but I know nothing about soccer, so they're hard for me to build. Same with the football field. I'd love to see someone build one of those for non-American football based on what I have. I do have Y'all in standings though! I hope these come in handy for someone. I also am building a site to run your office football squares if anyone's interested,

P.S.
Some links that I've put up before may not work anymore. Let me know if somethings gone you may want.

@srivastr14
Copy link

srivastr14 commented Oct 11, 2022 •
edited
Loading

Anyone able to find how you can get the starting lineup either during or before an MLB game? I can't seem to find that at all

http://site.api.espn.com/apis/site/v2/sports/baseball/mlb/summary?event=401246334

rosters[0] (0 = home, 1 = away) roster[n]. Roster has batting order, athlete, position, jersey, stats etc. Be aware that there may be more then 9 entries. But this is the closest I've got. Edit: Just noticed roster[n]starter(true or false). So loop and check for starter=true or something like that.

You are incredible! Thank you so much! Could you also help me look for starting pitcher's losses? I can find their era and wins, but not loses for some reason. Any help from anyone is appreciated!

Essentially I'm looking for the API that shows the "Season stats" that can be seen on this page: https://www.espn.com/mlb/player/_/id/5883/zack-greinke

@bobgodwin
Copy link

Essentially I'm looking for the API that shows the "Season stats" that can be seen on this page: https://www.espn.com/mlb/player/_/id/5883/zack-greinke

Try here:
https://site.web.api.espn.com/apis/common/v3/sports/baseball/mlb/athletes/5883
Look for "statsSummary/statistics." 0 = W/L 1=ERA 2=Ks 3=WHIP. It's the only place I've found.

@lexcraw4d
Copy link

when does it update for cfb http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard ......
still showing week 7 and the odds went awy

@lexcraw4d
Copy link

image

I guess tomorrow the 18th - (Tuesdays?)

@daviswieck
Copy link

Odds only show for Pregame.
It will update close to midnight just in case any games are played on Monday night.

@bobgodwin
Copy link

bobgodwin commented Oct 21, 2022 •
edited
Loading

I've update the Football Gridiron to include NCAA Football. You can select the games of the week or by conference.

https://bigearthweb.net/sports/football_field/
https://bigearthweb.net/sports/football_field.7z

And a list of NCAA Conference ids if anyone needs it:

Id = 80, Conf = FBS (I-A)
Id = 1, Conf = ACC
Id = 151, Conf = American
Id = 4, Conf = Big 12
Id = 5, Conf = Big Ten
Id = 12, Conf = C-USA
Id = 18, Conf = FBS Indep
Id = 15, Conf = MAC
Id = 17, Conf = Mountain West
Id = 9, Conf = Pac-12
Id = 8, Conf = SEC
Id = 37, Conf = Sun Belt
Id = 81, Conf = FCS (I-AA)
Id = 176, Conf = ASUN
Id = 20, Conf = Big Sky
Id = 40, Conf = Big South
Id = 48, Conf = CAA
Id = 22, Conf = Ivy
Id = 24, Conf = MEAC
Id = 21, Conf = MVFC
Id = 25, Conf = NEC
Id = 26, Conf = OVC
Id = 27, Conf = Patriot
Id = 28, Conf = Pioneer
Id = 31, Conf = SWAC
Id = 29, Conf = Southern
Id = 30, Conf = Southland
Id = 16, Conf = WAC

@nicksiscoe
Copy link

nicksiscoe commented Oct 21, 2022 •
edited
Loading

Anyone else only seeing like the first half of tomorrow's games when hitting https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=20221022? is it just me?
cc @reidwatson

@pjjacobson
Copy link

Standings endpoints. Most of the urls in this thread have '/apis/site/v2' in the url. The standings urls are just '/apis/v2'.

https://site.api.espn.com/apis/v2/sports/hockey/nhl/standings
https://site.api.espn.com/apis/v2/sports/basketball/nba/standings
https://site.api.espn.com/apis/v2/sports/football/nfl/standings
https://site.api.espn.com/apis/v2/sports/baseball/mlb/standings
https://site.api.espn.com/apis/v2/sports/football/college-football/standings
https://site.api.espn.com/apis/v2/sports/basketball/mens-college-basketball/standings
https://site.api.espn.com/apis/v2/sports/hockey/mens-college-hockey/standings
https://site.api.espn.com/apis/v2/sports/baseball/college-baseball/standings

There are parameters you can pass, so a full url might look like:
https://site.api.espn.com/apis/v2/sports/basketball/nba/standings?region=us&lang=en&contentorigin=espn&type=0&level=3&sort=playoffseed%3Aasc

Haven't figured out what the type parameter does, but level appears to be:
1 = Overall league-wide standings
2 = Conference standings
3 = Division standings
4+ = Same as division standings
0 = Same as division standings

It also looks like you can also chain multiple sort parameters together
https://site.api.espn.com/apis/v2/sports/hockey/nhl/standings?region=us&lang=en&contentorigin=espn&type=0&level=3&sort=playoffseed:asc,points:desc,gamesplayed:asc,rotwins:desc

@crichmond
Copy link

@akeaswaran,

How is it possible that we are able to access this when ESPN shut down public API support like 8 years ago?

@bobgodwin
Copy link

This seems pretty comprehensive:

https://www.espn.com/apis/devcenter/overview.html

Even has a branding guide and API logos.

@KevinDuganJr
Copy link

@akeaswaran,

How is it possible that we are able to access this when ESPN shut down public API support like 8 years ago?

Maybe they do not support it publicly, but they use it as the back-end for their data?

@munge64
Copy link

munge64 commented Oct 29, 2022 via email

@trueparallels
Copy link

This is just a community effort at documenting what is there now that's publicly available in some capacity. I wouldn't build anything that's not a hobby on it. If you're building a business, you're going to have to find somewhere you can pay for that data or risk getting shut down at any time.

The likely answer is that ESPN doesn't care about a few random hobbyists across the globe using their API for some minor things. It's a drop in the bucket for them. If ESPN drops a v3 GraphQL API at some point, I wouldn't be surprised, but I would be it would not be even slightly public.

@KevinDuganJr
Copy link

I'd like to find out also, because I don't want to build a bunch of code for my website (some of which I've already done) that is going to suddenly disappear...

Develop your website in a manner that it just consumes an object using the API data as middleware. Then when/if the ESPN API changes or fails, you just have to find a new source and your website continues. This is what I had to do with mine. NFL changed their API, or rather closed it down.

@lexcraw4d
Copy link

What is yalls best approach on querying a player by name if you don't know the id?

@slovanos
Copy link

slovanos commented Nov 4, 2022

Hi, and thanks for the list!

Any ideas on how to get boxing Information?

I discover some urls for mma:
https://site.api.espn.com/apis/site/v2/sports/mma/ufc/news
https://site.api.espn.com/apis/site/v2/sports/mma/ufc/scorboard

And for boxing it should be something analogous like:
https://site.api.espn.com/apis/site/v2/sports/boxing/:something/scoreboard

but I'm not getting anything. Any help would be appreciated

@codecatalysts
Copy link

@slovanos If you use this link you can find paths further down the tree by navigating to the url in the $ref. I don't see a top level boxing but there are several in mma, maybe has what you are looking for.

http://sports.core.api.espn.com/v2/sports

@ZachManno
Copy link

Made a parser that will turn the JSON response into a scoreboard object:
https://github.com/ZachManno/sports-scoreboard-ticker-led/blob/master/espn-scores/Scoreboard.py

@slovanos
Copy link

slovanos commented Nov 7, 2022

@slovanos If you use this link you can find paths further down the tree by navigating to the url in the $ref. I don't see a top level boxing but there are several in mma, maybe has what you are looking for.

http://sports.core.api.espn.com/v2/sports

Thanks @codecatalysts for your replay. Unfortunately I still can not find boxing info. I'm just looking for the upcomming fights on boxing to begin with, and, if available, the results (like on the scoreboard for the other sports)

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