ESPN Athletes Data
Gettin’ to know your favorite players
The ESPN Athlete API allows you to get rosters of players for various sports, as well as biographical and statistical data for individual athletes.
This API is currently a version 1 (/v1/) release.
Availability Public Strategic Partner ESPN
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:
Sample Athletes Requests
Action URI Description GET http://api.espn.com/v1/sports/baseball/mlb/athletes All MLB players for the current season. GET http://api.espn.com/v1/sports/baseball/mlb/athletes/teams/2 All MLB players for a specific team. Subject to access tier. GET http://api.espn.com/v1/sports/baseball/mlb/athletes?groups=1 All MLB players in a specific division. GET http://api.espn.com/v1/sports/baseball/mlb/athletes/3748 Data for a specific MLB athlete. GET http://api.espn.com/v1/sports/soccer/eng.1/athletes Data for a specific Barclay's Premier League athlete. GET http://api.espn.com/v1/sports/baseball/mlb/athletes/3748/dates/2011?enable=stats,competitors&seasontype=reg Specific athlete's full season stats and teams played on for the 2011 regular season. Subject to access tier. GET http://api.espn.com/v1/sports/baseball/mlb/athletes/3748/dates/2011?enable=stats,competitors&seasontype=reg&lang=es Specific athlete's full season stats and teams played on for the 2011 regular season, with optional Spanish translation enabled. Subject to access tier.
Resource Name Description Availability public strategic
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
MethodsBack to top
Parameter Description Availability public strategic
espn disable Optional flag to remove specific information from the response, with the following options. Accepts a single value or a comma-delimited string of values. For example, "disable=notes,statistics". headshots Removes the headshots object containing links to athlete images. links Removes links objects from the athletes and team objects. enable Optional flag to enable specific information in the response, with the following options. Accepts a single value or a comma-delimited string of values. For example, "enable=notes,statistics". cars Returns a cars array containing data about cars in which the athlete has driven. (Racing) competitors Returns a competitors array containing data about teams for which the athlete played. (Hockey, MLB, NBA, NCAAF, NFL, Soccer, WNBA) flags Returns flags objects within the country object, providing images representing the athlete's home country flag. (Golf, Hockey, MMA, Soccer, Tennis) logos Returns logos objects within the competitors, team and teams arrays, providing images representing the team logos. Use with the logosize parameter to return specific image sizes. notes Returns a notes array containing injury status notes for the athlete. ranks Returns a ranks array of ranking objects corresponding to the athlete. (Tennis) statistics Returns athlete-specific statistics in a statistics array. See the What it Returns page for details about the statistics supported for each sport. stats DEPRECATED Returns athlete-specific statistics in a stats object. Do not use this parameter for new development. Future support is not guaranteed. teams Returns a teams array containing data about teams for which the athlete played. (Hockey, MLB, NBA, NCAAF, NCAAM, NCAAW, NFL, Soccer, WNBA) tournaments Returns a tournaments array containing data about tournaments in which the athlete played. (Golf) headshotsize Optional flag to return a specific headshot image size in the response. Accepts a single value. For example, "headshotsize=large". Supported sizes include full (600×436), xlarge (350×254), large (65×90), medium (43×60), small (34×48), xsmall (28×38), fantasy (200×145) and gamecast (120×90). groups Optional flag to filter response by group, conference or division ID. For example, "groups=7". To see a list of group IDs for a given league, use the Helper API calls. Not applicable to Golf, Tennis or requests on specific athlete IDs. lang Optional flag to return content in a specified language. Note: not all content is available in multiple languages and will return in English if no alternative is available. Accepts the following values: en English. (Default) es Spanish. seasontype Optional flag to filter response by preseason, regular season, or postseason. Typically used in conjunction with statistics. For example, "enable=statistics&seasontype=post" If not passed, response defaults to the current season type. Not applicable to Golf, Tennis or Racing. Accepts the following values: pre Preseason statistics. reg Regular season statistics. post Post-season statistics. statstype Optional flag to specify the type of athlete statistics included in the response. For example, "enable=statistics&statstype=career". Accepts the following values: season Statistics for the current season. (Default) career Statistics for each season the athlete has played. careertotals Statistics for the athlete's entire career. (MLB) vspitcher Optional flag to return batting statistics versus a specific pitcher when statistics are enabled. Accepts the athlete ID of a pitcher. For example: "enable=statistics&statstype=careertotals&vspitcher=28474". (MLB)
- 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
Requests to this API return the following information.
Element Description Availability public strategic
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. uid A globally unique string identifier for the sports entity in ESPN's systems. leagues Collection within 'sports' that contains the following properties: id the ID of the league in ESPN's meta-tagging system. uid A globally unique string identifier for the sports entity in ESPN's systems. 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 Array of objects containing information about individual athletes. See the Athletes object below for details.
Element Description Availability public strategic
espn 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
height The athlete's height in inches. NCAAFB
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
dateOfBirth The athlete's birthdate. NCAAFB
age The athlete's current age. NCAAFB
birthPlace Object containing data on where the athlete was born. Properties include: NCAAFB
city City where the athlete was born, e.g. "Miami." NCAAFB
state State where the athlete was born, e.g. "Florida." NCAAFB
country Country where the athlete was born, e.g. "USA." NCAAFB
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
id ID of the school in ESPN's systems. NCAAFB
name String representation of the school name. NCAAFB
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." ranks When enabled, returns an array of rank objects containing the following properties. Currently only applies to tennis athletes. type Enum value indicating the type of ranking. name Text description of the ranking type. value Integer value of the ranking, e.g. 27. isDefault Boolean indicating if the rank value should be displayed by default in scoreboard cells. links Collection of relevant API endpoints and canonical URLs for the athlete. notes Array containing athlete-specific injury/status notes, when available and the enable=notes parameter is used. Each notes object contains the following properties: date Date string indicating the publishing date of the note. type String indicating the subject of the note. injuryStatusId Integer ID for athlete status. See athleteStatusId above for possible values. injuryStatus String description of athlete status. description String description of the note. text String providing additional desription for the note.
The following tables outline the statistics returned for various sports when the "statistics" property is enabled.
General Stats ExtensionBack to top
College Football Stats ExtensionBack to top
College Football Recruiting Extension
The following data is enabled when a request is made to any of the /recruits methods.Back to top
Golf Stats ExtensionBack to top
Men's College Basketball Stats ExtensionBack to top
MLB Stats ExtensionBack to top
NBA Stats ExtensionBack to top
NFL Stats ExtensionBack to top
NHL Stats ExtensionBack to top
Racing Stats ExtensionBack to top
Soccer Stats ExtensionBack to top
Tennis Stats Extension
Stat Category Stat Name Availability public strategic
espn generalStatistics Misc. statistics for the athlete. prizeMoney singlesTitles doublesTitles singlesWon singlesLost
The following XML output was rendered with a public key calling:
The following JSON output was rendered with a public key calling:
Sample CodeComing soon.
- Explore APIs
- ESPN News Content
- ESPN Research Notes Data
- ESPN Athletes Data
- ESPN Standings Data
- ESPN Teams Data
- ESPN Medals Data
- ESPN Video Content
- ESPN Now Content Stream
- ESPN Scores and Schedules Data
- WatchESPN Network Programming Listings
- ESPN Audio Content
- ESPN Twitter Stream
- ESPN Photos
- ESPN Sports Calendar
- ESPN Leaders Data
- ESPN Draft Data
- ESPN Test