ESPN hidden API Docs

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...

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

@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

@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": {}
        }
      ]
    },

@peteywhit now that the new season has "started", I am able to do something like

const currentSeason = await fetch(
  'https://site.api.espn.com/apis/common/v3/sports/football/college-football/season',
).then((res) => res.json())

const { year: currentSeasonYear } = currentSeason

const espnBody = await fetch(
  'https://site.api.espn.com/apis/common/v3/sports/football/college-football/seasons',
).then((res) => res.json())

const currentYearData = espnBody.seasons.find(
  (season: Season) => season.year === currentSeasonYear,
)

const regularSeasonWeeks = currentYearData.types.find(
  ({ type }: SeasonTypes) => type === 2,
).weeks

const currentWeek = regularSeasonWeeks.find((week: Week) => {
  const startDate = new Date(week.startDate)
  const endDate = new Date(week.endDate)
  return currentDate >= startDate && currentDate <= endDate
})

Although it would be nice to be able to do something like

https://site.api.espn.com/apis/common/v3/sports/football/college-football/season?seasontypes=2

or

https://site.api.espn.com/apis/common/v3/sports/football/college-football/season/seasontypes/2

I was trying to follow something similar to https://www.espn.com/college-football/schedule/_/week/1/year/2024/seasontype/2 but no dice. However, I did find

https://site.api.espn.com/apis/common/v3/sports/football/college-football/seasons?startingseason=2024

Which that is definitely better than getting back ALL seasons 😅 so going to play around with that and revise some of the code up above

Anyone have a beat on the ESPN Fantasy API? My previous calls are no longer working that point here: http://fantasy.espn.com/apis/v3/games/ffl/seasons

I would imagine they updated it somehow but I'm unable to source it. Any help would be appreciated!

Any ideas for Olympics API ? for medals or things like that

Also looking for Olympics APIs. So far, the only ones I found are individual ones for the major sports.

baseball/olympics-baseball
basketball/mens-olympics-basketball
basketball/womens-olympics-basketball
golf/mens-olympics-golf
golf/womens-olympics-golf
hockey/mens-olympic-hockey
hockey/womens-olympic-hockey
rubgy/282
soccer/fifa.olympics
soccer/fifa.w.olympics
tennis/atp
tennis/wta

Is there a risk that all this goes away? I'm curious to learn more about why this is even available and if it is safe to build off of. I know ESPN dropped support for developer API keys a while back so I question why they allow this. I have been using it for a while but have been waiting for the other shoe to drop so to speak.

anyone with a fixtures endpoint?

Anybody know if this is good to use for commercial purposes? Is it gonna all come tumbling down?

I wouldn't

…

On Mon, Aug 5, 2024 at 2:31 PM brandon wetzel ***@***.***> wrote: ***@***.**** commented on this gist. ------------------------------ Anybody know if this is good to use for commercial purposes? Is it gonna all come tumbling down? — Reply to this email directly, view it on GitHub <https://gist.github.com/akeaswaran/b48b02f1c94f873c6655e7129910fc3b#gistcomment-5144595> or unsubscribe <https://github.com/notifications/unsubscribe-auth/AANTBKKLIBFOBKJSJ5MNJQLZP7AJNBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDUOJ2WLJDOMFWWLO3UNBZGKYLEL5YGC4TUNFRWS4DBNZ2F6YLDORUXM2LUPGBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVA4DGOBXGIZTEMVHORZGSZ3HMVZKMY3SMVQXIZI> . You are receiving this email because you commented on the thread. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub> .

I am pulling NFL team schedules, the endpoint: https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/12/schedule?season=2024
only has the preseason for 2024, other years have the full regular season. Anyone know if the Regular season data is added after the preseason concludes?

I am pulling NFL team schedules, the endpoint: https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/12/schedule?season=2024 only has the preseason for 2024, other years have the full regular season. Anyone know if the Regular season data is added after the preseason concludes?

If you add &seasontype=2 it should show regular season data.
type 1 - preseason
2 - regular season
3 - postseason

I was sniffing the Network tab on the Olympic Medal Webpage and found this AJAX call: https://site.api.espn.com/apis/site/v2/scoreboard/activeSports?v=1&editionKey=espn-en&lang=en&region=us

That could be a good hint to the syntax of the sports.

I am pulling NFL team schedules, the endpoint: https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/12/schedule?season=2024 only has the preseason for 2024, other years have the full regular season. Anyone know if the Regular season data is added after the preseason concludes?

If you add &seasontype=2 it should show regular season data. type 1 - preseason 2 - regular season 3 - postseason

Lifesaver. Thank you!

I am pulling NFL team schedules, the endpoint: https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/12/schedule?season=2024 only has the preseason for 2024, other years have the full regular season. Anyone know if the Regular season data is added after the preseason concludes?

If you add &seasontype=2 it should show regular season data. type 1 - preseason 2 - regular season 3 - postseason

Lifesaver. Thank you!

You can see examples here in my AppScript https://docs.google.com/spreadsheets/d/18GZQQ7DPXBhBLtoRBBqNZV7KXVseVPB_udfyfU4K6vY/copy

I am pulling NFL team schedules, the endpoint: https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/12/schedule?season=2024 only has the preseason for 2024, other years have the full regular season. Anyone know if the Regular season data is added after the preseason concludes?

If you add &seasontype=2 it should show regular season data. type 1 - preseason 2 - regular season 3 - postseason

Lifesaver. Thank you!

You can see examples here in my AppScript https://docs.google.com/spreadsheets/d/18GZQQ7DPXBhBLtoRBBqNZV7KXVseVPB_udfyfU4K6vY/copy

Thanks man, just saw your reddit post too lol

@cermuel you can add ?enable=roster at the end of the url and the players will be under athletes.

For instance, if you're looking at Atlanta United FC in MLS, then your url would be: http://site.api.espn.com/apis/site/v2/sports/soccer/{usa.1}/teams/{18418}?enable=roster

The two items in brackets are based on which league and team you're looking at.

Any idea if it's possible to specify season too?

Any idea if it's possible to specify season too?

@EvanZ

You can also try this endpoint:
https://sports.core.api.espn.com/v2/sports/soccer/leagues/usa.1/seasons/2024/teams/18418/athletes/

Does anyone know why I only get 50 teams when running the one to get the college-football teams?

Does anyone know why I only get 50 teams when running the one to get the college-football teams?

It would help if you paste the url you’re using.

Does anyone know why I only get 50 teams when running the one to get the college-football teams?

It would help if you paste the url you’re using.

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

Does anyone know why I only get 50 teams when running the one to get the college-football teams?

It would help if you paste the url you’re using.

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

Add ?limit=500 to the end of the url.

?limit=500

awesome. thanks

Is it possible to find game by game live stats through this api...
var url = "https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?seasontype=1&week=" + weeknum + "&dates=2024"

I can get them through this api...
var url = "http://site.api.espn.com/apis/site/v2/sports/football/nfl/summary?event=" + gameId[k];

BUT, I'm trying to limit the number of times I call the api. I searched through all the objects that I could think of from the original url but I can't find all game stats, only game leaders and that's not enough.

Is there anyway to call the api ONE time for all the games for the current week?

Thanks!

Anyone know how to include FBS in this list of college scores?

http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=2024&week=1

Anyone know how to include FBS in this list of college scores?

http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=2024&week=1

https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=2024&week=1&groups=80

Group 80 is FBS schools.

Anyone know how to include FBS in this list of college scores?
http://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=2024&week=1

https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=2024&week=1&groups=80

Group 80 is FBS schools.

Excellent, thank you

does anyone know how to get different year rosters from this endpoint? &season={year} doesn't seem like it is doing anything. Still getting the current team rosters.

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

Anyone have a beat on the ESPN Fantasy API? My previous calls are no longer working that point here: http://fantasy.espn.com/apis/v3/games/ffl/seasons

I would imagine they updated it somehow but I'm unable to source it. Any help would be appreciated!

try adding " lm-api-reads. " in front of last years paths.

For example:

This...

https://fantasy.espn.com/apis/v3/games/ffl/seasons/2024/segments/0/leagues/[leagueID]?view=mMatchupScore&view=mStandings&view=mTeam"

would now be this...

https://lm-api-reads.fantasy.espn.com/apis/v3/games/ffl/seasons/2024/segments/0/leagues/[leagueID]?view=mMatchupScore&view=mStandings&view=mTeam"