ESPN Leaders Data

Leaders

The most promising prospects of the season so far
  • The ESPN Leaders API enables you to get the leading athletes in specific statistics categories relevant to each supported sport.

    This API is currently a version 1 (/v1/) release.

    Availability
    Strategic Partner ESPN
  • The ESPN Leaders API accepts a GET request.

    Leader information is currently available for:

    • MLB
    • NBA
    • NCAA football
    • NCAA men's basketball
    • NFL
    • NHL
    • Soccer
    • WNBA

    The Leader API supports getting season stats leaders by league or team or game stats leaders by team and event.

    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 Leaders Requests

    Action URI Description
    GET http://api.espn.com/v1/sports/baseball/mlb/leaders MLB players leading batting and pitching stats for the current season.
    GET http://api.espn.com/v1/sports/hockey/nhl/teams/16/leaders NHL players leading offensive and defensive stats for the Pittsburgh Penguins.
    GET http://api.espn.com/v1/sports/soccer/ger.1/leaders Soccer players leading stats categories in the German Bundesliga league.
    GET http://api.espn.com/v1/sports/soccer/arg.1/teams/14/leaders?lang=es Soccer players leading stats categories for the Newell's Old Boys team in the Primera División de Argentina, with results returned in Spanish.
    GET http://api.espn.com/v1/sports/basketball/nba/teams/18/leaders?dates=2013&seasontype=reg 2013 regular season basketball stats leaders for the New York Knicks.
    GET http://api.espn.com/v1/sports/baseball/mlb/teams/2/leaders?events=340511113 Boston Red Sox stats leaders for a specific game.
  • Quick Navigation

    Resources

    Resource Name Description Availability
    strategic
    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/football/college-football NCAA College Football
    /sports/football/nfl National Football League (NFL)
    /sports/hockey/nhl National Hockey League (NHL)
    /sports/soccer/:leagueName Specific professional soccer league. Use a helper API call for a complete list of supported soccer leagues.
    Back to top

     

    Methods

    Method Description Availability
    strategic
    partner
    espn
    /leaders Returns a list of stats leaders within a sport/league for a given season, with corresponding API links.
    /teams/:teamId/leaders Returns a list of stats leaders within the specified team, with corresponding API links.
    Back to top

     

    URI Parameters

    Parameter Description Availability
    strategic
    partner
    espn
    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.
    disable Optional flag to disable specific information, with the following options:
    links Removes links to teams in the response. Links are enabled by default.
    enable Optional flag to enable specific information, with the following options:
    headshot Returns links to player headshots in various sizes. Use in conjunction with the headshotsize parameter to return specific image sizes.
    events Integer in the form of an event ID to return stats leaders for a specific team and game. Must be used in the context of a specific team in the format api.espn.com/v1/sports/:sportName/:leagueName/teams/:teamId/leaders?events=:eventId.
    headshotsize Optional flag to return a specific headshot images size when the enable=headshot parameter is used. Accepts a single value. For example, enable=headshot&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).
    lang Can be used to return content in the specified language. 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
    leaderslimit Integer specifying the maximum number of athletes to return for each stat category. By default, the API returns a maximum of 3 athletes. Specifying a value for leaderslimit enables you to return more or fewer leaders per stat.
    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.
    Back to top

     

  • Quick Navigation

    Returned Data

    Requests to this API return the following information.

    Element Description Availability
    strategic
    partner
    espn
    sports An array containing the sport associated with the request. Contains a leagues array and also has the following properties:
    name The name of the sport. For example, "baseball."
    id The ID of the sport in the ESPN API.
    leagues An array containing the specified league within the sport. The array contains the following objects:
    name String containing the name of the league. For example, "Major League Baseball".
    abbreviation The abbreviation for the league. For example, "mlb".
    id The ID of the league in the ESPN meta-tagging system.
    uid A globally unique string identifier for the sports entity in the ESPN system.
    groupId The ID, unique to the selected organizing body, of the conference/division.
    shortName String containing an abbreviation for the league, typically for display purposes. For example, "MLB".
    statistics An array containing stats leaders data. See the Statistics Object for details about the contents of this array.
    Back to top

    The following tables outline the statistics array and stats leaders returned for various sports.

    Statistics Object

    Element Description Availability
    strategic
    partner
    espn
    season An object containing metadata about the season for which the leaders stats were returned. Contains 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 ("regular" for season type = 2).
    startDate ISO 8601 format date on which the season starts.
    endDate ISO 8601 format date on which the season ends.
    statCategories An array containing stats leaders data, each containing relevant stats for the athlete/sport. Details of stat categories and statistics by sport are outlined in the sports stat tables below. Note that stat categories will only be returned for athletes that have accumulated statistics in that category. Each statCategory object contains:
    name String name of the stats category. For some sports, offensive and defensive stats leaders are categorized separately, such as "batting" and "pitching". Sports without multiple stat categories return results in a single "generalStatistics" category.
    description String description of the category, suitable for display. Available to language translation.
    leaders An array containing a single object for the overall leader of a statistics category. Similar to a leaders object in the the Stats Object, but does not contain a value property. The displayValue property contains a summary string of the athlete's stats. For example, "17 rec, 327 yds, 2 tds, 0 fumbles".
    stats An array of stats objects, each containing a name, a description, description, an abbreviation and an array of stats leaders athletes. See the Stats Object for details about the contents of this array.
    Back to top

    Stats Object

    Element Description Availability
    strategic
    partner
    espn
    name String name of the stats category, such as "pointsPerGame".
    description String description of the stats category, suitable for display. For example, "Runs Batted In".
    abbreviation String short name for the stats category, suitable for display. For example, "RBI".
    leaders An array containing the leading athletes in the stats category. The request returns a maximum of 3 leaders per array, but may have fewer. For example, for game-related leaders, if only one player scores a run or goal, the leader array for that scoring category will contain only that one athlete. Contains the following data:
    type String name of the object type attributed to the statistic, typically "athlete".
    value The numerical value of the statistic returned for the athlete. Depending on the statistic, may be an integer or a decimal value.
    displayValue String containing the value of the statistic, suitable for display.
    athlete An object containing metadata for the athlete. Contains a subset of data returned by the Athletes API including name strings, team metadata and links. See the Athletes API for details.
    Back to top

    Baseball Leader Stats

    The Leaders API returns the following stats categories for baseball (MLB) season requests. Returns a subset of results for game requests.

    • batting
    • pitching

    Batting Leader Stats

    The Leaders API returns leaders for the following batting-related stats.

    Name Description Abbreviation
    homeRuns Home Runs HR
    runsBattedIn Runs Batted In RBI
    battingAverage Batting Average AVG
    runs Runs R
    stolenBases Stolen Bases SB
    rating Rating ERAT

    Pitching Leader Stats

    The Leaders API returns leaders for the following pitching-related stats.

    Name Description Abbreviation
    wins Wins W
    earnedRunAverage Earned Run Average ERA
    saves Saves SV
    rating Rating ERAT
    Back to top

    Basketball Leader Stats

    The Leaders API returns the following stats leaders for basketball (NBA, NCAA and WNBA) season and game requests. All results are returned under the generalStatistics category.

    Season Leader Stats

    The Leaders API returns leaders for the following season-related basketball stats.

    Name Description Abbreviation
    pointsPerGame Points Per Game PPG
    assistsPerGame Assists Per Game APG
    fieldGoalPercentage Field Goal Percentage FG%
    reboundsPerGame Rebounds Per Game RPG
    blocksPerGame Blocks Per Game BPG
    stealsPerGame Steals Per Game SPG

    Game Leader Stats

    The Leaders API returns leaders for the following game-related basketball stats. Note that rating is an NBA rating for NBA and WNBA and ESPN rating for NCAA basketball.

    Name Description Abbreviation
    points Points PTS
    assists Assists AST
    rebounds Rebounds REB
    blocks Blocks BLK
    steals Steals STL
    rating Rating RAT
    Back to top

    Football Leader Stats

    The Leaders API returns the following stats categories for football (MLB and NCAA) season and game requests. Returns ratings only for game requests.

    • passing
    • rushing
    • receiving

    Passing Leader Stats

    The Leaders API returns leaders for the following passing-related football stats.

    Name Description Abbreviation
    passingYards Passing Yards YDS
    passingTouchdowns Passing Touchdowns TD
    quarterbackRating Passer (QB) Rating RAT
    rating Rating ERAT

    Rushing Leader Stats

    The Leaders API returns leaders for the following rushing-related football stats.

    Name Description Abbreviation
    rushingYards Total Rushing Yards YDS
    rushingTouchdowns Touchdowns TD
    rating Rating RAT

    Receiving Leader Stats

    The Leaders API returns leaders for the following receiving-related football stats.

    Name Description Abbreviation
    receptions Total Receptions REC
    receivingYards Total Receiving Yards YDS
    receivingTouchdowns Receiving Touchdowns TD
    rating Rating RAT
    Back to top

    Hockey Leader Stats

    The Leaders API returns the following stats categories for hockey (NHL) season and game requests.

    • offense
    • defense

    Offense Leader Stats

    The Leaders API returns leaders for the following offense-related stats.

    Name Description Abbreviation
    goals Goals G
    assists Assists A
    points Points P
    plusMinus Plus/Minus Ratings +/-
    penaltyMinutes Penalty Minutes PIM

    Defense Leader Stats

    The Leaders API returns leaders for the following defense-related stats.

    Name Description Abbreviation
    wins Wins W
    goalsAgainst Goals Against GA (game requests only)
    averageGoalsAgainst Goals Against Average GAA (season requests only)
    saves Saves SV (game requests only)
    savePercentage Save Percentage SV% (season requests only)
    shutouts Shutouts SO
    Back to top

    Soccer Leader Stats

    The Leaders API returns the following stats leaders for soccer season and game requests. All results are returned under the generalStatistics category.

    Name Description Abbreviation
    goals Goals G
    assists Assists A
    shotsOnTarget Shots on Goal SG
    yellowCards Yellow Cards YC
    redCards Red Cards RC
    foulsCommitted Fouls Committed FC
    foulsSuffered Fouls Suffered FS
    Back to top

     

    Sample Response

    XML

    The following XML output is an excerpt from a request using an authorized key calling:
    http://api.espn.com/v1/sports/basketball/nba/leaders?disable=links&apikey=:yourkey.

     

    JSON

    The following JSON output is an excerpt from a request using an authorized key calling:
    http://api.espn.com/v1/sports/basketball/nba/leaders?disable=links&apikey=:yourkey.

    Back to top
  • Sample Code

    Coming soon.