Skip to main content

Overview

The ESPN API provides access to live scores, schedules, and team information across multiple sports leagues including basketball, football, hockey, soccer, and MMA.

Basketball

NBA Scoreboard

Get current NBA game scores and schedules. Endpoint: GET /api/espn/basketball/nba/scoreboard
cURL
curl -X GET "https://rocks.rive.wtf/api/espn/basketball/nba/scoreboard" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch('https://rocks.rive.wtf/api/espn/basketball/nba/scoreboard', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const scoreboard = await response.json();
scoreboard.games.forEach(game => {
  console.log(`${game.away_team.name} @ ${game.home_team.name}`);
  console.log(`Score: ${game.away_team.score} - ${game.home_team.score}`);
  console.log(`Status: ${game.status}\n`);
});

NBA Teams

Get a list of all NBA teams. Endpoint: GET /api/espn/basketball/nba/teams
cURL
curl -X GET "https://rocks.rive.wtf/api/espn/basketball/nba/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

WNBA Scoreboard

Get current WNBA game scores and schedules. Endpoint: GET /api/espn/basketball/wnba/scoreboard

College Basketball

Women’s College Basketball Scoreboard:
GET /api/espn/basketball/womens-college-basketball/scoreboard
Men’s College Basketball Teams:
GET /api/espn/basketball/mens-college-basketball/teams

Football & Hockey

NFL Scoreboard

Get current NFL game scores and schedules. Endpoint: GET /api/espn/football/nfl/scoreboard
cURL
curl -X GET "https://rocks.rive.wtf/api/espn/football/nfl/scoreboard" \
  -H "Authorization: Bearer YOUR_API_KEY"
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(
    'https://rocks.rive.wtf/api/espn/football/nfl/scoreboard',
    headers=headers
)

scoreboard = response.json()
print(f"Week {scoreboard['week']} - {scoreboard['season']} Season\n")

for game in scoreboard['games']:
    print(f"{game['away_team']['name']} @ {game['home_team']['name']}")
    print(f"Score: {game['away_team']['score']} - {game['home_team']['score']}")
    print(f"Quarter: {game['quarter']}\n")

NHL Scoreboard

Get current NHL game scores and schedules. Endpoint: GET /api/espn/hockey/nhl/scoreboard
cURL
curl -X GET "https://rocks.rive.wtf/api/espn/hockey/nhl/scoreboard" \
  -H "Authorization: Bearer YOUR_API_KEY"

UFC Events

Get current and upcoming UFC events and results. Endpoint: GET /api/espn/mma/ufc/scoreboard
cURL
curl -X GET "https://rocks.rive.wtf/api/espn/mma/ufc/scoreboard" \
  -H "Authorization: Bearer YOUR_API_KEY"

Soccer

All Leagues

Get scores from all available soccer leagues or a specific league. Endpoint: GET /api/espn/soccer Query Parameters:
league
string
required
League identifier. Use all for all leagues or specific league codes.

Available Leagues

LeagueCodeEndpoint
All Leaguesall/api/espn/soccer?league=all
English Premier Leagueepl/api/espn/soccer?league=epl
La Liga (Spain)laliga/api/espn/soccer?league=laliga
Bundesliga (Germany)bundesliga/api/espn/soccer?league=bundesliga
Serie A (Italy)seriea/api/espn/soccer?league=seriea
Ligue 1 (France)ligue1/api/espn/soccer?league=ligue1
UEFA Champions Leagueucl/api/espn/soccer?league=ucl
UEFA Europa Leagueeuropa/api/espn/soccer?league=europa
Major League Soccermls/api/espn/soccer?league=mls

Example Usage

cURL
curl -X GET "https://rocks.rive.wtf/api/espn/soccer?league=epl" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScript
const leagues = ['epl', 'laliga', 'bundesliga', 'seriea'];

async function getScores() {
  for (const league of leagues) {
    const response = await fetch(
      `https://rocks.rive.wtf/api/espn/soccer?league=${league}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    
    const data = await response.json();
    console.log(`\n${league.toUpperCase()} Matches:`);
    
    data.matches.forEach(match => {
      console.log(`${match.home_team.name} vs ${match.away_team.name}`);
      console.log(`Score: ${match.home_team.score} - ${match.away_team.score}`);
    });
  }
}

getScores();
Python
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY'}
leagues = ['epl', 'laliga', 'bundesliga', 'ucl', 'mls']

for league in leagues:
    params = {'league': league}
    response = requests.get(
        'https://rocks.rive.wtf/api/espn/soccer',
        headers=headers,
        params=params
    )
    
    data = response.json()
    print(f"\n{data['league_name']} Matches:")
    
    for match in data.get('matches', []):
        print(f"{match['home_team']['name']} vs {match['away_team']['name']}")
        print(f"Score: {match['home_team']['score']} - {match['away_team']['score']}")
        print(f"Status: {match['status']}")

Common Response Fields

Game Status Values

StatusDescription
Pre-GameGame hasn’t started yet
Live / In ProgressGame is currently being played
Halftime / IntermissionBreak between periods
FinalGame has ended
PostponedGame has been postponed
CanceledGame has been canceled

Team Information

All responses include team information with:
  • name: Full team name
  • abbreviation: Team abbreviation/code
  • score: Current score (null for pre-game)
  • logo: URL to team logo image
  • record: Win-loss record (where applicable)

Rate Limiting & Best Practices

ESPN data updates in real-time. For live events, consider polling the API every 30-60 seconds for score updates.
Cache scoreboard data for non-live games to reduce API calls. Games with status “Final” won’t change.
Game StatusRecommended Interval
Pre-GameEvery 5-10 minutes
Live/In ProgressEvery 30-60 seconds
Halftime/IntermissionEvery 2-3 minutes
FinalNo polling needed (cache)

Use Cases

Build comprehensive sports scoreboards displaying live scores from multiple leagues and sports.
Track player performance and game scores for fantasy sports platforms.
Provide real-time odds and score updates for sports betting applications.
Create bots that send score updates and game notifications to sports communities.
Integrate live scores and schedules into sports news and media websites.
Build mobile sports apps with real-time score updates and push notifications.

Match schedules vary by league and season. Some endpoints may return empty arrays when no games are scheduled for that day.