Skip to content

Instantly share code, notes, and snippets.

@akeaswaran

akeaswaran/espn-api-docs.md

Last active June 25, 2024 22:25
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...

@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
Loading

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
Loading

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

@finnbrauer
Copy link

finnbrauer commented May 2, 2024 •
edited
Loading

Does anyone know how to return the Athlete/Player Info for Past Years/Seasons in Men's College Basketball? For a while, this endpoint returned all of the player info (height, weight, player ID, etc.) for all CBB players active in the 2023-2024 season: https://sports.core.api.espn.com/v3/sports/basketball/mens-college-basketball/athletes?limit=1000000000. Now, though, it is not working (unsure why). That said, this endpoint now seems to return what that endpoint used to, and includes the relevant player info that I am looking for from the current 2023-2024 season (I believe - Duke Freshman TJ Power is in both sets of data, for example, though the actual number of responses varies a little, and the responses are no longer sorted in alphabetical order by last name, which is a bit confusing): https://sports.core.api.espn.com/v3/sports/basketball/mens-college-basketball/seasons/2024/athletes?limit=1000000000.

The issue is that changing the year in that endpoint does not actually change the response. For example, https://sports.core.api.espn.com/v3/sports/basketball/mens-college-basketball/seasons/2019/athletes?limit=1000000000 still returns the exact same page and data as the previous endpoint url, even though the year is 2019. I have downloaded the current 2023-2024 relevant data that I need already, but am struggling to find how I can access the data for past years of college basketball players.

I know that I could theoretically loop through every single player ID by using this endpoint and storing the data https://sports.core.api.espn.com/v3/sports/basketball/mens-college-basketball/athletes/{playerID} from 1 to whatever it gets to, but that feels like it cannot possibly be the most efficient way to do this lol. I've been trying to fool around with possible end points by adding in season(s), year(s), or dates parameters but haven't gotten anything to work. Would appreciate any advice! Thanks!

@yesh-rajawat-robomq
Copy link

Is there anything for cricket

@mattabets
Copy link

Anyone know how to access gamelogs from previous years?

Gamelog:
(https://site.web.api.espn.com/apis/common/v3/sports/football/nfl/athletes/14876/gamelog)

@JamesSingleton
Copy link

I wonder if there is a way to get a college sports start and end dates somehow

@peteywhit
Copy link

I wonder if there is a way to get a college sports start and end dates somehow

You mean the start and finish of each part of the season like preseason, regular season, postseason or regionals, etc?

yes you can use
http://site.api.espn.com/apis/common/v3/sports/baseball/college-baseball/season
Or
http://site.api.espn.com/apis/common/v3/sports/football/college-football/season

@JamesSingleton
Copy link

JamesSingleton commented Jun 5, 2024 •
edited
Loading

@peteywhit good to know! However, I was looking at it and it gives me

{
  "year": 2023,
  "displayName": "2023",
  "startDate": "2023-07-01T07:00:00.000+00:00",
  "endDate": "2024-01-10T07:59:00.000+00:00",
  "types": [
    {
      "id": "1",
      "type": 1,
      "name": "Preseason",
      "startDate": "2023-07-01T07:00:00.000+00:00",
      "endDate": "2023-08-26T06:59:00.000+00:00"
    },
    {
      "id": "2",
      "type": 2,
      "name": "Regular Season",
      "startDate": "2023-08-26T07:00:00.000+00:00",
      "endDate": "2023-12-12T07:59:00.000+00:00"
    },
    {
      "id": "3",
      "type": 3,
      "name": "Postseason",
      "startDate": "2023-12-12T08:00:00.000+00:00",
      "endDate": "2024-01-10T07:59:00.000+00:00"
    },
    {
      "id": "4",
      "type": 4,
      "name": "Off Season",
      "startDate": "2024-01-10T08:00:00.000+00:00",
      "endDate": "2024-07-01T06:59:00.000+00:00"
    }
  ]
}

So it gives the previous season. However, doing https://site.api.espn.com/apis/common/v3/sports/football/college-football/seasons/2024 will give me the 2024 season. Also, if you just do https://site.api.espn.com/apis/common/v3/sports/football/college-football/seasons it gives you seasons all the way back until 1872. I wish I could get the details that comes in /seasons but for a specific year. For example, the weeks don't return in the /seasons/2024

@peteywhit
Copy link

@JamesSingleton yes, but that is intentional due to the current date falling in the Off Season date range for 2023.
This will change to season 2024 on July 1 at 7:00am UTC or 2:00am CST for me.

{
  "seasons": [
    {
      "year": 2024,
      "displayName": "2024",
      "startDate": "2024-07-01T07:00:00.000+00:00",
      "endDate": "2025-01-22T07:59:00.000+00:00",
      "types": [
        {
          "id": "1",
          "type": 1,
          "name": "Preseason",
          "startDate": "2024-07-01T07:00:00.000+00:00",
          "endDate": "2024-08-24T06:59:00.000+00:00",
          "weeks": [
            {
              "number": 1,
              "startDate": "2024-07-01T07:00:00.000+00:00",
              "endDate": "2024-08-24T06:59:00.000+00:00",
              "text": "Week 1"
            }
          ],
          "week": {}
        },
        {
          "id": "2",
          "type": 2,
          "name": "Regular Season",
          "startDate": "2024-08-24T07:00:00.000+00:00",
          "endDate": "2024-12-15T07:59:00.000+00:00",
          "weeks": [
            {
              "number": 1,
              "startDate": "2024-08-24T07:00:00.000+00:00",
              "endDate": "2024-09-03T06:59:00.000+00:00",
              "text": "Week 1"
            },
            {
              "number": 2,
              "startDate": "2024-09-03T07:00:00.000+00:00",
              "endDate": "2024-09-08T06:59:00.000+00:00",
              "text": "Week 2"
            },
            {
              "number": 3,
              "startDate": "2024-09-08T07:00:00.000+00:00",
              "endDate": "2024-09-15T06:59:00.000+00:00",
              "text": "Week 3"
            },

There may be a header value that can make these details show in the https://site.api.espn.com/apis/common/v3/sports/football/college-football/seasons/2024 link, however I haven't been able to figure it out.

I have noticed that for the /seasons url, NFL and college football are the only sports that have the defined week details for the entire seasons. Other sports like MLB only show the current week in the current season, and then college-baseball, nba and soccer/USA.1 don't show week details at all.

{
  "seasons": [
    {
      "year": 2024,
      "displayName": "2024",
      "startDate": "2024-02-15T08:00:00.000+00:00",
      "endDate": "2024-12-11T07:59:00.000+00:00",
      "types": [
        {
          "id": "1",
          "type": 1,
          "name": "Spring Training",
          "startDate": "2024-02-15T08:00:00.000+00:00",
          "endDate": "2024-03-27T06:59:00.000+00:00",
          "week": {}
        },
        {
          "id": "2",
          "type": 2,
          "name": "Regular Season",
          "startDate": "2024-03-20T07:00:00.000+00:00",
          "endDate": "2024-10-01T06:59:00.000+00:00",
          "week": {
            "number": 11,
            "startDate": "2024-05-29T07:00:00.000+00:00",
            "endDate": "2024-06-05T06:59:00.000+00:00",
            "text": "Week 11"
          }
        },
        {
          "id": "3",
          "type": 3,
          "name": "Postseason",
          "startDate": "2024-10-01T07:00:00.000+00:00",
          "endDate": "2024-12-11T07:59:00.000+00:00",
          "week": {}
        },
        {
          "id": "4",
          "type": 4,
          "name": "Off Season",
          "startDate": "2024-12-11T08:00:00.000+00:00",
          "endDate": "2025-02-15T07:59:00.000+00:00",
          "week": {}
        }
      ]
    },

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