Skip to content

Instantly share code, notes, and snippets.

@akeaswaran

akeaswaran/espn-api-docs.md

Last active April 17, 2024 18:43
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...

@juniortotep
Copy link

anyone got recently working api for soccer?

@morris-choga
Copy link

@juniortotep i am. I recently implemented it in my project & its giving me some delayed status . How is it going for you so far

@tacrec
Copy link

tacrec commented Jan 30, 2024

Is there an endpoint for college softball?

@morris-choga
Copy link

Im not sure,

@zirelco
Copy link

zirelco commented Feb 3, 2024

Anyone implemented any of these in wordpress website? Any suggestions how to do it?

@Sergi0
Copy link

Sergi0 commented Feb 20, 2024

anyone know if it's possible to get team's results for all tournaments?
or at least get list of tournaments that team participates in

for example, this returns Serie A results for AC Milan
https://site.api.espn.com/apis/site/v2/sports/soccer/ita.1/teams/103/schedule

but I would like to get results like these:
https://www.espn.com/soccer/team/results/_/id/103/ita.ac_milan

with Coppa and Europa league

@acerbzzz
Copy link

Can someone tell me how I can get Australian football from the ESPN api. Just need to find the sport id name and league id etc. If someone could help would be amazing.

@carterjpilling
Copy link

carterjpilling commented Feb 25, 2024 •
edited

Can someone tell me how I can get Australian football from the ESPN api. Just need to find the sport id name and league id etc. If someone could help would be amazing.

@acerbzzz
Here is a start https://sports.core.api.espn.com/v2/sports/australian-football/leagues/afl. At least you have the league and sport name. Using the rest of the params I'm sure you'll get it. GL

@jpalm42
Copy link

jpalm42 commented Mar 5, 2024

has anyone had success with api endpoints for ncaa basketball tournament brackets? I have found the format:

http://sports.core.api.espn.com/v2/sports/basketball/leagues/mens-college-basketball/tournaments/22/seasons/${season}/bracketology?

to work for years up until 2021, but 2022 and 2023 return empty

@marcbrigham
Copy link

I found the endpoint for nfl drafts

Athlete: https://site.web.api.espn.com/apis/site/v2/sports/football/nfl/draft/athlete/106643?season=2023&region=us&lang=en
Entire Draft: https://site.web.api.espn.com/apis/site/v2/sports/football/nfl/draft?season=2023&region=us&lang=en

@badrbenhalima
Copy link

Is it possible to get realtime football scores ?

@marcbrigham
Copy link

Is it possible to get realtime football scores ?

I've only seen the scores in the schedule update when refreshing the endpoint. But I'd also love a realtime live scores endpoint as well.

@jrandallsexton
Copy link

jrandallsexton commented Mar 7, 2024 •
edited

I've always felt that forces should be combined and have a service deployed that would perform the polling required to get the data, then publish that information via events (AWS SNS/SQS, Azure Service Bus, etc), so we don't overload their system - and they decide to simply take it offline due to costs.

@ITIRadio
Copy link

ITIRadio commented Mar 7, 2024 •
edited

To respond to some questions above, first, I have found nothing for statistics by period, and I've looked.

As far as combining forces to avoid overuse, I'm not sure how much the general public uses this. They are so aggressive with their throttling, that I anyone who tries to access the API more than a couple of hundred times a day would not have much luck. For example, while you can get individual player stats, for the NFL for example, you wouldn't be able to update the stats of every skill player weekly before getting errors. You'd be better off running an event API call for each game & updating player stats on your own database.

Also, as I posted a couple of years back, ESPN.com is essentially a web app running in your browser (why it's soooo slow) that accesses the API to load the data onto a requested page, the list of current or past scores, a box score, a player's stats, etc. So, literally everyone who uses the site is using this API. The site just thinks I'm a fast clicker, in fact, the speed of the site is the most effective throttler for the general public. Otherwise, I don't have the money lying around to pay for some AWS BS.

As far as real time scores are concerned, the scoreboard calls are pretty current, such as for the NFL, http://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard , which works nicely. If you have Python installed and are OK with using the command line, I have 6 sports now included in my project at https://github.com/ITIRadio/ESPN-API . In-progress scores are included. If you scroll back a little bit in these comments, another poster uses these scoreboard endpoints to copy over updated scores to a site at https://bigearthweb.net/sports/ .

@cardoprimo
Copy link

anyone know if it's possible to get team's results for all tournaments? or at least get list of tournaments that team participates in

for example, this returns Serie A results for AC Milan https://site.api.espn.com/apis/site/v2/sports/soccer/ita.1/teams/103/schedule

but I would like to get results like these: https://www.espn.com/soccer/team/results/_/id/103/ita.ac_milan

with Coppa and Europa league

You can use this format:
https://site.api.espn.com/apis/site/v2/sports/soccer/UEFA.EUROPA/teams/103/schedule
https://site.api.espn.com/apis/site/v2/sports/soccer/{competition}/teams/{teamId}/schedule

The competition codes come from selecting in dropdown on https://www.espn.com/soccer/team/results/_/id/103/ita.ac_milan

@winstonrc
Copy link

has anyone had success with api endpoints for ncaa basketball tournament brackets? I have found the format:

http://sports.core.api.espn.com/v2/sports/basketball/leagues/mens-college-basketball/tournaments/22/seasons/${season}/bracketology?

to work for years up until 2021, but 2022 and 2023 return empty

I found the following endpoint when looking at the requests made for this page: https://www.espn.com/mens-college-basketball/bracket

Endpoint: https://fcast.espncdn.com/FastcastService/pubsub/profiles/12000/topic/bracket-basketball-mens-college-basketball-22-en/message/24624/checkpoint

@ryanbuckner
Copy link

ryanbuckner commented Mar 21, 2024 via email

@winstonrc
Copy link

That format does allow for viewing today's games (e.g. https://data.ncaa.com/casablanca/scoreboard/basketball-men/d1/2024/03/21/scoreboard.json), but I don't see how it could be used to retrieve the bracket ahead of time before the NCAA tournament begins. Any insight?

@chisox721
Copy link

chisox721 commented Mar 24, 2024 •
edited

That format does allow for viewing today's games (e.g. https://data.ncaa.com/casablanca/scoreboard/basketball-men/d1/2024/03/21/scoreboard.json), but I don't see how it could be used to retrieve the bracket ahead of time before the NCAA tournament begins. Any insight?

I haven't actually done this yet because I've been wrapped up in playbyplay data but my plan is to just recreate it based on what's in the json. All you need is ["bracketRegion"], ["bracketRound"], ["away"]["seed"], ["home"]["seed"]

@iko2000
Copy link

iko2000 commented Mar 25, 2024

I am fetching data from - http://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/standings
the outcome is empty object, what can be a cause ?!

@marcbrigham
Copy link

I am fetching data from - http://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/standings the outcome is empty object, what can be a cause ?!

You want to use https://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/scoreboard instead. I'm not sure what your looking for in terms of data but this endpoint does work.

@jafaircl
Copy link

jafaircl commented Mar 27, 2024 •
edited

While the college basketball tournament is going on, any team in the tournament will only return postseason results when you call https://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/teams/{team}/schedule to get their schedule. To get their regular season schedule, append season and seasontype params (i.e. https://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/teams/{team}/schedule?season=2024&seasontype=2) to get a different set of games. Seasontype 2 is regular season, 3 is postseason.

Rankings: https://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/rankings

Standings: https://site.api.espn.com/apis/v2/sports/basketball/mens-college-basketball/standings

@iko2000
Copy link

iko2000 commented Mar 27, 2024

I am fetching data from - http://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/standings the outcome is empty object, what can be a cause ?!

You want to use https://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/scoreboard instead. I'm not sure what your looking for in terms of data but this endpoint does work.

I want to get possition of each time on table, like Liverpool - which position it is in premier league, how many points got and etc.

@stern1978
Copy link

I am fetching data from - http://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/standings the outcome is empty object, what can be a cause ?!

You want to use https://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/scoreboard instead. I'm not sure what your looking for in terms of data but this endpoint does work.

I want to get possition of each time on table, like Liverpool - which position it is in premier league, how many points got and etc.

You have to add ?season=xxxx. https://site.web.api.espn.com/apis/v2/sports/soccer/eng.1/standings?season=2023

@D00pN00dle
Copy link

Could anyone help me out with the possible values of game states? Is there a list somewhere I'm missing?

@bhays
Copy link

bhays commented Apr 10, 2024

I've never seen an exhaustive list, but I have found the following:

  • STATUS_SCHEDULED
  • STATUS_IN_PROGRESS
  • STATUS_END_PERIOD
  • STATUS_HALFTIME
  • STATUS_POSTPONED
  • STATUS_FINAL

@D00pN00dle
Copy link

I've never seen an exhaustive list, but I have found the following:

  • STATUS_SCHEDULED
  • STATUS_IN_PROGRESS
  • STATUS_END_PERIOD
  • STATUS_HALFTIME
  • STATUS_POSTPONED
  • STATUS_FINAL

Thank you! I believe STATUS_CANCELLED is also one of them. Do you know the id for each status? End period and halftime in particular.

@bhays
Copy link

bhays commented Apr 11, 2024

I don't know the ids but you should be able to find them. There's an id key alongside name in competitions->status->type.

@carterjpilling
Copy link

Thank you! I believe STATUS_CANCELLED is also one of them. Do you know the id for each status? End period and halftime in particular.

I found this comment from earlier. Hopefully this helps? @D00pN00dle Link - https://gist.github.com/akeaswaran/b48b02f1c94f873c6655e7129910fc3b?permalink_comment_id=4458293#gistcomment-4458293

@D00pN00dle
Copy link

Thank you! I believe STATUS_CANCELLED is also one of them. Do you know the id for each status? End period and halftime in particular.

I found this comment from earlier. Hopefully this helps? @D00pN00dle Link - https://gist.github.com/akeaswaran/b48b02f1c94f873c6655e7129910fc3b?permalink_comment_id=4458293#gistcomment-4458293

Oh man Idk why but I didn't even think to look through the comments section for answers! Thank you so much! I'll have to keep in mind the comments are kind of like an extension of the documentation. Thanks again @carterjpilling

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