Skip to content

Instantly share code, notes, and snippets.

@akeaswaran

akeaswaran/espn-api-docs.md

Last active July 10, 2026 20:48
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save akeaswaran/b48b02f1c94f873c6655e7129910fc3b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
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...

@apelt001

apelt001 commented Jul 12, 2025

Copy link
Copy Markdown

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

@BataBoom

BataBoom commented Jul 14, 2025

Copy link
Copy Markdown

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

propsdaily commented Jul 14, 2025

Copy link
Copy Markdown

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

KHarper1993 commented Jul 14, 2025

Copy link
Copy Markdown

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

daniyalmaster693 commented Jul 15, 2025 •
edited
Loading

Copy link
Copy Markdown

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

propsdaily commented Jul 15, 2025

Copy link
Copy Markdown

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

bluemad commented Jul 27, 2025

Copy link
Copy Markdown

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

KevinDuganJr commented Jul 27, 2025

Copy link
Copy Markdown

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

gabebadooky commented Aug 18, 2025

Copy link
Copy Markdown

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

vasqued2 commented Aug 18, 2025

Copy link
Copy Markdown

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

peteywhit commented Aug 18, 2025

Copy link
Copy Markdown

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

@daniyalmaster693

daniyalmaster693 commented Aug 19, 2025

Copy link
Copy Markdown

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

daniyalmaster693 commented Aug 20, 2025

Copy link
Copy Markdown

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

daniyalmaster693 commented Aug 22, 2025

Copy link
Copy Markdown

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

seanrco commented Aug 23, 2025 •
edited
Loading

Copy link
Copy Markdown

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:

Or specify a particular Conference ID aka Group ID:

To find group ID:

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

Date (Range) Param

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

8uzNxWvITu

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

Questions

@ischmidt20

ischmidt20 commented Aug 24, 2025

Copy link
Copy Markdown

@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

newadventure079 commented Aug 27, 2025

Copy link
Copy Markdown

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!

@JamesSingleton

JamesSingleton commented Sep 5, 2025

Copy link
Copy Markdown

Is there a way to get Men's and Women's College Basketball week data? For example, https://site.api.espn.com/apis/common/v3/sports/football/college-football/seasons?startingseason=2023 will give me a weeks array with the number and their start and end date. However, https://site.api.espn.com/apis/common/v3/sports/basketball/mens-college-basketball/seasons?startingseason=2023 does not give me any of that data.

@ischmidt20

ischmidt20 commented Sep 6, 2025

Copy link
Copy Markdown

@JamesSingleton No, the scoreboard for college basketball (and probably for every sport other than football) is based on days, not weeks, so ESPN does not provide that information

@JamesSingleton

JamesSingleton commented Sep 6, 2025

Copy link
Copy Markdown

@JamesSingleton No, the scoreboard for college basketball (and probably for every sport other than football) is based on days, not weeks, so ESPN does not provide that information

I was able to find it https://sports.core.api.espn.com/v2/sports/basketball/leagues/mens-college-basketball/seasons/2025/types/2/weeks

I’m using this for rankings and ESPN also has a rankings page that’s split into weeks. I wish there was an official NCAA endpoint to hit though.

@JamesSingleton

JamesSingleton commented Sep 8, 2025

Copy link
Copy Markdown

For college football, is there a way to get stat leaders per week of the season?

@cyberautomate

cyberautomate commented Sep 9, 2025

Copy link
Copy Markdown

Anyone know of any documentation for these API endpoints? How do you find them?

@davidbti

davidbti commented Sep 9, 2025 via email

Copy link
Copy Markdown

@cyberautomate

cyberautomate commented Sep 9, 2025

Copy link
Copy Markdown

What method are you using to discover these endpoints when/if they change? Anyone have a tutorial?

@newadventure079

newadventure079 commented Sep 9, 2025

Copy link
Copy Markdown

@cyberautomate You find them by using a network sniffer. There is not documentation.

@ITIRadio

ITIRadio commented Sep 14, 2025 •
edited
Loading

Copy link
Copy Markdown

Significant Updates to my Box Score, and now, SQLite ESPN API utilities:

As has been requested here for years, a way to access the API one time for each game, and then save the data to a local database, I have posted an NFL box score to SQLite database conversion utility:

ESPN-API Github

Check the readme for instructions and an example query. Also, there have been a lot of updates in the NFL API this season, so hopefully my commit isn't super-late.

@JaredCH

JaredCH commented Sep 18, 2025

Copy link
Copy Markdown

site.web.api.espn.com/apis/personalized/v2/scoreboard/header?sport=basketball&league=nba&region=us&lang=en&contentorigin=espn&configuration=STREAM_MENU&platform=web&features=sfb-all%2Ccutl&buyWindow=1m&showAirings=buy%2Clive%2Creplay&showZipLookup=true&tz=America%2FNew_York&postalCode=78666&authNetworks=espn3&playabilitySource=playbackId

site.web.api.espn.com/apis/common/v3/sports/basketball/nba/athletes/2991235/stats?region=us&lang=en&contentorigin=espn

@rozeren

rozeren commented Sep 20, 2025

Copy link
Copy Markdown

Just a question, is there anyone knowing how long delay it is between espn update and Real time update. When i run this in a while loop its still slower then what i can see on my tv, this was with PL, i do have some latency but it should not be that long : GOAL DETECTED! (Latency: 194ms)

@dargo01

dargo01 commented Sep 21, 2025

Copy link
Copy Markdown

For college football, is there a way to get stat leaders per week of the season?

Seconding this, if anyone has any ideas.

@cory5490

cory5490 commented Sep 23, 2025

Copy link
Copy Markdown

is there anyone who can help me figure out how to get the league table from here

https://www.espn.com/rugby/table/_/league/270559

Ive tried
https://site.api.espn.com/apis/site/v2/sports/rugby/270559/table/
https://site.api.espn.com/apis/site/v2/sports/rugby_league/270559/table/
https://site.api.espn.com/apis/site/v2/sports/rugby/270559/standings
(only one that does not return a 404 this is what I see
{
"fullViewLink": {
"text": "Full Standings"
}
})
So I think I am close with the 3rd option but missing something

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