The ESPN Athletes API accepts a GET request.

Athlete information is available for most major sports.

Please refer to the Availability column in the documentation to confirm what team information and statistics are available to you, depending on your developer status (public, partner, or ESPN).

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

Sample Athletes Requests

Quick Navigation

• Resources
• Methods
• URI Parameters

Resources

Resource Name	Description	Availability
		public	partner	premium partner	espn
/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
/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 Golf Tour
/sports/golf/pga	Professional Golf Association
/sports/golf/sga	Senior Golf Association
/sports/hockey/nhl	National Hockey League (NHL)
/sports/racing/f1	Formula 1 Racing
/sports/racing/irl	IndyCar Racing League
/sports/racing/nascar	NASCAR Racing
/sports/soccer/:leagueName	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
/athletes	Retrieves a list of athletes within a sport/league for a given season, with corresponding API links.
/athletes/teams/:teamId	Retrieves a list of athletes on a particular team, with corresponding API links. Not applicable to golf, tennis, or racing.
/athletes/:id	Returns information about a specific athlete.
/recruits	Retrieves all high-school recruits entering college for the current year. Currently only available for college football and men's college basketball.
/recruits/teams/:teamId	Retrieves high-school recruits committed to a specific college. Currently only available for college football and men's college basketball.
/recruits/top	Retrieves the top high-school recruits entering college for the current year, as ranked by ESPN's experts. Currently only available for college football and men's college basketball.
/recruits/:id	Retrieves a specific high-school recruit entering college. Currently only available for college football and men's college basketball.

URI Parameters

Parameter	Description	Availability
		public	partner	premium partner	espn
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).
	statistics Athlete-specific statistics.
	stats Athlete-specific statistics. This is a DEPRECATED feature from our Beta release and will be removed from the API. Stats should be retrieved by enabling the 'statistics' parameter, as specified above.
	logos Team logos.
	flags Collection of country flag images representing the athlete's home country, each containing href, width, and height attributes.
	notes Athlete-specific injury/status notes.
	teams Team(s) the athlete has played for in a given season.
groups	Integer - Allows for filtering by "group" or division, e.g. AL East, NFC South, etc. For group IDs and their corresponding values, make a request to http://developer.espn.com/v1/{resource}/leagues. Not applicable to golf, tennis, and recruiting.
seasontype	Value corresponding to either preseason, regular season, or postseason games, typically in conjunction with 'statistics' being enabled. Accepts string (pre/reg/post) values. If not passed will default to the current season type. Not applicable to golf, tennis, racing, or recruiting.
statstype	When 'statistics' are enabled, determines whether a single season of stats or a full career of stats will be returned. Possible values are:
	season Statistics for the current season. This is the default.
	career Statistics objects for every season the athlete has played.
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

Quick Navigation

• Returned Data
• General Stats Extension
• College Basketball (Men) Stats Extension
• College Football Stats Extension
• College Football Recruiting Extension
• Golf Stats Extension
• MLB Stats Extension
• NBA Stats Extension
• NFL Stats Extension
• NHL Stats Extension
• Racing Stats Extension
• Soccer Stats Extension
• Tennis Stats Extension
• Sample Response

Returned Data

Requests to this API return the following information.

Element	Description	Availability
		public	partner	premium partner	espn
sports	A collection of sports associated with the request, e.g. "baseball." 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 the following properties:
	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.
	name the name of the league/conference/division, e.g. "American League East."
	shortName Shorter version of the league/conference/division name.
	abbreviation the abbreviation for the league/conference/division, e.g. "al" for "American League."
athletes	Collection of athlete objects within 'leagues' containing all the properties below:
id	The athlete's ID within that sport.
alternateId	The athlete's alternate ID within ESPN's systems. Not available for tennis or golf.
firstName	The athlete's first name.
lastName	The athlete's last name.
fullName	The athlete's full (proper) name.
displayName	The athlete's name as most commonly displayed.
shortName	Short version of the athlete's name, typically for display in box scores are other areas where space is limited.
weight	The athlete's weight in lbs.	NCAAFB NCAABB	NCAAFB NCAABB
height	The athlete's height in inches.	NCAAFB NCAABB	NCAAFB NCAABB
hand	The athlete's dominant hand, i.e. "L" or "R". Not available for all sports.
jersey	The athlete's uniform number, if applicable.	NCAAFB NCAABB	NCAAFB NCAABB
dateOfBirth	The athlete's birthdate.	NCAAFB NCAABB	NCAAFB NCAABB
age	The athlete's current age.	NCAAFB NCAABB	NCAAFB NCAABB
birthPlace	Object containing data on where the athlete was born. Properties include:	NCAAFB NCAABB	NCAAFB NCAABB
	city City where the athlete was born, e.g. "Miami."	NCAAFB NCAABB	NCAAFB NCAABB
	state State where the athlete was born, e.g. "Florida."	NCAAFB NCAABB	NCAAFB NCAABB
	country Country where the athlete was born, e.g. "USA."	NCAAFB NCAABB	NCAAFB NCAABB
country	Object containing data on the athlete's native country. Contains the following properties:
	id The unique ID for the country in ESPN's systems.
	abbreviation Text abbreviation for the country, e.g. "USA."
	flags If enabled, returns a collection of country flag images containing href, width, and height attributes.
schools	Object containing data on schools that the athlete attended/currently attends. Not available for all sports. Properties include:	NCAAFB NCAABB	NCAAFB NCAABB
	id ID of the school in ESPN's systems.	NCAAFB NCAABB	NCAAFB NCAABB
	name String representation of the school name.	NCAAFB NCAABB	NCAAFB NCAABB
rookieYear	The athlete's first professional year playing the sport.
experience	Number of full seasons the athlete has played at their competitive level (i.e. pro/college). Not available for tennis/racing/golf/soccer.
athleteStatusId	ID corresponding to the athlete's status on the team. Possible values are:
	1 Active
	2 Inactive/Retired
	3 Disabled
	4 Minors
	5 Suspended
	6 Bereavement
	7 Not with team
	8 Minors
	9 Free Agent
	10 Disabled/60
	11 Non-roster invite
athleteStatus	Text representation of the athlete's current status.
injuryStatusId	ID corresponding to the athlete's specific injury, if applicable. Possibles values are:
	0 Active
	1 Probable
	2 Questionable
	3 Doubtful
	4 Out
	5 Injured reserve
	6 Day-to-day
	10 15-day disabled list
	11 60-day disabled list
injuryStatus	Text representation of the athlete's current injury status, if applicable.
headshots	Collection of athlete headshots as specified below, each containing href, width, and height attributes. Soccer, recruiting, and WNBA not currently supported. Note: clients apps must be responsible for handling missing headshots as not every athlete has one.
	full 600x436 athlete headshot
	xlarge 350x254 athlete headshot
	large 65x90 athlete headshot
	medium 43x60 athlete headshot
	small 34x48 athlete headshot
	xsmall 28x38 athlete headshot
	fantasy 200x145 athlete headshot
team	Team object with basic properties (if athlete competes in a team sport) indicating their team for the time period selected.
	gamecast 120x90 athlete headshot
positions	Array of position objects containing data on what position the athlete plays (if a team sport). These are ranked in order of importance. Properties include:
	id ID corresponding the to athlete's position
	abbreviation Abbreviation used for the position, e.g. "SP" for starting pitcher in baseball.
	name Full text representation of the athlete's position, e.g. "Starting Pitcher."
positionsPlayed	Collection of position objects denoting the positions the athlete has played during the given season (if a team sport). Properties include:
	id ID corresponding the to athlete's position.
	abbreviation Abbreviation used for the position, e.g. "SP" for starting pitcher in baseball.
	name Full text representation of the athlete's position, e.g. "Starting Pitcher."
links	Collection of relevant API endpoints and canonical URLs for the athlete.

The following tables outline the statistics returned for various sports when the "statistics" property is enabled.

General Stats Extension

Element	Description	Availability
		public	partner	premium partner	espn
statistics	Array of statistics objects, each containing the following properties:
	season Object containing the following properties:
	year - 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.
	statCategories Array of statistical categories, each containing relevant stats for the athlete/sport. Details of stat categories and statistics by sport are outlined in the sports stat extension documented below. Note that stat categories will only be returned for athletes that have accumulated statistics in that category. Each statCategory object contains:
	name - The name of the category, i.e. "batting." Sports without multiple stat cateogories live in a "generalStatistics" category.
	description - Text description of the category, suitable for display. Note that this field is also subject to language translation.
	stats - Array of stats objects, each containing name/description/value/abbreviation properties. Specific stats are documented below.

College Football Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
passing	Object containing passing statistics as detailed below:
	completions
	passingAttempts
	completionPercentage
	passingYards
	yardsPerPassAttempt
	passingTouchdowns
	longPassing
	interceptions
	passingFumbles
	collegeQuarterbackRating
rushing	Object containing rushing statistics as detailed below:
	rushingAttempts
	rushingYards
	yardsPerRushAttempt
	longRushing
	rushingTouchdowns
recieving	Object containing receiving statistics as detailed below:
	receptions
	receivingYards
	yardsPerReception
	longReception
	receivingTouchdowns
kicking	Object containing kicking statistics as detailed below:
	fieldGoalsMade
	fieldGoalsAttempted
	fieldGoalPercentage
	fieldGoalsAttempted1_19
	fieldGoalsAttempted20_29
	fieldGoalsAttempted30_39
	fieldGoalsAttempted40_49
	fieldGoalsAttempted50
	longFieldGoalsMade
	extraPointsMade
	extraPointsAttempted
	totalKickingPoints

College Football Recruiting Extension

The following data is enabled when a request is made to any of the /recruits methods.

Element	Description	Availability
		public	partner	premium partner	espn
recruitData	Object containing college football recruiting information as outlined below:
	class The high-school graduation year for the athlete in the form of 'yyyy'.
	positionsPlayed An array of positions the athlete has played in high school, each with the following information:
	id - Integer representing the position ID in ESPN's systems.
	abbreviation - String abbreviation for the position, e.g. "OLB" for Outside Linebacker.
	name - String representation of the position, e.g. "Outside Linebacker."
	grade Rating (on scale of 100) for athlete's potential.
	status Object representing the status of the recruit's decision, containing the following properties:
	id - Integer ID corresponding to the status of the athlete's decision, as represented in ESPN's systems.
	description - Text description of the status of the athlete's decision, e.g. "Committed."
	commitSchoolId Integer ID representing the school the recruit has decided to attend.
	schools Array of schools the athlete is interested in attending, each with the following properties:
	id - Integer ID of the school in ESPN's systems.
	name - String representation of the school, e.g. "Georgia Tech."
	type - The type of school. Will always be set to "college."

Golf Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
generalStatistics	Misc. statistics for the athlete.
	tournamentsPlayed
	cutsMade
	topTenFinishes
	wins
	roundsPlayed
	holesPlayed
	averageScore
	cupPoints
	prizeMoney
	majorTournamentsPlayed
	majorCutsMade
	majorTopTenFinishes
	majorWins
	majorRoundsPlayed
	majorHolesPlayed
	majorAverageScore
	majorCupPoints
	majorPrizeMoney

Men's College Basketball Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
generalStatistics	Misc. statistics for the player.
	gamesPlayed
	gamesStarted
	minutes
	fieldGoalsMade
	fieldGoalsAttempted
	fieldGoalPercentage
	threePointFieldGoalsMade
	threePointFieldGoalsAttempted
	threePointFieldGoalPercentage
	freeThrowsMade
	freeThrowsAttempted
	freeThrowPercentage
	offensiveRebounds
	defensiveRebounds
	rebounds
	assists
	blocks
	steals
	fouls
	turnovers
	points
	ejections
	doubleDoubles
	tripleDoubles

MLB Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
batting	Object containing batting statistics as detailed below:
	gamesPlayed
	atBats
	runs
	hits
	doubles
	triples
	homeRuns
	runsBattedIn
	walks
	strikeouts
	stolenBases
	caughtStealing
	battingAverage
	onBasePercentage
	slugAverage
	plateApperances
	pitches
	totalBases
	hitByPitch
fielding	Object containing fielding statistics as specified below.
	gamesPlayed
	gamesStarted
	fullInningsPlayed
	totalChances
	putouts
	assists
	errors
	doublePlays
	fieldingPercentage
	rangeFactor
	zoneRating
	passedBalls
pitching	Object containing pitching statistics as detailed below:
	gamesPlayed
	gamesStarted
	completeGames
	shutouts
	fullInnings
	hits
	runs
	earnedRuns
	homeRuns
	walks
	strikeouts
	wins
	losses
	saves
	holds
	blownSaves
	earnedRunAverage
	pitches
	battersFaced
	battersHit
	wildPitches
	balks
	partInnings
	pitchCount
	winPercentage
generalStatistics	Misc. statistics for the player.
	salary

NBA Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
generalStatistics	Misc. statistics for the athlete.
	gamesPlayed
	gamesStarted
	minutes
	fieldGoalsMade
	fieldGoalsAttempted
	fieldGoalPercentage
	threePointFieldGoalsMade
	threePointFieldGoalsAttempted
	threePointFieldGoalPercentage
	freeThrowsMade
	freeThrowsAttempted
	freeThrowPercentage
	offensiveRebounds
	defensiveRebounds
	rebounds
	assists
	blocks
	steals
	fouls
	turnovers
	points
	ejections
	doubleDoubles
	tripleDoubles
	salary

NFL Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
passing	Object containing passing statistics as detailed below:
	gamesPlayed
	completions
	passingAttempts
	completionPercentage
	passingYards
	yardsPerPassAttempt
	passingTouchdowns
	longPassing
	interceptions
	passingFumbles
	quarterbackRating
rushing	Object containing rushing statistics as detailed below:
	gamesPlayed
	rushingAttempts
	rushingYards
	yardsPerRushAttempt
	longRushing
	rushingTouchdowns
	rushingFirstDowns
	rushingFumbles
	rushingFumblesLost
receiving	Object containing receiving statistics as detailed below:
	gamesPlayed
	receptions
	receivingTargets
	receivingYards
	yardsPerReception
	longReception
	receivingTouchdowns
	receivingFirstDowns
	receivingFumbles
	receivingFumblesLost
defense	Object containing defensive statistics as detailed below:
	gamesPlayed
	totalTackles
	unassistedTackles
	assistedTackles
	sacks
	fumblesForced
	fumblesRecovered
	fumblesRecoveredYards
	interceptions
	interceptionYards
	averageInterceptionYards
	longInterception
	interceptionTouchdowns
	passesDefended
	stuffs
	stuffYards
	kicksBlocked
kicking	Object containing kicking statistics as detailed below:
	gamesPlayed
	fieldGoalsMade
	fieldGoalsAttempted
	fieldGoalsAttempted1_19
	fieldGoalsAttempted20_29
	fieldGoalsAttempted30_39
	fieldGoalsAttempted40_49
	fieldGoalsAttempted50
	longFieldGoalMade
	extraPointsMade
	extraPointsAttempted
	totalKickingPoints
punting	Object containing punting statistics as detailed below:
	gamesPlayed
	punts
	grossAveragePuntYards
	longPunt
	puntYards
	puntsBlocked
	touchbackPercentage
	puntsInside20
	puntsInside20Percentage
	puntReturns
	puntReturnYards
	averagePuntReturnYards
	netAveragePuntYards

NHL Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
offense	Offensive statistics for the player.
	gamesPlayed
	gamesStarted
	goals
	assists
	points
	plusMinus
	penaltyMinutes
	shotsTotal
	shootingPercentage
	powerPlayGoals
	powerPlayAssists
	shortHandedGoals
	shortHandedAssists
	gameWinningGoals
	gameTyingGoals
	averageTimeOnIce
	production
defense	Defensive (goaltending) statistics for the player.
	gamesPlayed
	gamesStarted
	averageTimeOnIce
	wins
	losses
	ties
	overtimeLosses
	goalsAgainst
	averageGoalsAgainst
	shotsAgainst
	saves
	savePercentage
	shutouts

Racing Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
generalStatistics	Misc. statistics for the athlete.
	starts
	wins
	poles
	topFiveFinishes
	topTenFinishes
	lapsLed
	prizeMoney
	championshipPoints
	averageStartPosition
	averageLapsCompleted
	averageFinishPosition
	carNumber
	carMake

Soccer Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
outfield	Outfield statistics for the player.
	gamesStarted
	substitutions
	goals
	assists
	shots
	shotsOnTarget
	foulsCommitted
	foulsSuffered
	yellowCards
	redCards
	offsides
goalkeeping	Goalkeeping statistics for the player.
	starts
	substitutions
	saves
	wins
	draws
	losses
	foulsCommitted
	foulsSuffered
	yellowCards
	redCards

Tennis Stats Extension

Stat Category	Stat Name	Availability
		public	partner	premium partner	espn
generalStatistics	Misc. statistics for the athlete.
	prizeMoney
	singlesTitles
	doublesTitles
	singlesWon
	singlesLost

Sample Response

Sample Code