Getting started with Score Room
SCORE ROOM API
Welcome to the Scoreroom API Documentation. Here, you will find detailed information on how to interact with the different endpoints available to get sports news, statistics, game data, betting odds, schedules and more!
General Overview
The Scoreroom API offers 10 main endpoints, each designed to retrieve specific types of data:
- LiveScore
- BoxScore
- PlayByPlay
- LeagueSchedules
- TopEvents
- FeaturedHeadlines
- LeagueHeadlines
- Odds
- Teams
- Conferences
Each endpoint returns a JSON object containing the requested data alongside some additional useful data.
Endpoints - Descriptions & Usage Guide
fetchLiveScore:
The fetchLiveScore endpoint takes two query parameters L_ABRV (league abbreviation) & gameId (game ID provided from the fetchTopEvents & fetchLeagueSchedules endpoints).
- L_ABRV = โmlbโ (lowercase league abbreviation)
- gameId = โ401473216โ (specific game id provided by the getGame endpoint)
Valid responses with return JSON data that shows the current score of the relevant game alongside a game message that will either detail the winner of the game or the time remaining (bottom of 3rd inning, halftime, 8:30, etc.). For baseball games, it will also display the live count (outs, balls, fouls). Updates based on rate limit.
Responses:
{
"awayScore": "7",
"homeScore": "81 Winner Icon Oregon Ducks",
"message": "Final"
}
fetchBoxScore:
The fetchBoxScore endpoint takes three query parameters L_ABRV (league abbreviation) & gameId (game ID provided from the fetchTopEvents endpoint) just like the fetchLiveScore endpoint, and also fetchBoxscore (โdoFetchโ).
- L_ABRV = โmlbโ (lowercase league abbreviation)
- gameId = โ401473216โ (specific game id provided by the getGame endpoint)
- fetchBoxscore = โdoFetchโ (add this to get both the live game data and boxscore)
Valid responses will return the stats of a given game in the relevant metrics of the respective sport: (ie baseball: errors, runs, etc.; football: ints, tds, etc.; basketball: fouls, shots, etc.). It will also return team abbreviations and logos. Updates based on rate limit.
Responses:
Teams: [ 'WSH', 'PIT' ]
Processed Scores: [
{
'1': '0',
'2': '0',
'3': '0',
'4': '0',
'5': '0',
'6': '0',
'7': '0',
'8': '0',
'9': '0',
Runs: '0',
Hits: '2',
Errors: '2'
},
{
'1': '0',
'2': '1',
'3': '0',
'4': '0',
'5': '1',
'6': '0',
'7': '0',
'8': '0',
'9': '-',
Runs: '2',
Hits: '5',
Errors: '1'
}
]
WSH: 0 0 0 0 0 0 0 0 0 0 2 2
PIT: 0 1 0 0 1 0 0 0 - 2 5 1
Pitcher: undefined
Pitcher Stats: undefined
Batter: undefined
Batter Stats: undefined
Count: B-0 S-0 O-0
Hitting Stats: [
{
teamName: 'Nationals Hitting',
playersStats: [
[Object], [Object],
[Object], [Object],
[Object], [Object],
[Object], [Object],
[Object], [Object]
]
},
{
teamName: 'Pirates Hitting',
playersStats: [
[Object], [Object],
[Object], [Object],
[Object], [Object],
[Object], [Object],
[Object], [Object]
]
},
...,
teamLogos: [
{
abbrv: 'WSH',
logoUrl: 'https://a.espncdn.com/combiner/i?img=/i/teamlogos/mlb/500/wsh.png&h=40&w=40'
},
{
abbrv: 'PIT',
logoUrl: 'https://a.espncdn.com/combiner/i?img=/i/teamlogos/mlb/500/pit.png&h=40&w=40'
}
]
}
fetchPlayByPlay:
The fetchPlayByPlay endpoint takes three query parameters L_ABRV (league abbreviation) & gameId (game ID provided from the fetchTopEvents endpoint) like the fetchLiveScore endpoint, and also fetchPlayByPlay (โdoFetchโ).
- L_ABRV = โmlbโ (lowercase league abbreviation)
- gameId = โ401473216โ (specific game id provided by the getGame endpoint)
- fetchPlayByPlay = โdoFetchโ (add this to get both live game information and play-by-play data)
Valid responses will return up-to-the-minute play-by-play data including but not limited to scores, plays, possession/drive/inning descriptions and summaries, and team names. Updates based on rate limit.
Responses:
{
"playByPlayData": [
{
"teamName": "Vanderbilt Commodores",
"driveDescription": "6 plays, 15 yards, 2:20",
"driveHeadline": "Punt",
"awayTeam": "MIZ",
"awayScore": "0",
"homeTeam": "VAN",
"homeScore": "0",
"plays": [
{
"headline": null,
"description": "(15:00 - 1st) Harrison Mevis kickoff for 65 yds for a touchback"
},
{
"headline": "1st & 10 at VAN 25",
"description": "(14:34 - 1st) Patrick Smith run for 2 yds to the VAN 27"
},
{
"headline": "2nd & 8 at VAN 27",
"description": "(14:10 - 1st) Patrick Smith run for 4 yds to the VAN 31"
},
{
"headline": "3rd & 4 at VAN 31",
"description": "(13:30 - 1st) Ken Seals pass complete to Will Sheppard for 8 yds to the VAN 39 for a 1ST down"
},
{
"headline": "1st & 10 at VAN 39",
"description": "(13:12 - 1st) Jayden McGowan run for 6 yds to the VAN 45"
},
{
"headline": "2nd & 4 at VAN 45",
"description": "(12:52 - 1st) Ken Seals pass incomplete to Gamarion Carter"
},
{
"headline": "3rd & 4 at VAN 45",
"description": "(12:52 - 1st) Vanderbilt Penalty, False Start (Gunnar Hansen) to the VAN 40"
},
{
"headline": "3rd & 9 at VAN 40",
"description": "(12:48 - 1st) Ken Seals pass incomplete to Justin Ball"
},
{
"headline": "4th & 9 at VAN 40",
"description": "(12:40 - 1st) Matthew Hayball punt for 35 yds, punt out-of-bounds at the MIZ 25"
}
]
},...
]}
โfetchLeagueSchedulesโ:
The fetchLeagueSchedules endpoint takes one query parameter and returns relevant information about league schedules and games updated daily.
-
fetchSchedules = โtrueโ (NOT the boolean true but the string โtrueโ)
-
Valid responses will return the schedules and relevant game and league data for a given sport and league, including but not limited to their season start and end dates, games, competitors, broadcasts, venues, logos, season types, etc.
{
"basketball": {
"nba": {
"schedule": {
"startDate": "2023-10-05T07:00Z",
"endDate": "2024-06-22T06:59Z",
"year": 2024,
"games": [
{
"id": "401591869",
"uid": "s:40~l:46~e:401591869",
"date": "2023-10-05T16:00Z",
"name": "Dallas Mavericks at Minnesota Timberwolves",
"shortName": "DAL VS MIN",
"season": {
"year": 2024,
"type": 1,
"slug": "preseason"
},
"competitions": [
{
"id": "401591869",
"uid": "s:40~l:46~e:401591869~c:401591869",
"date": "2023-10-05T16:00Z",
"attendance": 0,
"type": {
"id": "1",
"abbreviation": "STD"
},
"timeValid": true,
"neutralSite": true,
"conferenceCompetition": false,
"playByPlayAvailable": false,
"recent": false,
"venue": {
"id": "7126",
"fullName": "Etihad Arena",
"address": {
"city": "Abu Dhabi"
},
"capacity": 0,
"indoor": true
},
"competitors": [
{
"id": "16",
"uid": "s:40~l:46~t:16",
"type": "team",
"order": 0,
"homeAway": "home",
"team": {
"id": "16",
"uid": "s:40~l:46~t:16",
"location": "Minnesota",
"name": "Timberwolves",
"abbreviation": "MIN",
"displayName": "Minnesota Timberwolves",
"shortDisplayName": "Timberwolves",
"color": "266092",
"alternateColor": "79bc43",
"isActive": true,
"venue": {
"id": "2029"
},
"links": [
{
"rel": [
"clubhouse",
"desktop",
"team"
],
"href": "https://www.espn.com/nba/team/_/name/min/minnesota-timberwolves",
"text": "Clubhouse",
"isExternal": false,
"isPremium": false
},
{
"rel": [
"roster",
"desktop",
"team"
],
"href": "http://www.espn.com/nba/team/roster/_/name/min/minnesota-timberwolves",
"text": "Roster",
"isExternal": false,
"isPremium": false
},
{
"rel": [
"stats",
"desktop",
"team"
],
"href": "http://www.espn.com/nba/team/stats/_/name/min/minnesota-timberwolves",
"text": "Statistics",
"isExternal": false,
"isPremium": false
},...
fetchTopEvents:
The fetchTopEvents endpoint takes one query parameter getTopEvents and returns the top events of the day. Updated daily.
- ** fetchTopEvents** = โtrueโ (NOT the boolean true but the string โtrueโ)
Valid responses will return the top events of the day including their time, game ID, the home team, the away team, and odds to win.
Responses:
{
"topEvents":
[
{
"time":"11:00 PM UTC",
"gameId":"401520231",
"homeTeam":"Maryland Terrapins",
"awayTeam":"Virginia Cavaliers",
"odds":"MD -15.0"
"league_abrv": "college-football"
},
{
"time":"11:00 PM UTC",
"gameId":"401531396",
"homeTeam":"UTSA Roadrunners",
"awayTeam":"Army Black Knights",
"odds":"UTSA -8.0"
"league_abrv": "college-football"
},
{
"time":"12:00 AM UTC",
"gameId":"401532581",
"homeTeam":"Air Force Falcons",
"awayTeam":"Utah State Aggies",
"odds":"AFA -9.0"
"league_abrv": "college-football"
}, ...
]
}
fetchFeaturedArticles:
The fetchFeaturedArticles endpoint takes one query parameter fetchFeaturedArticles and will return featured/trending articles and each articleโs source, url, title, author, time, and imageUrl assuming each is available and valid. Updated every 4 hours.
- fetchFeaturedArticles = โtrueโ (NOT the boolean true but the string โtrueโ)
Responses:
[
{
"source":"ESPN",
"url":"https://www.espn.com/college-football/story/_/id/38398593/georgia-bulldogs-mekhi-mews-2023-explosive-player",
"title":"The tale of 'Waffle House,' the 5-foot-8 walk-on making plays in Georgia's blue-chip factory",
"author":"Mark Schlabach",
"time":"8h",
"imageUrl":"https://a.espncdn.com/photo/2023/0914/r1224320_1296x729_16-9.jpg"
},
{
"source":"BLEACHER REPORT",
"url":"https://bleacherreport.com/articles/10089614-espn-alabama-name-tyler-buchner-qb1-vs-usf-replaces-jalen-milroe-after-texas-loss",
"title":"ESPN: ALABAMA NAME TYLER BUCHNER QB1 VS. USF; REPLACES JALEN MILROE AFTER TEXAS LOSS",
"imageUrl":"https://media.bleacherreport.com/image/upload/x_13,y_20,w_1783,h_1190,c_crop/w_300,h_200,c_fill/v1694799622/yjp0yyp6yvtvygqir3gh.jpg"
},
{
"source":"YAHOO SPORTS",
"url":"https://sports.yahoo.com/cowboys-believe-stephon-gilmore-trevon-diggs-are-primed-to-become-nfls-best-cornerback-duo-202606363.html",
"title":"'The best duo in the league. Non-negotiable.'",
"imageUrl":"https://s.yimg.com/uu/api/res/1.2/gjfvJwc4n8vD3zBd4aR0uw--~B/Zmk9ZmlsbDtoPTUwNTtweW9mZj0wO3E9OTU7dz05MDA7YXBwaWQ9eXRhY2h5b24-/https://s.yimg.com/os/creatr-uploaded-images/2023-09/efb691d0-532c-11ee-a5fd-e056d243c72a"
},
...
]
fetchLeagueArticles:
The fetchLeagueArticles endpoint takes one query parameter fetchLeagueArticles and will return league articles across 50+ major and minor professional and collegiate sports and each articleโs source, URL, title, author, time, and imageUrl assuming each is available and valid. Updated every 4 hours.
- fetchLeagueArticles = โtrueโ (NOT the boolean true but the string โtrueโ)
Responses:
{
"basketball":
{
"nba":
[
"title":"Wizards re-sign veteran F Taj Gibson to one-year deal"
"description":"The Washington Wizards are re-signing veteran forward Taj Gibson to a one-year, $3.2 million contract."
"url":"https://www.espn.com/nba/story/_/id/38407470/wizards-re-sign-veteran-f-taj-gibson-one-year-deal"
"imageUrl":"https://a.espncdn.com/photo/2023/0915/r1224911_600x400_3-2.jpg"
"publishedAt":"2023-09-15T19:05:08Z"
],
[
"title":"Lakers, Jarred Vanderbilt agree to 4-year, $48M extension, sources say"
"description":"After helping the Lakers' push into the Western Conference finals, Jarred Vanderbilt has agreed to a four-year, $48 million extension, sources told ESPN."
"url":"https://www.espn.com/nba/story/_/id/38405158/lakers-jarred-vanderbilt-agree-4-year-48m-extension-sources-say"
"imageUrl":"https://a.espncdn.com/photo/2023/0503/r1168124_1296x729_16-9.jpg"
"publishedAt":"2023-09-15T14:41:31Z"
],
[
"title":"Team USA tops FIBA men's world rankings, overtaking Spain"
"description":"USA Basketball is back atop the FIBA men's world rankings, even after failing to medal at the World Cup."
"url":"https://www.espn.com/olympics/story/_/id/38404621/team-usa-tops-fiba-men-world-rankings-overtaking-spain"
"imageUrl":"https://a.espncdn.com/photo/2023/0812/r1209841_600x400_3-2.jpg"
"publishedAt":"2023-09-15T13:28:06Z"
]
},
"womens-college-basketball":
{
[...]
},
...
},
"tennis": {},
}
fetchOdds:
The fetchOdds endpoint takes one query parameter fetchOdds and will return the odds for upcoming games across most major sports and each gameโs league, teams, team odds of winning, logo, and record assuming each is available and valid. Updated twice daily.
- fetchOdds = โtrueโ (NOT the boolean true but the string โtrueโ)
Responses:
[
{
"league":"mlb",
"gameInfo": ["Yankees vs NYY","Pirates vs PIT"],
"oddsValue":"-148",
"teamLogo":"https://static.sprtactn.co/teamlogos/mlb/100/nyy.png",
"teamName": ["Yankees", "NYY"],
"win":69,
"loss":78,
"ties":null,
"draw":null,
"overtime_losses":null
},
...
]
fetchTeams:
The fetchTeams endpoint takes one query parameter fetchTeams and will return teams across 44 major and minor professional and collegiate sports, with each teamโs relevant information including but not limited to its id, abbreviation, displayName, colors, location, league, etc. assuming each is available and valid. Updated monthly.
- fetchTeams = โtrueโ (NOT the boolean true but the string โtrueโ)
Responses:
[
{
"sports":
[
{
"id":"600",
"uid":"s:600",
"name":"Soccer",
"slug":"soccer",
"leagues":
[
{
"id":"770",
"uid":"s:600~l:770",
"name":"MLS",
"abbreviation":"MLS",
"shortName":"MLS",
"slug":"usa.1",
"teams":
[
{
"team":
{
"id":"18418",
"uid":"s:600~t:18418",
"slug":"usa.atlanta_united_fc",
"abbreviation":"ATL",
"displayName":"Atlanta United FC",
"shortDisplayName":"Atlanta",
"name":"Atlanta United FC",
"location":"Atlanta United FC",
"color":"9d2235",
"alternateColor":"aa9767",
"isActive":true,
"isAllStar":false,
"logos":
[
{
"href":"https://a.espncdn.com/i/teamlogos/soccer/500/18418.png",
"alt":"",
"rel":["full","default"],
"width":500,
"height":500
},...
],
"links":
[
{
"language":"en-US",
"rel":["clubhouse","desktop","team"],
"href":"https://www.espn.com/soccer/club/_/id/18418/atlanta-united-fc",
"text":"Clubhouse",
"shortText":"Clubhouse",
"isExternal":false,
"isPremium":false,
"isHidden":false
},
{
"language":"en-US",
"rel":["stats","desktop","team"],
"href":"https://www.espn.com/soccer/team/stats/_/id/18418/atlanta-united-fc",
"text":"Stats",
"shortText":"Stats",
"isExternal":false,
"isPremium":false,
"isHidden":false
},...
]
}
},
fetchConferences:
The fetchConferences endpoint takes one query parameter fetchConferences and will return professional and collegiate conferences with their respective teams across 44 major and minor professional and collegiate sports. Updated monthly.
- fetchConferences = โtrueโ (NOT the boolean true but the string โtrueโ)
Responses:
"nfl":
{
"status":"success",
"groups":
[
{
"name":"American Football Conference",
"abbreviation":"AFC",
"children":
[
{
"name":"AFC East",
"abbreviation":"EAST",
"teams":
[
{
"id":"2",
"slug":"buffalo-bills",
"name":"Bills",
"abbreviation":"BUF",
"displayName":"Buffalo Bills",
"shortDisplayName":"Bills",
"logos":
[
{
"href":"https://a.espncdn.com/i/teamlogos/nfl/500/buf.png",
"width":500,
"height":500,
"alt":"",
"rel":
[
"full",
"default"
],
"lastUpdated":"2023-08-24T19:26Z"
},...
],
"links":
[
{
"language":"en-US",
"rel":...
}
],
},...
]
},...
}]}...
```
---