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

@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