ESPN Teams Data

Teams beta

Smells like team spirit
  • The ESPN Teams API enables you to get information, including roster, stats, and more, for individual teams. You can also fetch teams by conference or division.

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

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

    Team information is available for most major sports.

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

    Sample Teams Requests

    Action URI Description
    GET http://api.espn.com/v1/sports/baseball/mlb/teams All MLB teams.
    GET http://api.espn.com/v1/sports/baseball/mlb/teams/2 Specific MLB team.
    GET http://api.espn.com/v1/sports/baseball/mlb/teams/2?enable=roster Specific MLB team, including the current roster. Subject to access tier.
    GET http://api.espn.com/v1/sports/baseball/mlb/teams?groups=1 All teams within the American League East division in MLB.
    GET http://api.espn.com/v1/sports/baseball/mlb/teams?groups=1&lang=es All teams within the American League East division in MLB, with Spanish-language option enabled.
  • Quick Navigation

    Resources

    Resource Name Description Availability
    public 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/basketball/womens-college-basketball NCAA Women's College Basketball
    /sports/football/college-football NCAA College Football
    /sports/football/nfl National Football League (NFL)
    /sports/hockey/nhl National Hockey League (NHL)
    /sports/soccer Professional soccer. Useful as soccer teams may participate in more than one league/tournament within a given season.
    /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
    public strategic
    partner
    espn
    /teams Retrieves a list of teams within a sport and league, with corresponding API links.
    /teams/:id Returns information about a specific team.
    Back to top

     

    URI Parameters

    Parameter Description Availability
    public strategic
    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).
    venues Stadium information for the venue that the team plays in
    statistics Team-specific statistics
    ranks Returns an array of rank objects corresponding to the team, e.g. AP Poll, USA Today Poll, BCS Ranking, ESPN Power Ranking, etc. 'rank' types vary by sport.
    roster - team roster. Can only be used when specifying a single team, otherwise is ignored.
    leaders - team's current statistical leaders across key categories
    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 and tennis.
    rostertype When roster is enabled, rostertype can be set to either of the following options. Note: this option is only valid for MLB.
    full Full team roster (includes injured/inactive players). This is the default roster view.
    active Active players
    dates Date in the form of "yyyy" that can be used to return players that played for a team in a given year.
    zipcode A 5-digit zip code used to return relevant teams corresponding to the location.
    logosize Specific image size to return for team logos. Supported sizes are:
    full 110x110.
    medium 80x80.
    small 50x50.
    xsmall 40x40.
    xxsmall 25x25.
    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
    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 a 'teams' collection and also 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.
    abbreviation the abbreviation for the league/conference/division, e.g. "al" for "American League."
    teams Collection of team objects within 'leagues' containing all the properties below:
    id The team's ID within that sport.
    uid A globally unique string identifier for the sports entity in ESPN's systems.
    location The team's location, e.g. "New York."
    name The team's name, e.g. "Yankees."
    nickname The team's nickname, e.g. "Yankees."
    abbreviation The team's abbreviation, e.g. "nyy."
    color Hexadecimal value of the team's identifying color, e.g. "00314B"
    logos Collection of team logos as specified below, each containing href, width, and height attributes. Note that soccer support is limited to the following leagues: Spanish Primera Division (esp.1), English Premier League (eng.1), Italian Serie A (ita.1), Portuguese Liga (por.1), Bundesliga (ger.1), Ligue 1 (fra.1), MLS (usa.1), Mexico (mex.1), Primera División de Argentina (arg.1), Fútbol Profesional Colombiano (col.1), and FIFA and world tournaments .
    full Largest, non-resized team logo available, currently 500x500.
    large 110x110 team logo
    medium 80x80 team logo
    small 50x50 team logo
    xsmall 40x40 team logo
    xxsmall 25x25 team logo
    record Object containing the following data:
    summary A string representation of the team's record, e.g. "75-42".
    wins Wins for the season specified.
    losses Losses for the season specified.
    ties Ties for the season specified (where applicable).
    overTimeLosses Overtime (or extra inning) losses for the season specified. 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.
    ranks When enabled, returns an array of rank objects containing the following properties:
    type Enum value indicating the type of ranking. Possible values across sports include "power" (ESPN Power Rankings), "ap" (AP Poll), "bcs" (BCS Ranking)", "seed" (Seed in current tournament), etc.
    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.
    roster When enabled, contains a collection of athletes. See the Athlete API for details.
    leaders When enabled, contains a collection of season stat leaders for the team. Data includes:
    stat
    id
    firstName
    lastName
    links Collection of relevant API endpoints
    links Collection of relevant API endpoints and canonical URLs for the team
    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 teams 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 Basketball Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    offense Object containing offensive statistics as detailed below:
    gamesPlayed
    points
    fieldGoalsMade
    fieldGoalsAttempted
    fieldGoalPercentage
    threePointFieldGoalsMade
    threePointFieldGoalsAttempted
    threePointFieldGoalPercentage
    freeThrowsMade
    freeThrowsAttempted
    freeThrowPercentage
    pointsPerShot
    adjustedFieldGoalPercentage
    generalStatistics Misc. statistics for the team.
    gamesPlayed
    offensiveRebounds
    defensiveRebounds
    rebounds
    assists
    blocks
    steals
    turnovers
    fouls
    ejections
    Back to top

    College Football Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    offense Object containing general offense statistics as detailed below:
    gamesPlayed
    yards
    points
    firstDowns
    rushingFirstDowns
    passingFirstDowns
    thirdDownConversions
    thirdDownAttempts
    fourthDownConversions
    fourthDownAttempts
    firstDownPenalties
    penalties
    penaltyYards
    yardsPerGame
    pointsPerGame
    passing Object containing passing statistics as detailed below:
    gamesPlayed
    passingAttempts
    completions
    completionPercentage
    passingYards
    longPassing
    passingTouchdowns
    interceptions
    sacks
    sackedYardsLost
    quarterbackRating
    rushing Object containing rushing statistics as detailed below:
    gamesPlayed
    rushingAttempts
    rushingYards
    yardsPerRushAttempt
    longRushing
    rushingTouchdowns
    rushingFumbles
    rushingFumblesLost
    receiving Object containing receiving statistics as detailed below:
    gamesPlayed
    receptions
    receivingYards
    longReception
    receivingTouchdowns
    receivingFumbles
    receivingFumblesLost
    defense Object containing defensive statistics as detailed below:
    gamesPlayed
    totalTackles
    unassistedTackles
    assistedTackles
    sacks
    sackYards
    passesDefended
    interceptions
    interceptionYards
    longInterception
    interceptionTouchdowns
    fumblesForced
    fumblesRecovered
    fumblesRecoveredTouchdowns
    returning Object containing kick return statistics as detailed below:
    gamesPlayed
    kickReturns
    kickReturnYards
    longKickReturn
    kickReturnTouchdowns
    puntReturns
    puntReturnYards
    longPuntReturn
    puntReturnTouchdowns
    puntReturnFairCatches
    kicking Object containing kicking statistics as detailed below:
    gamesPlayed
    fieldGoalsMade
    fieldGoalsAttempted
    fieldGoalsMade1_19
    fieldGoalsAttempted1_19
    fieldGoalsMade20_29
    fieldGoalsAttempted20_29
    fieldGoalsMade30_29
    fieldGoalsAttempted30_39
    fieldGoalsMade40_49
    fieldGoalsAttempted40_49
    fieldGoalsMade50
    fieldGoalsAttempted50
    longFieldGoalMade
    extraPointsMade
    extraPointsAttempted
    punting Object containing punting statistics as detailed below:
    gamesPlayed
    punts
    puntingYards
    longPunt
    grossAveragePuntYards
    netAveragePuntYards
    puntsBlocked
    puntsInside20
    touchbacks
    fairCatches
    puntReturns
    puntReturnYards
    averagePuntReturnYards
    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
    totalBases
    runsBattedIn
    battingAverage
    onBasePercentage
    slugAverage
    onBasePlusSluggingPercentage
    walks
    strikeouts
    stolenBases
    caughtStealing
    plateApperances
    pitches
    hitByPitch
    fielding Object containing fielding statistics as detailed below.
    gamesPlayed
    errors
    fieldingPercentage
    assists
    putouts
    totalChances
    fullInningsPlayed
    doublePlays
    rangeFactor
    zoneRating
    passedBalls
    pitching Object containing pitching statistics as detailed below:
    gamesPlayed
    wins
    losses
    earnedRunAverage
    completeGames
    shutouts
    inningsPitched
    qualityStarts
    earnedRuns
    runs
    walks
    strikeouts
    battingAverageAgainst
    hits
    homeRuns
    saves
    holds
    blownSaves
    pitches
    battersFaced
    battersHit
    wildPitches
    balks
    winPercentage
    Back to top

    NBA Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    offense Object containing offensive statistics as detailed below:
    gamesPlayed
    points
    fieldGoalsMade
    fieldGoalsAttempted
    fieldGoalPercentage
    threePointFieldGoalsMade
    threePointFieldGoalsAttempted
    threePointFieldGoalPercentage
    freeThrowsMade
    freeThrowsAttempted
    freeThrowPercentage
    pointsPerShot
    adjustedFieldGoalPercentage
    defense Object containing defensive statistics as detailed below:
    gamesPlayed
    opponentPoints
    opponentFieldGoalsMade
    opponentFieldGoalsAttempted
    opponentFieldGoalPercentage
    opponentThreePointFieldGoalsMade
    opponentThreePointFieldGoalsAttempted
    opponentThreePointFieldGoalPercentage
    opponentFreeThrowsMade
    opponentFreeThrowsAttempted
    opponentFreeThrowPercentage
    opponentPointsPerShot
    opponentAdjustedFieldGoalPercentage
    generalStatistics Misc. statistics for the team.
    gamesPlayed
    offensiveRebounds
    opponentOffensiveRebounds
    defensiveRebounds
    opponentDefensiveRebounds
    rebounds
    opponentRebounds
    assists
    opponentAssists
    blocks
    opponentBlocks
    steals
    opponentSteals
    turnovers
    opponentTurnovers
    fouls
    ejections
    Back to top

    NFL Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    offense Object containing general offense statistics as detailed below:
    gamesPlayed
    yards
    points
    firstDowns
    rushingFirstDowns
    passingFirstDowns
    thirdDownConversions
    thirdDownAttempts
    fourthDownConversions
    fourthDownAttempts
    firstDownPenalties
    penalties
    penaltyYards
    yardsPerGame
    pointsPerGame
    passing Object containing passing statistics as detailed below:
    gamesPlayed
    passingAttempts
    completions
    completionPercentage
    passingYards
    longPassing
    passingTouchdowns
    interceptions
    sacks
    sackedYardsLost
    quarterbackRating
    rushing Object containing rushing statistics as detailed below:
    gamesPlayed
    rushingAttempts
    rushingYards
    yardsPerRushAttempt
    longRushing
    rushingTouchdowns
    rushingFumbles
    rushingFumblesLost
    receiving Object containing receiving statistics as detailed below:
    gamesPlayed
    receptions
    receivingYards
    longReception
    receivingTouchdowns
    receivingFumbles
    receivingFumblesLost
    defense Object containing defensive statistics as detailed below:
    gamesPlayed
    totalTackles
    unassistedTackles
    assistedTackles
    sacks
    sackYards
    passesDefended
    interceptions
    interceptionYards
    longInterception
    interceptionTouchdowns
    fumblesForced
    fumblesRecovered
    fumblesRecoveredTouchdowns
    returning Object containing kick returning statistics as detailed below:
    gamesPlayed
    kickReturns
    kickReturnYards
    longKickReturn
    kickReturnTouchdowns
    puntReturns
    puntReturnYards
    longPuntReturn
    puntReturnTouchdowns
    puntReturnFairCatches
    kicking Object containing kicking statistics as detailed below:
    gamesPlayed
    fieldGoalsMade
    fieldGoalsAttempted
    fieldGoalsMade1_19
    fieldGoalsAttempted1_19
    fieldGoalsMade20_29
    fieldGoalsAttempted20_29
    fieldGoalsMade30_39
    fieldGoalsAttempted30_39
    fieldGoalsMade40_49
    fieldGoalsAttempted40_49
    fieldGoalsMade50
    fieldGoalsAttempted50
    longFieldGoalMade
    extraPointsMade
    extraPointsAttempted
    punting Object containing punting statistics as detailed below:
    gamesPlayed
    punts
    puntingYards
    longPunt
    grossAveragePuntYards
    netAveragePuntYards
    puntsBlocked
    puntsInside20
    touchbacks
    fairCatches
    puntReturns
    puntReturnYards
    averagePuntReturnYards
    Back to top

     

    NHL Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    offense Object containing offensive statistics as detailed below:
    gamesPlayed
    goals
    shotsTotal
    powerPlayGoals
    powerPlayOpportunities
    shortHandedGoals
    assists
    points
    penaltyMinutes
    shootingPercentage
    powerPlayAssists
    shortHandedAssists
    defense Object containing defensive statistics as detailed below:
    gamesPlayed
    goalsAgainst
    shotsAgainst
    savePercentage
    shortHandedGoalsAgainst
    powerPlayGoalsAgainst
    penaltyKillPercentage
    averageGoalsAgainst
    blockedShots
    saves
    shutouts
    majorPenalties Object containing major penalty statistics as detailed below:
    gamesPlayed
    penaltyMinutes
    majorPenalties
    misconducts
    gameMisconducts
    boardingPenalties
    unsportsmanlikePenalties
    fightingPenalties
    instigatorPenalties
    timeBetweenFights
    minorPenalties Object containing minor penalty statistics as detailed below:
    gamesPlayed
    penaltyMinutes
    minorPenalties
    hookingPenalties
    trippingPenalties
    roughingPenalties
    holdingPenalties
    interferencePenalties
    slashingPenalties
    highStickingPenalties
    crossCheckingPenalties
    stickHoldingPenalties
    goalieInterferencePenalties
    Back to top

     

    Soccer Stats Extension

    Stat Category Stat Name Availability
    public strategic
    partner
    espn
    generalStatistics Object containing general soccer team statistics as detailed below:
    gamesPlayed
    wins
    losses
    draws
    goalsFor
    goalsAgainst
    goalsDifference
    goalsForAverage
    goalsAgainstAverage
    pointsPerGame
    points
    rank
    Back to top

     

    Sample Response

    XML

    The following XML output was rendered with a public key calling:
    http://api.espn.com/v1/sports/basketball/nba/teams/2?apikey=:yourkey.

     

    JSON

    The following JSON output was rendered with a public key calling:
    http://api.espn.com/v1/sports/basketball/nba/teams/2?apikey=:yourkey.

    Back to top
  • Sample Code

    JavaScript
    
    // Example JSONP request with jQuery
    $.ajax({
    	url: "http://api.espn.com/v1/sports/baseball/mlb/teams",
    	data: {
    		// enter your developer api key here
    		apikey: "{api key}",
    		// the type of data you're expecting back from the api
    		_accept: "application/json"
    	},
    	dataType: "jsonp",
    	success: function(data) {
    		// create an unordered list of headlines
    		var ul = $('<ul/>');
    		$.each(data.name, function() {
    			var li = $('<li/>').text(this.name);
    			ul.append(li)
    		});
    		// append this list to the document body
    		$('body').append(ul);
    	},
    	error: function() {
    		 // handle the error
    	}
    });