Zuplo
Learning Center
APIs

Unlocking ESPN's Hidden API: a Developer's Guide

Adrian MachadoAdrian Machado
October 1, 2024
7 min read

ESPN's hidden REST API powers their site and apps — and you can use it too. Endpoints, rate-limit behavior, sample requests, and production caveats.

In sports data, ESPN stands as a titan, offering a wealth of information that developers crave. While ESPN doesn’t officially provide a public API, the developer community has reverse-engineered a “hidden” API that powers ESPN’s own website and mobile apps. This guide walks through the endpoints you can call today, the query parameters that shape results, the reliability and rate-limit realities you need to plan for, and how to wrap the whole thing in an API gateway so your project doesn’t break when ESPN changes something overnight.

ESPN: The Sports Data Powerhouse

ESPN, short for Entertainment and Sports Programming Network, has become synonymous with sports coverage. From live broadcasts to in-depth analysis and breaking news, ESPN’s multi-channel presence across television, web, and mobile platforms makes it an invaluable resource for sports enthusiasts worldwide. Under the hood, ESPN’s digital properties pull from a set of internal JSON APIs — and those APIs are accessible to anyone who knows the URLs.

Revealing the Hidden API

The ESPN hidden API, documented by developers in various GitHub repositories [1,2,3] and projects, provides programmatic access to ESPN’s extensive sports data. This API offers real-time scores, detailed player and team statistics, news articles, and up-to-date league standings. No API key, authentication token, or sign-up is required — you simply send a GET request and receive JSON.

The API’s strengths lie in its comprehensive data coverage and real-time updates, making it an attractive option for developers looking to create dynamic sports applications. However, its unofficial status means there is no guarantee of long-term stability or support. Developers must be prepared for potential changes without notice and should implement strong error handling in their applications.

Does ESPN Offer an OpenAPI/Swagger Specification?

Unfortunately, there is no official documentation for the hidden API. We have decided to create an unofficial OpenAPI specification for the ESPN hidden API — and welcome your support in filling it out.

Sample Endpoints: Scores, Schedules, and Team Data

The hidden ESPN API is organized around two main base URLs. The site API (site.api.espn.com) returns rich, pre-assembled responses, while the core API (sports.core.api.espn.com) exposes more granular data with $ref links you follow for details. For most use cases the site API is the better starting point.

The general URL pattern follows a clean, resource-oriented structure. If you are building your own APIs, you might find our guide on REST API naming conventions helpful for understanding why ESPN’s URL design works well.

Scoreboards and Live Scores

The scoreboard endpoint is the most commonly used. It returns current or historical game data for a given sport and league:

Terminalsh
# NFL scoreboard — today's games
curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard"

# NBA scoreboard for a specific date
curl "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard?dates=20260120"

# English Premier League soccer
curl "https://site.api.espn.com/apis/site/v2/sports/soccer/eng.1/scoreboard"

The response includes an events array where each event contains competitors, scores by period, venue details, broadcast information, and game status (scheduled, in-progress, or final).

Team Information and Rosters

You can list all teams for a league or fetch details for a specific team by ID:

Terminalsh
# List all NFL teams
curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams"

# Get a specific team (e.g., Green Bay Packers, ID 9)
curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/9"

# Team roster
curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/9/roster"

Schedules and Standings

Team schedules require a team ID and an optional season filter. A common gotcha: the schedule endpoint can return an empty events array unless you pass the seasontype parameter explicitly (1 = preseason, 2 = regular season, 3 = postseason).

Terminalsh
# Team schedule with season type
curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/9/schedule?season=2025&seasontype=2"

# League standings (note: uses /apis/v2/, not /apis/site/v2/)
curl "https://site.api.espn.com/apis/v2/sports/basketball/nba/standings"

News Headlines

Terminalsh
# NFL headlines
curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/news"

# News for a specific athlete (by player ID)
curl "https://site.api.espn.com/apis/site/v2/sports/football/nfl/news?athlete=4241479"

Node.js Implementation

TypeScripttypescript
const response = await fetch(
  "https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard",
);
const data = await response.json();

for (const event of data.events) {
  const [away, home] = event.competitions[0].competitors;
  console.log(
    `${away.team.displayName} ${away.score} @ ${home.team.displayName} ${home.score}`,
  );
}

Python Implementation

python
import requests

url = "https://site.api.espn.com/apis/site/v2/sports/basketball/nba/scoreboard"
resp = requests.get(url, params={"dates": "20260120"})
data = resp.json()

for event in data["events"]:
    competition = event["competitions"][0]
    teams = competition["competitors"]
    home = next(t for t in teams if t["homeAway"] == "home")
    away = next(t for t in teams if t["homeAway"] == "away")
    status = competition["status"]["type"]["description"]
    print(f"{away['team']['displayName']} {away['score']} @ "
          f"{home['team']['displayName']} {home['score']} — {status}")

Useful Query Parameters

The API supports several query parameters that shape the response:

  • dates — filter by date (YYYYMMDD) or date range (YYYYMMDD-YYYYMMDD)
  • season — season year (e.g., 2025)
  • seasontype — 1 preseason, 2 regular, 3 postseason
  • week — week number within the season (football)
  • limit — max results returned (e.g., 365)
  • groups — broadens scope; use 50 for all Division I college basketball games

Supported Sports

The API covers 17+ sports. Common league identifiers include nfl, college-football, nba, wnba, mens-college-basketball, mlb, nhl, eng.1 (Premier League), usa.1 (MLS), ufc, f1, and pga.

Rate Limits and Reliability

Because these endpoints are undocumented, ESPN publishes no official rate limits or uptime guarantees. Here is what the developer community has learned:

  • Rate limiting is opaque. There is no published threshold, but developers who hammer endpoints with bulk requests report eventual blocks. A safe starting point is to avoid polling more frequently than once every 30–60 seconds for live scores. If you are building an application that needs to handle API rate limit exceeded errors, implement retry logic with exponential backoff.
  • Endpoints can change without notice. ESPN has moved base URLs before — the Fantasy API migrated from fantasy.espn.com to lm-api-reads.fantasy.espn.com around April 2024, breaking existing integrations overnight.
  • Response structure varies by sport. Fields present in the NFL response may be absent or nested differently in the soccer response. Defensive parsing is essential.
  • Latency is near-real-time, not instant. Scores update slightly behind the live broadcast. One community benchmark measured roughly 200 ms of lag for soccer scores relative to the TV feed.

Wrapping the Hidden API With an API Gateway

The hidden API’s lack of guarantees makes it risky to call directly from production code. A better architecture is to place an API gateway in front of ESPN’s endpoints. This gives you control over caching, rate limiting, monitoring, and error handling without modifying your application code every time ESPN changes something.

With Zuplo, you can set up a gateway in minutes:

  • Caching — Use the Caching policy to cache ESPN responses and reduce redundant calls. Completed game data never changes, so you can set long TTLs for final scores and shorter ones for in-progress games.
  • Rate limiting — The Rate Limiting policy lets you throttle requests to ESPN so you stay well below whatever hidden threshold triggers a block. You can also expose your own rate-limited API to downstream consumers.
  • Monitoring and logging — Route all ESPN traffic through the gateway and you get structured API logging out of the box. When an endpoint starts returning errors, you will know immediately instead of discovering it from user complaints.
  • Custom error handling — Write a custom outbound policy in TypeScript to catch 5xx or unexpected responses from ESPN and return a graceful fallback to your clients.

This approach means your frontend or mobile app only ever talks to your gateway URL. If ESPN changes an endpoint path, you update one route configuration instead of every client.

ESPN Hidden API vs. Official Sports Data Providers

The hidden API is appealing because it is free and requires no sign-up, but it is not the only option. Here is how it compares to popular paid alternatives:

ESPN Hidden API — Free, no authentication, broad coverage of 20+ sports, but zero documentation, no SLA, and endpoints can break at any time. Best for personal projects, prototypes, and learning.

Sportradar — The industry leader with official league partnerships. Covers 80+ sports with sub-second real-time data, advanced analytics, and enterprise SLAs. Pricing starts well above $10,000 per month, making it realistic only for media companies and sportsbooks.

MySportsFeeds — Free for non-commercial use with paid tiers for production. Covers NFL, NBA, MLB, NHL, and NCAA Basketball with solid depth (play-by-play, DFS, projections). No soccer or international sports.

API-SPORTS — Affordable paid plans starting at around $19 per month. Strong soccer coverage across 900+ leagues, plus basketball, football, baseball, and more. Free tier limited to 100 requests per day.

The choice depends on your use case. If you are building a weekend project or learning how APIs work, ESPN’s hidden API is hard to beat. If you need contractual reliability or real-time data for a production application, a paid provider with an SLA is the safer path — and putting any of them behind an API gateway gives you the flexibility to swap providers later without rewriting your client code.

Summary and Next Steps

The ESPN hidden API is a powerful resource for developers looking to integrate rich sports data into their applications. While its unofficial status means you need to plan for instability, the breadth of data available — from live scoreboards to team rosters, schedules, and news — makes it one of the most comprehensive free sports APIs available.

To get started, pick a sport and league, hit the scoreboard endpoint, and explore the JSON response. When you are ready to move beyond a prototype, wrap the API in a gateway so you can add caching, rate limiting, and monitoring without changing your application logic.

Ready to put a production-grade gateway in front of ESPN’s API? Sign up for Zuplo and have your first route proxying live scores in minutes.