ESPN Athletes Data

Athletes

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:
    http://api.espn.com/:version/:resource/:method?apikey=:yourkey

    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.
  • Quick Navigation

    Resources

    Resource Name Description Availability
    publicstrategic
    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
    Back to top

     

    Methods

    Method Description Availability
    public strategic
    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.
    Back to top

     

    URI Parameters

    Parameter Description Availability
    public strategic
    partner
    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)
    Back to top

     

  • Quick Navigation

    Returned Data

    Requests to this API return the following information.

    Element Description Availability
    public strategic
    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.
    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.
    Back to top

    Athletes Data

    Element Description Availability
    public strategic
    partner
    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
    NCAABB
    height The athlete's height in inches. 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
    dateOfBirth The athlete's birthdate. NCAAFB
    NCAABB
    age The athlete's current age. NCAAFB
    NCAABB
    birthPlace Object containing data on where the athlete was born. Properties include: NCAAFB
    NCAABB
    city City where the athlete was born, e.g. "Miami." NCAAFB
    NCAABB
    state State where the athlete was born, e.g. "Florida." NCAAFB
    NCAABB
    country Country where the athlete was born, e.g. "USA." 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
    id ID of the school in ESPN's systems. NCAAFB
    NCAABB
    name String representation of the school name. 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."
    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.
    Back to top

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

    General Stats Extension

    Element Description Availability
    public strategic
    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.
    Back to top

    College Football Stats Extension

    Stat Category Stat Name Availability
    public strategic
    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
    Back to top

    College Football Recruiting Extension

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

    Element Description Availability
    public strategic
    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."
    Back to top

    Golf Stats Extension

    Stat Category Stat Name Availability
    public strategic
    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
    Back to top

    Men's College Basketball Stats Extension

    Stat Category Stat Name Availability
    public strategic
    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
    Back to top

    MLB Stats Extension

    Stat Category Stat Name Availability
    public strategic
    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
    batterVSPitching Batting statistics for the player versus a pitcher specified by the "vspitcher" parameter. See the batting stat category above for supported statistics.
    Back to top

    NBA Stats Extension

    Stat Category Stat Name Availability
    public strategic
    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
    Back to top

    NFL Stats Extension

    Stat Category Stat Name Availability
    public strategic
    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
    Back to top

    NHL Stats Extension

    Stat Category Stat Name Availability
    public strategic
    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
    Back to top

    Racing Stats Extension

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

    Soccer Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    outfield Outfield statistics for the player.
    gamesStarted
    substitutions
    goals
    assists
    shots
    shotsOnTarget
    foulsCommitted
    foulsSuffered
    yellowCards
    redCards
    offsides
    minutes
    goalsConceded
    ownGoals
    goalkeeping Goalkeeping statistics for the player.
    starts
    substitutions
    saves
    wins
    draws
    losses
    foulsCommitted
    foulsSuffered
    yellowCards
    redCards
    minutes
    cleanSheet
    penaltyKicksSaved
    penaltyKicksMissed
    goalsConceded
    Back to top

    Tennis Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    generalStatistics Misc. statistics for the athlete.
    prizeMoney
    singlesTitles
    doublesTitles
    singlesWon
    singlesLost
    Back to top

     

    Sample Response

    XML

    The following XML output was rendered with a public key calling:
    http://api.espn.com/v1/sports/hockey/nhl/athletes/3114?_accept=text/xml&apikey=:yourkey.

     

    JSON

    The following JSON output was rendered with a public key calling:
    http://api.espn.com/v1/sports/hockey/nhl/athletes/3114?apikey=:yourkey.

    Back to top
  • Sample Code

    Coming soon.