The ESPN Scores & Schedules API accepts a GET request.

The format of an API request is as follows:
http://api.espn.com/:version/:resource/:method?apikey=:yourkey

Sample Scores & Schedules Requests

Quick Navigation

• Resources
• Methods
• URI Parameters

Resources

Resource Name	Description	Availability
		public	partner	premium partner	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

Methods

Method	Description	Availability
		public	partner	premium partner	espn
/events	Events for a given sport/league. Defaults to current day's events. For college football and college basketball, defaults to AP Top 25 games.
/events/top	Day's top events as determined by ESPN's editorial team. Only applicable to /sports resource.
/events/:eventId	Information for a particular game/match.
/teams/:teamId/events	Events for a particular team for the current day. Only applicable to team sports.

URI Parameters

In addition to the standard URI parameters, the ESPN Scores & Schedules API also supports the following URI parameters:

Parameter	Description	Availability
		public	partner	premium partner	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).

Quick Navigation

• Returned Data
• Baseball Extension
• Basketball Extension
• Football Extension
• MMA Extension
• Olympics Extension
• Racing Extension
• Soccer Extension
• Competition Details Extension
• Sample Response

Returned Data

Element	Description	Availability
		public	partner	premium partner	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:

Element	Description	Availability
		public	partner	premium partner	espn
situation	Object within the 'competition' object containing the following properties. Only displayed during in-progress competitions.
	balls Integer indicating the number of balls in the current at-bat.
	strikes Integer indicating the number of strikes in the current at-bat.
	outs Integer indicating the number of outs in the current inning.
	onFirst Integer corresponding to the athlete ID of the baserunner on first base.
	onSecond Integer corresponding to the athlete ID of the baserunner on second base.
	onThird Integer corresponding to the athlete ID of the baserunner on third base.
	currentBatter Integer corresponding to the athlete ID of the current batter.
	currentPitcher Integer corresponding to the athlete ID of the current pitcher.

Basketball Extension (NBA, NCAA Basketball)

The following additional data are included for basketball competitions:

Element	Description	Availability
		public	partner	premium partner	espn
situation	Object within the 'competition' object containing the following properties. Only displayed during in-progress competitions.
	awayTimeouts Integer indicating number of full timeouts remaining for the away team for the game.
	homeTimeouts Integer indicating number of full timeouts remaining for the home team for the game.
	awayTimeoutsCurrent Integer indicating number of timeouts used in the current period by the away team. Resets at the beginning of each period.
	homeTimeoutsCurrent Integer indicating number of timeouts used in the current period by the home team. Resets at the beginning of each period.
	awayTimeoutsTwoCurrent Integer indicating number of timeouts used in the last two minutes of the current period by the away team. Resets at the beginning of each period.
	homeTimeoutsTwoCurrent Integer indicating number of timeouts used in the last two minutes of the current period by the home team. Resets at the beginning of each period.
	awayTeamFouls Integer indicating the number of total fouls committed by the away team for the entire game.
	homeTeamFouls Integer indicating the number of total fouls committed by the home team for the entire game.
	awayTeamFoulsCurrent Integer indicating the number of fouls committed by the away team in the current period. Resets with each period.
	homeTeamFoulsCurrent Integer indicating the number of fouls committed by the home team in the current period. Resets with each period.

Football Extension (College Football & NFL)

The following additional data are included for football competitions:

Element	Description	Availability
		public	partner	premium partner	espn
situation	Object within the 'competition' object containing the following properties. Only displayed during in-progress competitions.
	down Integer of the current down.
	distance Integer corresponding to the number of yards needed for a 1st down.
	yardLine Integer denoting the current yard line of the team in possession.
	possessionTeamId Integer of the team ID currently in possession of the ball.
	isRedZone Boolean indicating if the offensive team is within 20 yards of the opposing team's end zone.
	awayTimeouts Number of timeouts remaining for the away team.
	homeTimeouts Number of timeouts remaining for the home team.

MMA Extension

The following additional data are included for MMA competitions:

Element	Description	Availability
		public	partner	premium partner	espn
competitions	A collection within the 'events' object that contains the following data:
	weightClass Object containing the following properties:
	name - The enumerator value, e.g. "middleweight"
	description - Text description of the weight class, e.g. "Middleweight""
	isTitle Boolean property indicating whether the match is a title fight.
	decisionType Object representing the final outcome of the fight. Contains the following properties:
	name - The enumerator value, e.g. "knockout"
	description - Text description of the decision type, e.g. "Knockout""

Olympics Extension

The following additional data are included in Olympics competitions:

Element	Description	Availability
		public	partner	premium partner	espn
season	Object containing the following additional property:
	olympicSeasonId Integer ID corresponding to the specific Olympic Games in ESPN's systems.
competitions	A collection within the events object that contains the following additional data:
	isMedal Boolean indicating whether a medal will be awarded to the winner of the competition.

Racing Extension

The following additional data are included for racing competitions:

Element	Description	Availability
		public	partner	premium partner	espn
competitions	A collection within the 'events' object that contains the following data:
	competitors Collection of drivers competing in the event. Contains the following additional properties for racing:
	place - the driver's current position in the race.

Soccer Extension

The following additional data are included for soccer competitions:

Element	Description	Availability
		public	partner	premium partner	espn
competitions	A collection within the 'events' object that contains the following data:
	competitors Collection of teams competing in the event. Contains the following additional properties for soccer:
	shootoutScore - the team's shootout score, if applicable.
	addedClock Added time in the soccer match, if applicable. Note that this value only exists during the match. Upon match completion, it resets to 0.
	leg The leg of the soccer match, if applicable, for matches that span more than one day.

Competition Details Extension

The following additional data are included when the /events/:eventId method is used. 

Element	Description	Availability
		public	partner	premium partner	espn
details	Array of play detail objects within the competition object. Each detail object contains the following properties:
	id Integer ID of the play.
	clock String value corresponding to the game clock at the time of the play.
	datestamp Time snapshot when the play happened, e.g. "2011-02-02T21:09:30Z".
	playType Object containing details on the play, with the following properties:
	id - Integer ID corresponding to the type of play.
	description - String value describing the type of play, e.g. "Start Period."
	period Integer corresponding to the period when the play occurred.
	playText Text describing the play.
	shortPlayText Shorter variation of text describing the play.
	sequenceNumber Unique number corresponding to the order of the play in the competition.
Baseball (MLB) competitions also include:
	awayScore Away team score at time of the play.
	homeScore Home team score at time of the play.
	scoreValue Number of incremental points associated with the play, e.g. 4 for a grand slam.
	teamId Team ID of the team involved in the play.
	halfInning Integer to denote whether the play happened in the top or bottom of the inning.
	batterId Integer ID of the batter involved in the play.
	pitcherId Integer ID of the pitcher involved in the play.
	awayHits Number of total hits for the away team at the time of the play.
	homeHits Number of total hits for the home team at the time of the play.
	awayErrors Number of total errors for the away team at the time of the play.
	homeErrors Number of total errors for the home team at the time of the play.
	balls Number of balls at the time of the play.
	strikes Number of strikes at the time of the play.
	outs Number of outs at the time of the play.
Basketball (NBA, NCAABB, NCAAWBB, WNBA) competitions also include:
	awayScore Away team score at time of the play.
	homeScore Home team score at time of the play.
	scoreValue Number of incremental points associated with the play, e.g. 1 for a free throw.
	athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
	teamId Team ID of the team involved in the play.
	xCoordinate The x coordinate of where the scoring play occurred on the court.
	yCoordinate The y coordinate of where the scoring play occurred on the court.
Football (NCAAFB, NFL) competitions also include:
	homeScore Home team score at time of the play.
	awayScore Away team score at time of the play.
	scoreValue Number of incremental points associated with the play, e.g. 6 for a touchdown.
	athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
	teamStart Object containing the following properties:
	id - Team ID with possession of the ball when the play started.
	teamEnd Object containing the following properties:
	id - Team ID with possession of the ball when the play ended.
	downDistanceText String value describing the down and distance of the current play.
	downStart Integer of the down when the play started.
	downEnd Integer of the down when the play ended.
	drive Object containing information about the current drive. Includes the following properties:
	id - Integer Id of the current drive.
	statYardage Integer indicating the amount of yards gained/lost on the play.
	yardLineStart Integer indicating the yard line that the play started on.
	yardsToEndZoneStart Integer indicating the number of yards from the end zone of the offensive team when the play began.
	yardsToEndZoneEnd Integer indicating the number of yards from the end zone of the offensive team when the play ended.
Hockey (NHL) competitions also include:
	awayScore Away team score at time of the play.
	homeScore Home team score at time of the play.
	athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
	teamId Team ID of the team involved in the play.
	xCoordinate The x coordinate of where the play occurred on the ice.
	yCoordinate The y coordinate of where the play occurred on the ice.
	strength Object indicating power-play situation, with the following properties:
	id - The ID associated with the strength type.
	description - String description associated with the strength type, e.g. "even" or "shorthanded."
Soccer competitions also include:
	awayScore Away team score at time of the play.
	homeScore Home team score at time of the play.
	athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
	teamId Team ID of the team involved in the play.

Sample Response