akeaswaran/espn-api-docs.md

Last active December 9, 2025 09:16

Star (924) You must be signed in to star a gist
Fork (144) You must be signed in to fork a gist

Select an option

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

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!

JamesSingleton commented Sep 5, 2025

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 commented Sep 6, 2025

@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 commented Sep 6, 2025

@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 commented Sep 8, 2025

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

cyberautomate commented Sep 9, 2025

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

davidbti commented Sep 9, 2025 via email

Is there an endpoint or just a list that would list all of the status available for college football competitions?

…

On Fri, Aug 22, 2025 at 8:17 PM Sean C. ***@***.***> wrote: ***@***.**** commented on this gist. ------------------------------ 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 conferences 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: 1. Go to: https://www.espn.com/college-football/scoreboard 2. Filter by group / conference and record group id from URL: bKKaRRAiTH.png (view on web) <https://gist.github.com/user-attachments/assets/b2c155c2-b0ff-49a9-acf6-80a8da61ccb6> *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: 8uzNxWvITu.png (view on web) <https://gist.github.com/user-attachments/assets/47e00262-db1c-47e2-aabf-918ad2b3943d> *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. — Reply to this email directly, view it on GitHub <https://gist.github.com/akeaswaran/b48b02f1c94f873c6655e7129910fc3b#gistcomment-5731301> or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHGUPHBTB2RKEQQ5M5FOAL3O66LTBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDUOJ2WLJDOMFWWLO3UNBZGKYLEL5YGC4TUNFRWS4DBNZ2F6YLDORUXM2LUPGBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVA4DGOBXGIZTEMVHORZGSZ3HMVZKMY3SMVQXIZI> . 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> .

-- * David Pilkinton* *VP of Development* Business Technology, INC. <http://www.bti.tv> 301 Mallory Station Rd. Franklin, TN. 37067 *T. 615-591-1900* *F. 615-591-1909*

------------------------------ *Disclaimer: This electronic message may contain information that is Proprietary, Confidential, or legally privileged or protected. It is intended only for the use of the individual(s) and entity named in the message. If you are not an intended recipient of this message, please notify the sender immediately and delete the material from your computer. Do not deliver, distribute or copy this message and do not disclose its contents or take any action in reliance on the information it contains.* ------------------------------

-- _Disclaimer: This electronic message may contain information that is Proprietary, Confidential, or legally privileged or protected. It is intended only for the use of the individual(s) and entity named in the message. If you are not an intended recipient of this message, please notify the sender immediately and delete the material from your computer. Do not deliver, distribute or copy this message and do not disclose its contents or take any action in reliance on the information it contains._

cyberautomate commented Sep 9, 2025

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

newadventure079 commented Sep 9, 2025

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

ITIRadio commented Sep 14, 2025 •

edited

Loading

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 commented Sep 18, 2025

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 commented Sep 20, 2025

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 commented Sep 21, 2025

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

Seconding this, if anyone has any ideas.

cory5490 commented Sep 23, 2025

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

Sergi0 commented Sep 26, 2025

Is there a way to get team's results and schedule for all tournaments?
Team's page has these two links:
https://www.espn.com/soccer/team/fixtures/_/id/363/chelsea
https://www.espn.com/soccer/team/results/_/id/363/chelsea

but it's not API. I wonder if I can get an API url, like for injures
http://sports.core.api.espn.com/v2/sports/soccer/leagues/eng.1/teams/363/injuries?lang=en&region=us

I don't want to get just one leagues results, I want to see all the matches, including national cups and leagues

drcs2000 commented Oct 1, 2025

Is there a way to get team's results and schedule for all tournaments? Team's page has these two links: https://www.espn.com/soccer/team/fixtures/_/id/363/chelsea https://www.espn.com/soccer/team/results/_/id/363/chelsea

but it's not API. I wonder if I can get an API url, like for injures http://sports.core.api.espn.com/v2/sports/soccer/leagues/eng.1/teams/363/injuries?lang=en&region=us

I don't want to get just one leagues results, I want to see all the matches, including national cups and leagues

You gotta do something like that to get all the future matches from an specific team in all competitions:

http://site.api.espn.com/apis/site/v2/sports/soccer/all/teams/363/schedule?fixture=true

Now, to get all already played matches from all competitions you delete the ?fixture=true like that:

http://site.api.espn.com/apis/site/v2/sports/soccer/all/teams/363/schedule

ganicus commented Oct 7, 2025

Any websockets?

Sergi0 commented Oct 25, 2025

Now, to get all already played matches from all competitions you delete the ?fixture=true like that:

http://site.api.espn.com/apis/site/v2/sports/soccer/all/teams/363/schedule

you're a life saver! this works perfectly, thanks.

I used events API, but it requires an API call for everything, including other team's name and even scores for each team separately.
it was extremely slow even with the date filter.
https://sports.core.api.espn.com/v2/sports/soccer/teams/364/events

tarunramO7 commented Nov 6, 2025

Do we have cricket api?

tacrec commented Nov 16, 2025

Is there an API for college team colors? ESPN has colors in their pro API but not college. They somehow have the team colors behind the logos on their score pages: https://www.ncaa.com/game/6459550

gabebadooky commented Nov 16, 2025

Is there an API for college team colors? ESPN has colors in their pro API but not college. They somehow have the team colors behind the logos on their score pages: https://www.ncaa.com/game/6459550

That is captured in the "color" and "alternateColor" properties of the Team endpoint!

tacrec commented Nov 17, 2025

Is there an API for college team colors? ESPN has colors in their pro API but not college. They somehow have the team colors behind the logos on their score pages: https://www.ncaa.com/game/6459550

That is captured in the "color" and "alternateColor" properties of the Team endpoint!

Cool thanks!

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

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

Current Behavior

Ideal vs. Actual Data Structure

API URLs

What I Want

Question

Uh oh!

JamesSingleton commented Sep 5, 2025

Uh oh!

ischmidt20 commented Sep 6, 2025

Uh oh!

JamesSingleton commented Sep 6, 2025

Uh oh!

JamesSingleton commented Sep 8, 2025

Uh oh!

cyberautomate commented Sep 9, 2025

Uh oh!

davidbti commented Sep 9, 2025 via email

Uh oh!

cyberautomate commented Sep 9, 2025

Uh oh!

newadventure079 commented Sep 9, 2025

Uh oh!

ITIRadio commented Sep 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JaredCH commented Sep 18, 2025

Uh oh!

rozeren commented Sep 20, 2025

Uh oh!

dargo01 commented Sep 21, 2025

Uh oh!

cory5490 commented Sep 23, 2025

Uh oh!

Sergi0 commented Sep 26, 2025

Uh oh!

drcs2000 commented Oct 1, 2025

Uh oh!

ganicus commented Oct 7, 2025

Uh oh!

Sergi0 commented Oct 25, 2025

Uh oh!

tarunramO7 commented Nov 6, 2025

Uh oh!

tacrec commented Nov 16, 2025

Uh oh!

gabebadooky commented Nov 16, 2025

Uh oh!

tacrec commented Nov 17, 2025

Uh oh!

seanrco commented Aug 23, 2025 •

edited

Loading

ITIRadio commented Sep 14, 2025 •

edited

Loading