ESPN Scores and Schedules Data
Scores & Schedules
We never miss a game
The ESPN Scores & Schedules API provides game/match information, including start times, venue, competitors, score, and stats across every major sport.
This API is currently a version 1 (/v1/) release.
Availability Public Partner Premium Partner ESPN
This API is great for:
- Scoreboard apps
- Pre-game and post-game experiences
- Sport and team-by-team schedules
- "Live" apps
The ESPN Scores & Schedules API accepts a GET request.
The format of an API request is as follows:
Sample Scores & Schedules Requests
Action URI Description GET http://api.espn.com/v1/sports/baseball/mlb/events Current day's game information for MLB. GET http://api.espn.com/v1/sports/baseball/mlb/events?lang=es Current day's game information for MLB with optional Spanish-language translations enabled. GET http://api.espn.com/v1/sports/baseball/mlb/events?groups=7 American League event data for MLB for current day. GET http://api.espn.com/v1/sports/baseball/mlb/teams/2/events?dates=2010 Schedule and scores information for a particular MLB team for the 2010 season. GET http://api.espn.com/v1/sports/baseball/mlb/events/320328111 Specific MLB game information. GET http://api.espn.com/v1/sports/events Score/schedule information for all supported sports for the current day. GET http://api.espn.com/v1/sports/events/top Top sports events as highlighted by ESPN's editorial team. GET http://api.espn.com/v1/sports/events?leagues=nhl,mens-college-basketball NHL and men's college basketball events for the current day.
Resource Name Description Availability public partner premium
espn /sports All supported sports /sports/baseball/mlb Major League Baseball (MLB) /sports/basketball/mens-college-basketball NCAA Men's College Basketball /sports/basketball/nba National Basketball Association (NBA) /sports/basketball/wnba Women's National Basketball Association (WNBA) /sports/basketball/womens-college-basketball NCAA Women's College Basketball /sports/football/college-football NCAA College Football /sports/football/nfl National Football League (NFL) /sports/golf Professional golf /sports/golf/eur European Tour golf /sports/golf/ntw Nationwide Tour golf /sports/golf/pga Professional Golfers' Association (PGA) golf /sports/golf/sga Champions Tour golf /sports/hockey/nhl National Hockey League (NHL) /sports/mma Mixed Martial Arts /sports/mma/:leagueAbbrev Specific Mixed Martial Arts league.
Use a helper API call for a complete list of supported MMA leagues.
/sports/olympics Olympic Games /sports/olympics/:olympicSport Specific Olympics sport/discipline (e.g. soccer, badminton, swimming, etc).
Use a helper API call for a complete list of supported Olympics sports.
/sports/racing Professional auto racing /sports/racing/f1 Formula 1 Racing /sports/racing/irl IndyCar Series Racing /sports/racing/sprint NASCAR Sprint Racing /sports/racing/truck NASCAR Truck Racing /sports/soccer Professional soccer /sports/soccer/:leagueAbbrev Specific professional soccer league.
Use a helper API call for a complete list of supported soccer leagues.
/sports/tennis Professional tennis /sports/tennis/atp Association of Tennis Professionals /sports/tennis/wta Women's Tennis Association
MethodsBack to top
In addition to the standard URI parameters, the ESPN Scores & Schedules API also supports the following URI parameters:
Parameter Description Availability public partner premium
espn groups Integer (e.g. groups=7) that limits the event results to a specific group/division. To see a list of group IDs for a given league, use our Helper API calls. enable Optional flag to enable specific information, with the following options. Accepts a single value or a comma delimited string of values (i.e. enable=a,b,c). linescores Enables linescores for /events and /events/top methods. Note that linescores are automatically enabled when using the /events/:eventId method. odds Enables game line/odds information for the event. This is disabled by default. broadcasts Enables TV broadcast information, including the network name and whether it's nationally or locally televised. logos Enables team logos. flags For individual sports (current support for Olympics, Golf, and Tennis) returns the athlete's affiliated country object and links to flag images, each containing href, width, and height attributes. Only works with /events/:eventId method. weather For MLB, NCAA Football (where available), NFL, and Racing events (where available) returns weather information for the location where the event is being played. Only works with /events/:eventId method. series For MLB, NBA, and NHL, returns head-to-head series information for the current series between the teams. Useful for indicating current state of Playoff Series. ranks Returns an array of rank objects corresponding to the competitor, e.g. AP Poll, USA Today Poll, BCS Ranking, ESPN Power Ranking, etc. 'rank' types vary by sport. disable Optional flag to disable specific information, with the following options. Accepts a single value or a comma delimited string of values (i.e. disable=a,b,c). links Removes event-specific links to GameCast, game previews, recaps, etc for the event. This is enabled by default. venues Removes venue/stadium information for the event. This is enabled by default. stats Removes event-specific statistics information. This is enabled by default. season Removes the season object from the response. sports Removes the containing 'sports' array from the response. Not applicable for /sports/events and /sports/events/top methods. leagues Removes the containing 'leagues' array from the response. Not applicable for the /sports/events, /sports/events/top/sports/:sportName/events athletes Removes array of athletes playing in the event. Only applies when /events/:eventId method is used. details Removes array of plays from the event. Only applies when /events/:eventId method is used. team Removes the nested team object within a competitor. Useful when polling only for score updates when the competing teams are already known. Only applicable to team sports. linescores Removes period by period scoring for the event. Linescores are only enabled by default when using the /events/:eventId method. dates Integer in the form of yyyy, yyyymm, or yyyymmdd to limit output to a particular season, month, or day. If not passed will default to the season and season type (pre/reg/post) corresponding to the current date. weeks Integer. Only applicable to college and NFL football. When used with a season, returns games for that particular week. seasontype Value corresponding to either preseason, regular season, or postseason games. Accepts string (pre/reg/post) values. If not passed will default to the season type corresponding to the current date. Not applicable to golf, tennis, racing, olympics, or soccer. "pre" season type is only available for MLB, NFL, NBA, and NHL . expand Boolean that can be used with the /events or /teams/:teamId/events methods to return previous/current/next games in a single result set. Applicable to NFL, NHL, MLB, NBA, NCAAFB, NCAABB, and WNBA. leagues Comma-separated list of leagues that can be used with a /sports/events request to include results for multiple leagues in a single API request. period Integer value to limit the contents of the details array to a specific period. Only applicable with the /events/:eventId method. scoredetails Boolean parameter that will show only scoring plays in the details array. Only applicable with the /events/:eventId method. lastdetail Boolean parameter that will show only the most recent play in the details array (vs. the entire array). Only applicable with the /events/:eventId method. lang Can be used to return content in the specified language. Supported languages are below. Note: not all content is available in multiple languages and will return in English if no alternative is available. en English. Default language es Spanish locale Applicable only when /events/top method is used. Supported values are currently en-us (top US events) and en-gb (top UK events).
- Returned Data
- Baseball Extension
- Basketball Extension
- Football Extension
- MMA Extension
- Olympics Extension
- Racing Extension
- Soccer Extension
- Competition Details Extension
- Sample Response
Element Description Availability public partner premium
espn sports Array of sports associated with the request. Contains a leagues collection and also has the following properties: name The name of the sport, e.g. "Baseball." id the ID of the sport in the ESPN API. leagues Collection within 'sports' that contains events and the following properties: name the name of the league/conference/division, e.g. "American League East." shortName Shorter version of the league/conference/division. abbreviation the abbreviation for the league/conference/division, e.g. "al" for "American League." id the ID of the sport in ESPN's meta-tagging system. groupId The ID, unique to the selected organizing body, of the conference/division being used. events Array of event objects within 'leagues'. Contains a collection of 'competitions' (games/matches). Also contains all the properties below: id the ID corresponding to the event. In many cases, this will be the same as the competition ID. date date of the event, e.g. "2011-10-25T00:05:00Z". name Name of the event. Not applicable for all sports. season object containing the follow properties: year - the calendar year in which the majority of the sport's season is played. type - Integer corresponding to the season type (1 = preseason, 2 = regular season, 3 = postseason). description - String representation of the season type (e.g. "regular" for season type = 2). startDate - date for which the season starts for this sport/league. endDate - date for which the season ends for this sport/league. timeValid Boolean; Indicates if the event has an official scheduled start time. competitions Array within the events object that contains the following data: id ID for the game/match. date Date for the match, e.g. "2011-10-25T00:05:00Z". name Name of the competition. Not applicable for all sports. stats Additional statistics related to the match, including: attendance - Integer indicating the attendance of the match. priority - Integer indicating level of importance of the match as determined by ESPN's editorial team. Only returned when /events/top method is used. competitors Collection of teams or individuals competing in the event. Contains the following properties: type - String value representing the type of competitor, i.e. "team" or "athlete". score - the competitor's current total score in the match. homeAway - String indicating whether the competitor is the home/away team, and can be used for a typical scoreboard display (away=top, home=bottom). Only applicable to team sports. isWinner - Boolean value indicating if the competitor is the winner of the competition. Can only be 'true' for a completed competition. team - Team object with basic properties (if competitor is a team). athlete - Athlete object with basic properties (if competitor is an athlete). linescores - When enabled, returns a collection of period/score values for the team. details Array of play detail objects. Only displayed when the /events/:eventId method is used. See the Event Details Extension for more info. odds When enabled, returns a collection of objects each containing the following properties. Only available for team sports. casino - Object for the reporting odds source. Contains id/name/active/priority values. favorite - String representation of the favorite team, e.g. "Philadelphia". underdog - String representation of the underdog team, e.g. "Philadelphia". overUnder - Integer spread - Integer initialSpread - Integer initialOverUnder - Integer price - Integer broadcasts When enabled, returns a collection of TV broadcast objects for the game, each with the following properties: typeId - ID corresponding to the type of network in ESPN's systems. type - String representation of the type of network, i.e. awayTV/homeTV/nationalTV. broadcastId - ID of the network in ESPN's systems. name - String value of the network name, e.g. "ESPN." shortName - Shorter string value of the network name, if available. callLetters - Unique call sign for the transmitting station. situation Object containing sport-specific situational details for competitions that are in progress. See the various sport extensions below for more details. series When enabled, returns a series object containing information about the current head-to-head matchup between teams. Only available for MLB, NHL, and NBA games. Contains the following properties: competitor1Id - Integer ID of the first competitor in the competition. competitor2Id - Integer ID of the second competitor in the competition. competitor1Wins - Number of competitions won by competitor 1 in the series. competitor2Wins - Number of competitions won by competitor 2 in the series. totalCompetitions - Maximum number of competitions (games) scheduled in the series. Can be used for "Best Of 7" or "Best of 5" type notes. summary - String summary of the series, e.g. "New York Leads 2-0". seriesFinished - Boolean indicating if the series is complete. seriesTitle - String indicating "Regular Season Series" or "Playoff Series". status object of the current status of the game/match containing the following properties: id - Integer ID corresponding to the current game status (1= pre, 2= in, 3=post). description - String representation of match status, e.g. "SCHEDULED". detail - Detailed string representation of match status, e.g. "SCHEDULED: 2011-10-25T00:05:00Z". period Integer corresponding to the current period of play. clock Current time left in the period. notes Collection of game-related notes (if available), each with the following properties: type - String representing the type of note, e.g. "event" text - String of the actual note text, e.g. "2012 NBA All-Star Game in Orlando, FL" links Collection of relevant API endpoints and canonical URLs for the event. venues The location where the game/match is being played. Contains the following properties: id - Integer ID representing the venue name - Name of the venue (e.g. "Fenway Park") city - String value of the city where the venue is located (e.g. "Boston") state - String abbreviation the state where the venue is located (e.g. "MA") country - String abbreviation the country where the venue is located (e.g. "USA") weather When enabled, returns a weather object containing the following properties. Only applicable to /events/:eventId method and only works with MLB, NCAA Football (where available), NFL, and Racing (where available). Weather data is only available prior to and during live events. conditions String describing the conditions at the event, e.g. "Few Clouds". temperature Temperature at the event in Fahrenheit. windDirection Direction of the wind in degrees windSpeed Wind speed in MPH graphics Object containing images indicative of the weather conditions. lastUpdated Date when the weather data was last updated, in standard DateTime format ("yyyy-MM-ddTHH:mm:ssZ"). type String representing the type of game/match, e.g. "Regular Season" eventSourceId Integer ID corresponding to the Event Source in ESPN's systems. eventSource String representation of the level of score updates available for the game. Possible values include: pbp Live, real-time updates. basic Periodic updates. manual Only basic updates, such as score only. postgame Final/official scrubbed values. statSourceId Integer ID corresponding to the statistics source in ESPN's systems. statSource String representation of the level of stats available for the game/match. Possible values include: pbp Full, real-time stat feed. basic Only major stat categories (e.g. goals, assists for hockey). postgame Final/official scrubbed values.
Baseball Extension (MLB)
The following additional data are included for baseball competitions:Back to top
Basketball Extension (NBA, NCAA Basketball)
The following additional data are included for basketball competitions:Back to top
Football Extension (College Football & NFL)
The following additional data are included for football competitions:Back to top
The following additional data are included for MMA competitions:Back to top
The following additional data are included in Olympics competitions:Back to top
The following additional data are included for racing competitions:Back to top
The following additional data are included for soccer competitions:Back to top
Competition Details Extension
The following additional data are included when the /events/:eventId method is used.Back to top
The following XML output was rendered with an internal key calling:
The following JSON output was rendered with an internal key calling: