akeaswaran/espn-api-docs.md

Last active September 5, 2025 00:21

Star (866) You must be signed in to star a gist
Fork (132) You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/akeaswaran/b48b02f1c94f873c6655e7129910fc3b.js"></script>
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

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

lemonaidlabs commented May 22, 2025

http://site.api.espn.com/apis/site/v2/sports/golf/pga/scoreboard

wanted to share golf into this mix shall anyone be looking for it.

nwbarkeriu commented Jun 2, 2025

Does anyone have the minor league baseball endpoint?

BStenfors9119 commented Jun 2, 2025

Out of curiosity, does anyone know if the api for the schedules has changed?

In the past I have been using the following to pull an entire schedule for a specific team.

https://site.api.espn.com/apis/site/v2/sports/football/college-football/teams/2306/schedule?season=2025

But right now the events array just comes back empty.

Any ideas or suggestions?

TIA

jgazick commented Jun 26, 2025

Women's college soccer:

Women's college volleyball

propsdaily commented Jun 26, 2025

Out of curiosity, does anyone know if the api for the schedules has changed?

In the past I have been using the following to pull an entire schedule for a specific team.

https://site.api.espn.com/apis/site/v2/sports/football/college-football/teams/2306/schedule?season=2025

But right now the events array just comes back empty.

Any ideas or suggestions?

TIA

@BStenfors9119 Try passing in a season type:
https://site.api.espn.com/apis/site/v2/sports/football/college-football/teams/2306/schedule?season=2025&seasontype=2

BStenfors9119 commented Jun 27, 2025

Out of curiosity, does anyone know if the api for the schedules has changed?
In the past I have been using the following to pull an entire schedule for a specific team.
https://site.api.espn.com/apis/site/v2/sports/football/college-football/teams/2306/schedule?season=2025
But right now the events array just comes back empty.
Any ideas or suggestions?
TIA

@BStenfors9119 Try passing in a season type: https://site.api.espn.com/apis/site/v2/sports/football/college-football/teams/2306/schedule?season=2025&seasontype=2

Thank you so much @propsdaily !! This is huge!! 🔥❤️

seanrco commented Jun 28, 2025

In the scoreboard endpoints for each individual sport (ex: https://site.api.espn.com/apis/site/v2/sports/baseball/mlb/scoreboard) does anyone know all the possible values for event status name (see below)?

The values I am aware of:

STATUS_SCHEDULED
STATUS_IN_PROGRESS
STATUS_FINAL

The reason I am asking is I would like to filter out any events that are postponed, cancelled, etc., but have not noticed if those are the only possible values or not. Thanks!

lemonaidlabs commented Jul 11, 2025

Has anyone else noticed the in-game updates for MLB now seem to be updated at the end of each at-bat rather than after each pitch. As a result, the count isn't updated. Just checking to see if anyone is seeing balls and strikes come through this year.

I have balls and strikes etc -- Might be a change of something there you want to check.

lemonaidlabs commented Jul 11, 2025 •

edited

Loading

In the scoreboard endpoints for each individual sport (ex: https://site.api.espn.com/apis/site/v2/sports/baseball/mlb/scoreboard) does anyone know all the possible values for event status name (see below)?

The values I am aware of:

STATUS_SCHEDULED

STATUS_IN_PROGRESS

STATUS_FINAL

The reason I am asking is I would like to filter out any events that are postponed, cancelled, etc., but have not noticed if those are the only possible values or not. Thanks!

STATUS_POSTPONED = rail delayed etc just confirmed.

lemonaidlabs commented Jul 11, 2025

I'm looking for suggestions gathering games for all weeks of NFL season upcoming

https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard

this is the baseline url, now i was trying to get games for week 2, 3 etc. I have tried adding season type but havent found success. Any help, many thanks

BataBoom commented Jul 11, 2025

I'm looking for suggestions gathering games for all weeks of NFL season upcoming

https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard

this is the baseline url, now i was trying to get games for week 2, 3 etc. I have tried adding season type but havent found success. Any help, many thanks

https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?seasontype=2&week=1&dates=2025

Change seasontype to 1 if you want preseason.

lemonaidlabs commented Jul 11, 2025

Many thanks for this so quickly -

aaronweldy commented Jul 12, 2025

If anyone's interested: I've gotten pretty far with creating an OpenAPI spec for ~200 endpoints that I've found: https://github.com/aaronweldy/espn-openapi
Fully typed-out definitions for all of the endpoints listed here.

apelt001 commented Jul 12, 2025

Does anyone know the league parameter name for NBA summer league?

BataBoom commented Jul 14, 2025

If anyone's interested: I've gotten pretty far with creating an OpenAPI spec for ~200 endpoints that I've found: https://github.com/aaronweldy/espn-openapi Fully typed-out definitions for all of the endpoints listed here.

Fire! Very cool.

Also wondering if anyone has a param for NBA summer league

propsdaily commented Jul 14, 2025

Does anyone know the league parameter name for NBA summer league?

@apelt001 @BataBoom It looks like they separate leagues out by region, for reference you can check all leagues here:
https://sports.core.api.espn.com/v2/sports/basketball/leagues

KHarper1993 commented Jul 14, 2025

I am trying to load college basketball player data (GP, MIN, PTS, etc) from prior years (the same thing that you can see on the team stats pages for prior years, https://www.espn.com/womens-college-basketball/team/stats/_/id/2294/season/2023). In the API team data I see only this season, and not really all of the player data I'm looking for and if I add a query for prior season it doesn't seem to chagne the data. Any idea how I can get prior year stats for players?

I know this is a little late but better late then ever. So i did something similar for mens colleage and created a loop to get whatever matups to a certain point

' current_year = date.today().year
year = current_year -1
matchup_data = []

while year >= 2024:  #You can do it to whatever year you would like here
    # Define season start and end dates for the given year
    start_date = date(year, 11, 4)  # Typically around early November
    end_date = date(year + 1, 3, 9)  # Typically around early March

    # Generate each day in the season date range
    current_date = start_date
    while current_date <= end_date:
        date_str = current_date.strftime("%Y%m%d")  # Format date as YYYYMMD

        url = f"https://site.api.espn.com/apis/site/v2/sports/basketball/mens-college-basketball/scoreboard?dates={date_str}"
       #change to your url for women 
        try:
            response = requests.get(url)
            response.raise_for_status()
            data = response.json()
        except requests.exceptions.RequestException as e:
            print(f"Error fetching scoreboard data for {date_str}: {e}")
            current_date += timedelta(days=1)
            continue`

This worked for me as I was building my algo out for men so hopefully this helps you with your analytics.

daniyalmaster693 commented Jul 15, 2025 •

edited

Loading

Can someone tell me all the available leagues, this api doesn't seem to cover all of them: https://site.api.espn.com/apis/site/v2/scoreboard/activeSports?v=1&editionKey=espn-en&lang=en&region=us

propsdaily commented Jul 15, 2025

Can someone tell me all the available leagues, this api doesn't seem to cover all of them: https://site.api.espn.com/apis/site/v2/scoreboard/activeSports?v=1&editionKey=espn-en&lang=en&region=us

@daniyalmaster693 You can view all sports on this endpoint:
https://sports.core.api.espn.com/v2/sports

And then if you go a bit deeper, for each sport you can view leagues
https://sports.core.api.espn.com/v2/sports/basketball/leagues

bluemad commented Jul 27, 2025

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.

Hi @KevinDuganJr can you go into some detail on what you did. Sorry if this is a stupid question, I'm still very much a programming beginner.
Thanks

KevinDuganJr commented Jul 27, 2025

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.

Hi @KevinDuganJr can you go into some detail on what you did. Sorry if this is a stupid question, I'm still very much a programming beginner. Thanks

You create classes that your application will use. Let's say you're doing Schedule so you would have at least a Schedule class and Team class. Then you use the API to populate the properties of those classes. If you have an ongoing project, I could try to help guide you. I'm afraid I'm not good at wiring everything up in a chat window though haha.

gabebadooky commented Aug 18, 2025

Did anyone else observe that only the Iowa State/Kansas State game is returning college football SCOREBOARD endpoint for this Saturday, 8/23 (query parameter week=1)? Is this anticipated functionality once we are in the current "game week"?

vasqued2 commented Aug 18, 2025

Did anyone else observe that only the Iowa State/Kansas State game is returning college football SCOREBOARD endpoint for this Saturday, 8/23 (query parameter week=1)? Is this anticipated functionality once we are in the current "game week"?

It used to just return ranked teams by default unless you specified a group.

peteywhit commented Aug 18, 2025

Did anyone else observe that only the Iowa State/Kansas State game is returning college football SCOREBOARD endpoint for this Saturday, 8/23 (query parameter week=1)? Is this anticipated functionality once we are in the current "game week"?

You're seeing this because it's the only game this week.

daniyalmaster693 commented Aug 19, 2025

Did anyone else observe that only the Iowa State/Kansas State game is returning college football SCOREBOARD endpoint for this Saturday, 8/23 (query parameter week=1)? Is this anticipated functionality once we are in the current "game week"?

I was able to get it show all games when adding a date parameter:

https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=20250817-20250831

daniyalmaster693 commented Aug 20, 2025

Does anyone know how to access driver stats for f1? This api doesn't have driver stats: https://site.api.espn.com/apis/site/v2/sports/racing/f1/scoreboard?dates=20250803

daniyalmaster693 commented Aug 22, 2025

Does anyone know how to access driver stats for f1? This api doesn't have driver stats: https://site.api.espn.com/apis/site/v2/sports/racing/f1/scoreboard?dates=20250803

For anyone who has the same issue, this api gives you access to pits taken, player headshots, race times, player countries, vehicle makes and more. https://site.web.api.espn.com/apis/personalized/v2/scoreboard/header?sport=racing&league=f1&dates=20250803

seanrco commented Aug 23, 2025 •

edited

Loading

College Football Scoreboard Endpoint

For anyone else noticing that the College Football Scoreboard API endpoint (https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard) only outputs top 25 events by default - below are some options if you want to retrieve other events:

Groups Param

Get all FBS (aka Division I-A) events:

FBS (formerly known as Division I-A)
- https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?groups=80
- This covers all FBS (Div 1 schools) scheduled events - for most part this covers all events.

Or specify a particular Conference ID aka Group ID:

SEC
- https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?groups=8
- This will return all scheduled events for SEC.
Big 12
- https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?groups=4
- This will return all scheduled events for Big 12.

To find group ID:

Go to: https://www.espn.com/college-football/scoreboard
Filter by group / conference and record group id from URL:

Date (Range) Param

Week 1 (all events)
- https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=20250823-20250902
Week 2 (all events)
- https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?dates=20250902-20250908

If you wanted to get weekly date ranges by code you could use the default scoreboard API endpoint calendar entries:

Summary
Hope this helps others out and thanks for other users that posted info that helped me summarize this up in a comment.

Questions

Anyone know if it's possible to chain groups together? (ex that doesn't work https://site.api.espn.com/apis/site/v2/sports/football/college-football/scoreboard?groups=8,4)
Anyone know of any other undocumented params that would work to retrieve all events? I tried 'weeks' (weeks=1) or 'week' (week=1) and didn't work.

ischmidt20 commented Aug 24, 2025

@Bobsilvio You can use this endpoint: https://site.api.espn.com/apis/site/v2/sports/soccer/all/scoreboard

And then if you want a specific date: https://site.api.espn.com/apis/site/v2/sports/soccer/all/scoreboard?dates=20250215

Replace "all" with the actual league to get specific leagues, ie: eng.1 for EPL

Is there any way to get the entire ESPN soccer storyboard but also return the league (e.g., "eng.1") for each game?

When I use all, the leagues entry in the result is empty. The individual events do not have a league parameter, unless the game has not yet begun in which case it will be included with the betting information. The closest I can get is the season parameter for each event, which looks like this:

"season":{"year":2025,"type":13481,"slug":"2025-26-english-premier-league"}

But I do not have a crosswalk between either the type or slug and the league code.

A couple years ago I was able to use https://secure.espn.com/soccer/scoreboard/_/league/all/date/{date}?xhr=1 but that now always returns an HTML result rather than JSON.

newadventure079 commented Aug 27, 2025

Cannot Tell if Picks are made for College Pick 'em or Pigskin Pick 'em Current Week via ESPN Pick'em API

Problem Summary

I'm using ESPN's Pick'em API to track user picks for challenges like NFL Pigskin Pick'em and College Football Pick'em.

The core issue:
I need to know, each week, whether a user has made their picks before the games start. However, the way the API is structured makes this difficult once the season has started.

Current Behavior

Before Week 1:
- If .picks doesn’t exist: The user hasn’t made any picks.
- If .picks exists but is empty: The user has submitted picks, but the pick data isn’t available until the games start.
After Week 1 & Throughout the Season:
- The .picks array is a flat list with all picks for the season added as games begin.
- There’s no breakdown by week (no .picks.week2, .picks.week3, etc.).
- For example:
  - Just before Week 2, .picks for everyone has 16 entries from Week 1.
  - There are no empty or null entries for future weeks.
  - As Week 2 games start, new picks are revealed, and the array grows (17, 18, 19, ...).
  - There's no way to tell ahead of time if someone has made their picks for the upcoming week; you only find out after kickoff, when it’s too late for users to make the picks for the week.

Ideal vs. Actual Data Structure

Ideal structure (week-by-week distinction):

{
  "picks": {
    "week1": [...],
    "week2": [...],
    // etc.
  }
}

Actual structure (flat array, no week info):

{
  "picks": [
    {...}, // week 1
    {...}, // week 1
    // ... (only fills as games start, no separation by week)
  ]
}

API URLs

College Football Pick'em:
https://gambit-api.fantasy.espn.com/apis/v1/challenges/college-football-pickem-2025/entries/{user_guid}
NFL Pigskin Pick'em:
https://gambit-api.fantasy.espn.com/apis/v1/challenges/nfl-pigskin-pickem-2025/entries/{user_guid}

What I Want

Is there any way, using the current ESPN Pick'em API, to determine before kickoff whether a user has or hasn't made their picks for a given week during the season?

Right now, I can only detect an empty/null picks list at the very start of the season (before Week 1).
After that, the .picks array grows each week, and there's no way to distinguish “not made picks for this week yet” from simply “picks for this week aren’t public yet”—until it’s already too late.

Before the pick ems site redesign a few years ago, ESPN provided this information. If you viewed a person's picks entry, it would say "Chuck has not made their picks yet", but this functionality was removed in the redesign

Question

Is this a current limitation of the API, or is there a workaround to detect per-week pick completion before games start?

Thank you!

akeaswaran/espn-api-docs.md

ESPN's hidden API endpoints

Football

College Football

NFL

Baseball

MLB

College Baseball

Hockey

Basketball

NBA

WNBA

Women's College Basketball

Men's College Basketball

Soccer

lemonaidlabs commented May 22, 2025

Uh oh!

nwbarkeriu commented Jun 2, 2025

Uh oh!

BStenfors9119 commented Jun 2, 2025

Uh oh!

jgazick commented Jun 26, 2025

Uh oh!

propsdaily commented Jun 26, 2025

Uh oh!

BStenfors9119 commented Jun 27, 2025

Uh oh!

seanrco commented Jun 28, 2025

Uh oh!

lemonaidlabs commented Jul 11, 2025

Uh oh!

lemonaidlabs commented Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lemonaidlabs commented Jul 11, 2025

Uh oh!

BataBoom commented Jul 11, 2025

Uh oh!

lemonaidlabs commented Jul 11, 2025

Uh oh!

aaronweldy commented Jul 12, 2025

Uh oh!

apelt001 commented Jul 12, 2025

Uh oh!

BataBoom commented Jul 14, 2025

Uh oh!

propsdaily commented Jul 14, 2025

Uh oh!

KHarper1993 commented Jul 14, 2025

Uh oh!

daniyalmaster693 commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

propsdaily commented Jul 15, 2025

Uh oh!

bluemad commented Jul 27, 2025

Uh oh!

KevinDuganJr commented Jul 27, 2025

Uh oh!

gabebadooky commented Aug 18, 2025

Uh oh!

vasqued2 commented Aug 18, 2025

Uh oh!

peteywhit commented Aug 18, 2025

Uh oh!

daniyalmaster693 commented Aug 19, 2025

Uh oh!

daniyalmaster693 commented Aug 20, 2025

Uh oh!

daniyalmaster693 commented Aug 22, 2025

Uh oh!

seanrco commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

College Football Scoreboard Endpoint

Uh oh!

ischmidt20 commented Aug 24, 2025

Uh oh!

newadventure079 commented Aug 27, 2025

Cannot Tell if Picks are made for College Pick 'em or Pigskin Pick 'em Current Week via ESPN Pick'em API

Problem Summary

lemonaidlabs commented Jul 11, 2025 •

edited

Loading

daniyalmaster693 commented Jul 15, 2025 •

edited

Loading

seanrco commented Aug 23, 2025 •

edited

Loading