ESPN Scores and Schedules Data

Scores & Schedules beta

We never miss a game
  • The ESPN Scores & Schedules API provides game/match information, including start times, venue, competitors, score, and stats across every major sport. Depth of statistics and dat  varies by sport. 

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

    Availability
    Public Strategic Partner ESPN
  • The ESPN Scores & Schedules API accepts a GET request.

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

    Sample Scores & Schedules Requests

    Action URI Description
    GET http://api.espn.com/v1/sports/baseball/mlb/events Current day's game information for MLB.
    GET http://api.espn.com/v1/sports/baseball/mlb/events?lang=es Current day's game information for MLB with optional Spanish-language translations enabled.
    GET http://api.espn.com/v1/sports/baseball/mlb/events?groups=7 American League event data for MLB for current day.
    GET http://api.espn.com/v1/sports/baseball/mlb/teams/2/events?dates=2010 Schedule and scores information for a particular MLB team for the 2010 season.
    GET http://api.espn.com/v1/sports/baseball/mlb/events/320328111 Specific MLB game information.
    GET http://api.espn.com/v1/sports/events/top Top sports events as highlighted by ESPN's editorial team.
    GET http://api.espn.com/v1/sports/events?leagues=nhl,mens-college-basketball NHL and men's college basketball events for the current day.
    GET http://api.espn.com/v1/sports/football/college-football/events?advance=true&enable=ranks NCAA Top 25 Football events for the most appropriate week, with ranking information enabled.
    GET http://api.espn.com/v1/sports/football/college-football/events?advance=true&enable=ranks NCAA Top 25 Football events for the most appropriate week, with ranking information enabled.
    GET http://api.espn.com/v1/sports/golf/pga/events?advance=true&enable=flags,statistics&competitorlimit=3 Most appropriate PGA Golf event, with country flags and golfer statistics enabled for the top 3 golfers in the leaderboard only.
  • Quick Navigation

    Resources

    Resource Name Description Availability
    public strategic
    partner
    espn
    /sports All supported sports
    /sports/baseball/college-baseball NCAA Men's Baseball
    /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 (WNBA)
    /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/lpga Ladies' Professional Golf Association (LPGA) Golf
    /sports/golf/ntw Nationwide Tour Golf
    /sports/golf/pga Professional Golfers' Association (PGA) Golf
    /sports/golf/sga Champions Tour Golf
    /sports/hockey/mens-college-hockey NCAA Men's Hockey
    /sports/hockey/womens-college-hockey NCAA Women's Hockey
    /sports/hockey/nhl National Hockey League (NHL)
    /sports/lacrosse/mens-college-lacrosse NCAA Men's Lacrosse
    /sports/lacrosse/womens-college-lacrosse NCAA Women's Lacrosse
    /sports/mma Mixed Martial Arts
    /sports/mma/:leagueAbbrev Specific Mixed Martial Arts league.
    Use a helper API call for a complete list of supported MMA leagues.
    /sports/olympics Olympic Games
    /sports/olympics/:olympicSport Specific Olympics sport/discipline (e.g. soccer, badminton, swimming, etc).
    Use a helper API call for a complete list of supported Olympics sports.
    /sports/racing Professional auto racing
    /sports/racing/f1 Formula 1 Racing
    /sports/racing/irl IndyCar Series Racing
    /sports/racing/nhra National Hot Rod Association Racing
    /sports/racing/sprint NASCAR Sprint Racing
    /sports/racing/truck NASCAR Truck Racing
    /sports/soccer Professional Soccer
    /sports/soccer/:leagueAbbrev Specific professional soccer league.
    Use a helper API call for a complete list of supported soccer leagues.
    /sports/soccer/mens-college-soccer NCAA Men's Soccer
    /sports/soccer/womens-college-soccer NCAA Women's Soccer
    /sports/softball/college-softball NCAA Women's Softball
    /sports/tennis Professional Tennis
    /sports/tennis/atp Association of Tennis Professionals
    /sports/tennis/wta Women's Tennis Association
    /sports/volleyball/mens-college-volleyball NCAA Men's Volleyball
    /sports/volleyball/womens-college-volleyball NCAA Women's Volleyball
    /sports/water-polo/mens-college-water-polo NCAA Men's Water Polo
    /sports/water-polo/womens-college-water-polo NCAA Women's Water Polo
    Back to top

     

    Methods

    Method Description Availability
    public strategic
    partner
    espn
    /events Events for a given sport/league. Defaults to current day's events for all sports except football, which defaults to current week, and NHRA racing, which defaults to current year. For college football and college basketball, also defaults to AP Top 25 games.
    /events/top Day's top events as determined by ESPN's editorial team. Only applicable to /sports resource.
    /events/:eventId Information for a particular game/match.
    /teams/:teamId/events Events for a particular team for the current day (all team sports except for football) or current week (football). Only applicable to team sports.
    Back to top

     

    URI Parameters

    In addition to the standard URI parameters, the ESPN Scores & Schedules API also supports the following URI parameters:

    national, tv, mobile, web and radio
    Parameter Description Availability
    public strategic
    partner
    espn
    groups Integer (e.g. groups=7) that limits the event results to a specific group/division. To see a list of group IDs for a given league, use our Helper API calls.
    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).
    linescores Enables linescores for /events and /events/top methods. Note that linescores are automatically enabled when using the /events/:eventId method.
    odds Enables game line/odds information for the event. This is disabled by default.
    broadcasts Enables TV broadcast information, including the network name and whether it's nationally or locally televised.
    logos Enables team logos.
    flags For individual sports (current support for Olympics, Golf, and Tennis) returns the athlete's affiliated country object and links to flag images, each containing href, width, and height attributes. Only works with /events/:eventId method.
    weather For MLB, NCAA Football (where available), NFL, and Racing events (where available) returns weather information for the location where the event is being played. Only works with /events/:eventId method.
    series For MLB, NBA, and NHL, returns head-to-head series information for the current series between the teams. Useful for indicating current state of Playoff Series.
    ranks Returns an array of rank objects corresponding to the competitor, e.g. AP Poll, USA Today Poll, BCS Ranking, ESPN Power Ranking, etc. 'rank' types vary by sport.
    statistics Athlete-specific statistics for the event. This can be enabled for all events where statistics are available when used with the /events/:eventId method. For golf, racing, and MMA, this can also be enabled on the /events method. This replaces the stats property, which is now DEPRECATED from the Beta release of this API and should no longer be used.
    lineup Enables a lineup array within the team object for team sports. Useful for printing box score information when used in conjunction with enable=statistics. Currently only supported for MLB, and only applicable to /events/:eventId method.
    disable Optional flag to disable specific information, with the following options. Accepts a single value or a comma delimited string of values (i.e. disable=a,b,c).
    links Removes event-specific links to GameCast, game previews, recaps, etc for the event. This is enabled by default.
    venues Removes venue/stadium information for the event. This is enabled by default.
    stats Removes event-specific statistics information. This is enabled by default.
    season Removes the season object from the response.
    notes Removes the array of game notes, if applicable to the game.
    sports Removes the containing 'sports' array from the response. Not applicable for /sports/events and /sports/events/top methods.
    leagues Removes the containing 'leagues' array from the response. Not applicable for the /sports/events, /sports/events/top/sports/:sportName/events
    athletes Removes array of athletes playing in the event. Only applies when /events/:eventId method is used.
    details Removes array of plays from the event. Only applies when /events/:eventId method is used.
    team Removes the nested team object within a competitor. Useful when polling only for score updates when the competing teams are already known. Only applicable to team sports.
    linescores Removes period by period scoring for the event. Linescores are only enabled by default when using the /events/:eventId method.
    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.
    weeks Integer. Only applicable to college and NFL football. When used with a season, returns games for that particular week.
    seasontype Value corresponding to either preseason, regular season, or postseason games. Accepts string (pre/reg/post) values. If not passed will default to the season type corresponding to the current date. Not applicable to golf, tennis, racing, olympics, or soccer. "pre" season type is only available for MLB, NFL, NBA, and NHL .
    advance Boolean (default is false). Executes ESPN-specific business logic to return the most appropriate event(s) for the selected API request. Typically used in conjunction w/ scores apps to always display events, regardless of date. Not applicable to /top method or NHRA events. Also not available for lower tier NCAA sports.
    eventsforward Integer. Can be used to select a specific number of events in the future. If no date is passed, will pull from the current date. Can also be used with the 'dates' parameter to get future events from a certain date. Typically used with /:sportName/:leagueName/teams/:teamId/events method. Also available for MMA, golf, tennis, and racing.
    eventsback Integer. Can be used to select a specific number of events in the past. If no date is passed, will pull from the current date. Can also be used with the 'dates' parameter to get completed events from a certain date. Typically used with /:sportName/:leagueName/teams/:teamId/events method. Also available for MMA, golf, tennis, and racing.
    eventsrange Integer. Can be used to fetch a range of events. Best used with an odd number (for example 11) which will split an event number of completed and upcoming events on each side of the most current event. Typically used with /:sportName/:leagueName/teams/:teamId/events method. Also available for MMA, golf, tennis, and racing.
    eventsoffset Integer. Accepts an event ID to be used in conjunction with eventsforward or eventsback for paginating events. Typically used with /:sportName/:leagueName/teams/:teamId/events method.
    daysforward Integer. Can be used to retrieve events within a specific range into the future.
    daysback Integer. Can be used to retrieve events completed within the passed number of days.
    leagues Comma-separated list of leagues that can be used with a /sports/events request to include results for multiple leagues in a single API request.
    matchtype Can be used to filter on match type, specifically for tennis. Possible values are "singles" and "doubles".
    period Integer value to limit the contents of the details[] array to a specific period. Only applicable with the /events/:eventId method.
    scoredetails Boolean parameter that will show only scoring plays in the details[] array. Only applicable with the /events/:eventId method.
    lastdetail Boolean parameter that will show only the most recent play in the details[] array (vs. the entire array). Only applicable with the /events/:eventId method.
    competitorlimit Integer available for golf and racing events to limit the number of competitors returned for the competition. Default number is 10 for the /events method, and full list for the /events/:eventId method.
    logosize Specific image size to return for team logos, when enable=logos is set. Supported sizes are:
    full 110x110.
    medium 80x80.
    small 50x50.
    xsmall 40x40.
    xxsmall 25x25.
    broadcasts Specific broadcast type to return when enable=broadcasts is set. Supported types are:
    national National TV networks.
    tv All TV networks.
    mobile Mobile-only broadcast networks.
    web Web-based broadcast networks.
    radio Radio networks.
    oddslimit Accepts integer value. When enable=odds is set, limits the number of odds objects returned to the number specificied, i.e. 1, 2, etc.
    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

    Element Description Availability
    public strategic
    partner
    espn
    sports Array of sports associated with the request. 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 events and the following properties:
    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."
    id the ID of the sport 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.
    events Array of event objects within 'leagues'. Contains a collection of 'competitions' (games/matches). Also contains all the properties below:
    id the ID corresponding to the event. In many cases, this will be the same as the competition ID.
    uid A globally unique string identifier for the event in ESPN's systems.
    date date of the event, e.g. "2011-10-25T00:05:00Z".
    name Name of the event. 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.
    timeValid Boolean; Indicates if the event has an official scheduled start time.
    competitions Array within the events object that contains the following data:
    id ID for the game/match.
    uid A globally unique string identifier for the competition in ESPN's systems.
    date Date for the match, e.g. "2011-10-25T00:05:00Z".
    name Name of the competition. Not applicable for all sports.
    stats Additional statistics related to the match, including:
    attendance - Integer indicating the attendance of the match.
    priority - Integer indicating level of importance of the match as determined by ESPN's editorial team. Only returned when /events/top method is used.
    competitors Collection of teams or individuals competing in the event. Contains the following properties:
    type - String value representing the type of competitor, i.e. "team" or "athlete".
    score - the competitor's current total score in the match, represented as a string.
    homeAway - String indicating whether the competitor is the home/away team, and can be used for a  typical scoreboard display (away=top, home=bottom). Only applicable to team sports.
    isWinner - Boolean value indicating if the competitor is the winner of the competition. Can only be 'true' for a completed competition.
    team -  Team object with basic properties (if competitor is a team).
    athlete -  Athlete object with basic properties (if competitor is an athlete).
    linescores - When enabled, returns a collection of linescore objects with the following properties:
    period - Integer indicating the period number.
    label - String property used to display column headers in a linescore table. Possible values include "5", "2OT", "SO", etc.
    score - Integer indicating the number of points scored by the competitor during the period.
    details Array of play detail objects. Only displayed when the /events/:eventId method is used. See the Event Details Extension for more info.
    odds When enabled, returns a collection of objects each containing the following properties. Only available for team sports.
    casino - Object for the reporting odds source. Contains id/name/active/priority values.
    favorite - String representation of the favorite team, e.g. "Philadelphia".
    favoriteId - competitor ID of the favorite. For team sports, this will correspond to the team ID. For athlete sports, this will correspond to the athlete ID.
    underdog - String representation of the underdog team, e.g. "Philadelphia".
    underdogId - competitor ID of the underdog. For team sports, this will correspond to the team ID. For athlete sports, this will correspond to the athlete ID.
    overUnder - Integer
    spread - Integer
    initialSpread - Integer
    initialOverUnder - Integer
    price - Integer
    broadcasts When enabled, returns a collection of TV broadcast objects for the game, each with the following properties:
    typeId - ID corresponding to the type of network in ESPN's systems. 
    type - String representation of the type of network, i.e. awayTV/homeTV/nationalTV.
    broadcastId - ID of the network in ESPN's systems.
    name - String value of the network name, e.g. "ESPN."
    shortName - Shorter string value of the network name, if available.
    callLetters - Unique call sign for the transmitting station.
    isNational - Boolean indicating if the network is a national network.
    situation Object containing sport-specific situational details for competitions that are in progress. See the various sport extensions below for more details.
    series When enabled, returns a series object containing information about the current head-to-head matchup between teams. Only available for MLB, NHL, and NBA games. Contains the following properties:
    competitor1Id - Integer ID of the first competitor in the competition.
    competitor2Id - Integer ID of the second competitor in the competition.
    competitor1Wins - Number of competitions won by competitor 1 in the series.
    competitor2Wins - Number of competitions won by competitor 2 in the series.
    totalCompetitions - Maximum number of competitions (games) scheduled in the series. Can be used for "Best Of 7" or "Best of 5" type notes.
    summary - String summary of the series, e.g. "New York Leads 2-0".
    seriesFinished - Boolean indicating if the series is complete.
    seriesTitle - String indicating "Regular Season Series" or "Playoff Series".
    status object of the current status of the game/match containing the following properties:
    detail - Detailed string representation of match status, e.g. "Top 4th". This property is intended for use in scoreboard cells and displaying to users.
    state - String value indicating the event state. All conditional logic for event state should be written against this property. Possible values are "pre" / "in" / "post".
    id - Integer ID corresponding to the current game status. Possible game status values are listed below.
    0 - TBD
    1 - SCHEDULED
    2 - IN PROGRESS
    3 - FINAL
    4 - FORFEIT
    5 - CANCELLED
    6 - POSTPONED
    7 - DELAYED
    8 - SUSPENDED
    9 - FORFEIT OF HOME TEAM
    10 - FORFEIT OF AWAY TEAM
    17 - RAIN DELAY
    21 - BEGINNING OF PERIOD
    22 - END OF PERIOD
    23 - HALFTIME
    24 - OVERTIME
    25 - FIRST HALF
    26 - SECOND HALF
    27 - ABANDONED
    28 - FULL TIME
    29 - RESCHEDULED
    30 - START LIST
    31 - INTERMEDIATE
    32 - UNOFFICIAL
    33 - MEDAL OFFICIAL
    34 - GROUPINGS OFFICIAL
    35 - PLAY COMPLETE
    36 - OFFICIAL - EVENT SHORTENED
    37 - CORRECTED RESULT
    38 - RETIRED
    39 - BYE
    40 - WALKOVER
    41 - VOID
    42 - PRELIMINARY
    43 - GOLDEN TIME
    44 - SHOOTOUT
    45 - FINAL SCORE - AFTER EXTRA TIME
    46 - FINAL SCORE - AFTER GOLDEN GOAL
    47 - FINAL SCORE - AFTER PENALTIES
    48 - END EXTRA TIME
    49 - EXTRA TIME HALF TIME
    50 - FIXTURE - NO LIVE COVERAGE
    51 - FINAL SCORE - ABANDONED
    description - String representation of match status, e.g. "SCHEDULED". This data is not meant for display.
    period Integer corresponding to the current period of play.
    clock  Current time left in the period.
    notes Collection of game-related notes (if available), each with the following properties:
    type - String representing the type of note, e.g. "event"
    text - String of the actual note text, e.g. "2012 NBA All-Star Game in Orlando, FL"
    links Collection of relevant API endpoints and canonical URLs for the event.
    venues The location where the game/match is being played. Contains the following properties:
    id - Integer ID representing the venue
    name - Name of the venue (e.g. "Fenway Park")
    city - String value of the city where the venue is located (e.g. "Boston")
    state - String abbreviation the state where the venue is located (e.g. "MA")
    country - String abbreviation the country where the venue is located (e.g. "USA")
    weather When enabled, returns a weather object containing the following properties. Only applicable to /events/:eventId method and only works with MLB, NCAA Football (where available), NFL, and Racing (where available). Weather data is only available prior to and during live events.
    conditions String describing the conditions at the event, e.g. "Few Clouds".
    temperature Temperature at the event in Fahrenheit.
    windDirection Direction of the wind in degrees
    windSpeed Wind speed in MPH
    graphics Object containing images indicative of the weather conditions.
    lastUpdated Date when the weather data was last updated, in standard DateTime format ("yyyy-MM-ddTHH:mm:ssZ").
    type String representing the type of game/match, e.g. "Regular Season"
    eventSourceId Integer ID corresponding to the Event Source in ESPN's systems.
    eventSource String representation of the level of score updates available for the game. Possible values include: 
    pbp Live, real-time updates.
    basic Periodic updates.
    manual Only basic updates, such as score only.
    postgame Final/official scrubbed values.
    statSourceId Integer ID corresponding to the statistics source in ESPN's systems.
    statSource String representation of the level of stats available for the game/match. Possible values include:
    pbp Full, real-time stat feed.
    basic Only major stat categories (e.g. goals, assists for hockey).
    postgame Final/official scrubbed values.
    Back to top

     

    Baseball Extension (MLB)

    The following additional data are included for baseball competitions:

    Element Description Availability
    public strategic
    partner
    espn
    situation Object within the 'competition' object containing the following properties. Only displayed during in-progress competitions.
    balls Integer indicating the number of balls in the current at-bat.
    strikes Integer indicating the number of strikes in the current at-bat.
    outs Integer indicating the number of outs in the current inning.
    outsText String property with displayable text, i.e. "1 Out" or "2 Outs".
    onFirst Integer corresponding to the athlete ID of the baserunner on first base.
    onSecond Integer corresponding to the athlete ID of the baserunner on second base.
    onThird Integer corresponding to the athlete ID of the baserunner on third base.
    onThird Integer corresponding to the athlete ID of the baserunner on third base.
    baseRunnersText String property with displayable text, i.e. "Runner on 1st", "Runners on 1st and 2nd", etc.
    currentPitcher Integer corresponding to the athlete ID of the current pitcher.
    isInningTop Boolean indicating if it's the top of the inning.
    isInningMiddle Boolean indicating if it's the middle of the inning.
    isInningBottom Boolean indicating if it's the bottom of the inning.
    isInningEnd Boolean indicating if it's the end of the inning.
    Back to top

     

    Basketball Extension (NBA, NCAA Basketball)

    The following additional data are included for basketball competitions:

    Element Description Availability
    public strategic
    partner
    espn
    situation Object within the 'competition' object containing the following properties. Only displayed during in-progress competitions.
    awayTimeouts Integer indicating number of full timeouts remaining for the away team for the game.
    homeTimeouts Integer indicating number of full timeouts remaining for the home team for the game.
    awayTimeoutsCurrent Integer indicating number of timeouts used in the current period by the away team. Resets at the beginning of each period.
    homeTimeoutsCurrent Integer indicating number of timeouts used in the current period by the home team. Resets at the beginning of each period.
    awayTimeoutsTwoCurrent Integer indicating number of timeouts used in the last two minutes of the current period by the away team. Resets at the beginning of each period.
    homeTimeoutsTwoCurrent Integer indicating number of timeouts used in the last two minutes of the current period by the home team. Resets at the beginning of each period.
    awayTeamFouls Integer indicating the number of total fouls committed by the away team for the entire game.
    homeTeamFouls Integer indicating the number of total fouls committed by the home team for the entire game.
    awayTeamFoulsCurrent Integer indicating the number of fouls committed by the away team in the current period. Resets with each period.
    homeTeamFoulsCurrent Integer indicating the number of fouls committed by the home team in the current period. Resets with each period.
    Back to top

     

    Football Extension (College Football & NFL)

    The following additional data are included for football competitions:

    Element Description Availability
    public strategic
    partner
    espn
    situation Object within the 'competition' object containing the following properties. Only displayed during in-progress competitions.
    down Integer of the current down.
    distance Integer corresponding to the number of yards needed for a 1st down.
    downDistanceText String property with displayable text, i.e. "1st and 10".
    yardLine Integer denoting the current yard line of the team in possession.
    possessionTeamId Integer of the team ID currently in possession of the ball.
    possessionText String property with displayable text, i.e. "MIA 45".
    isRedZone Boolean indicating if the offensive team is within 20 yards of the opposing team's end zone.
    awayTimeouts Number of timeouts remaining for the away team.
    homeTimeouts Number of timeouts remaining for the home team.
    Back to top

     

    MMA Extension

    The following additional data are included for MMA competitions:

    Element Description Availability
    public strategic
    partner
    espn
    competitions A collection within the 'events' object that contains the following data:
    weightClass Object containing the following properties:
    name - The enumerator value, e.g. "middleweight"
    description - Text description of the weight class, e.g. "Middleweight""
    isTitle Boolean property indicating whether the match is a title fight.
    decisionType Object representing the final outcome of the fight. Contains the following properties:
    name - The enumerator value, e.g. "knockout"
    description - Text description of the decision type, e.g. "Knockout""
    Back to top

     

    Olympics Extension

    The following additional data are included in Olympics competitions:

    Element Description Availability
    public strategic
    partner
    espn
    season Object containing the following additional property:
    olympicSeasonId Integer ID corresponding to the specific Olympic Games in ESPN's systems.
    competitions A collection within the events object that contains the following additional data:
    isMedal Boolean indicating whether a medal will be awarded to the winner of the competition.
    Back to top

     

    Racing Extension

    The following additional data are included for racing competitions:

    Element Description Availability
    public strategic
    partner
    espn
    competitions A collection within the 'events' object that contains the following data:
    competitors Collection of drivers competing in the event. Contains the following additional properties for racing:
    place - the driver's current position in the race.
    Back to top

     

    Soccer Extension

    The following additional data are included for soccer competitions:

    Element Description Availability
    public strategic
    partner
    espn
    competitions A collection within the 'events' object that contains the following data:
    competitors Collection of teams competing in the event. Contains the following additional properties for soccer:
    shootoutScore - the team's shootout score, if applicable.
    addedClock Added time in the soccer match, if applicable. Note that this value only exists during the match. Upon match completion, it resets to 0.
    leg Object containing the leg information of the soccer match, if applicable, for matches that span more than one day. Contains the following properties:
    value - Integer indicating the leg number of the match, e.g. 1, 2, etc.
    text - Displayable text indicating the leg, i.e. "1st Leg".
    Back to top

     

    Tennis Extension

    The following additional data are included for tennis competitions:

    Element Description Availability
    public strategic
    partner
    espn
    competitions A collection within the 'events' object that contains the following data:
    round String indicating the round number, i.e. "4th Round"
    matchNumber String indicating the current match number, i.e. "2nd Match".
    matchType eNum value indicating the tennis match type, i.e. "singles" or "doubles." Can be used to trigger different score cell displays for singles vs. doubles competitions
    competitors Collection of athletes competing in the event. Contains the following additional properties for tennis:
    linescores - When enabled, returns a collection of linescore objects with the following properties:
    setScore - Integer indicating the competitor's score in the set.
    tieBreakScore - Integer indicating the competitor's tie break score in the set, if applicable.
    Back to top

     

    Competition Details Extension

    The following additional data are included when the /events/:eventId method is used. 

    Element Description Availability
    public strategic
    partner
    espn
    details Array of play detail objects within the competition object. Each detail object contains the following properties:
    id Integer ID of the play.
    clock String value corresponding to the game clock at the time of the play.
    datestamp Time snapshot when the play happened, e.g. "2011-02-02T21:09:30Z".
    playType Object containing details on the play, with the following properties:
    id - Integer ID corresponding to the type of play.
    description - String value describing the type of play, e.g. "Start Period."
    period Integer corresponding to the period when the play occurred.
    playText Text describing the play.
    shortPlayText Shorter variation of text describing the play.
    sequenceNumber Unique number corresponding to the order of the play in the competition.
    Baseball (MLB) competitions also include:
    awayScore Away team score at time of the play.
    homeScore Home team score at time of the play.
    scoreValue Number of incremental points associated with the play, e.g. 4 for a grand slam.
    teamId Team ID of the team involved in the play.
    halfInning Integer to denote whether the play happened in the top or bottom of the inning.
    batterId Integer ID of the batter involved in the play.
    pitcherId Integer ID of the pitcher involved in the play.
    awayHits Number of total hits for the away team at the time of the play.
    homeHits Number of total hits for the home team at the time of the play.
    awayErrors Number of total errors for the away team at the time of the play.
    homeErrors Number of total errors for the home team at the time of the play.
    balls Number of balls at the time of the play.
    strikes Number of strikes at the time of the play.
    outs Number of outs at the time of the play.
    Basketball (NBA, NCAABB, NCAAWBB, WNBA) competitions also include:
    awayScore Away team score at time of the play.
    homeScore Home team score at time of the play.
    scoreValue Number of incremental points associated with the play, e.g. 1 for a free throw.
    athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
    teamId Team ID of the team involved in the play.
    xCoordinate The x coordinate of where the scoring play occurred on the court.
    yCoordinate The y coordinate of where the scoring play occurred on the court.
    Football (NCAAFB, NFL) competitions also include:
    homeScore Home team score at time of the play.
    awayScore Away team score at time of the play.
    scoreValue Number of incremental points associated with the play, e.g. 6 for a touchdown.
    athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
    teamStart Object containing the following properties:
    id - Team ID with possession of the ball when the play started.
    teamEnd Object containing the following properties:
    id - Team ID with possession of the ball when the play ended.
    downDistanceText String value describing the down and distance of the current play.
    downStart Integer of the down when the play started.
    downEnd Integer of the down when the play ended.
    drive Object containing information about the current drive. Includes the following properties:
    id - Integer Id of the current drive.
    statYardage Integer indicating the amount of yards gained/lost on the play.
    yardLineStart Integer indicating the yard line that the play started on.
    yardsToEndZoneStart Integer indicating the number of yards from the end zone of the offensive team when the play began.
    yardsToEndZoneEnd Integer indicating the number of yards from the end zone of the offensive team when the play ended.
    videos Lite video object corresponding to the play. Can be used to tie video highlights to specific plays. Currently only applies to select college football games.
    Hockey (NHL) competitions also include:
    awayScore Away team score at time of the play.
    homeScore Home team score at time of the play.
    athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
    teamId Team ID of the team involved in the play.
    xCoordinate The x coordinate of where the play occurred on the ice.
    yCoordinate The y coordinate of where the play occurred on the ice.
    strength Object indicating power-play situation, with the following properties:
    id - The ID associated with the strength type.
    description - String description associated with the strength type, e.g. "even" or "shorthanded."
    Soccer competitions also include:
    awayScore Away team score at time of the play.
    homeScore Home team score at time of the play.
    athletesInvolved Array of athlete IDs involved in the play. Ranked in order of importance.
    teamId Team ID of the team involved in the play.
    xCoordinate The x coordinate of where the play occurred on the field.
    yCoordinate The y coordinate of where the play occurred on the field.
    Back to top

     

    Lineup Extension

    The following additional data are included when the /events/:eventId method is used and enable=lineup is set. Currently only supported for MLB events.

    Element Description Availability
    publicstrategic
    partner
    espn
    lineup Array of lineup objects within the team object. Each lineup object contains the following properties:
    athleteId Athlete ID.
    isStarter Boolean indicating if the athlete started the game.
    positionId ID of the player's position.
    athleteReplacing ID of the athlete this athlete replaced in the game, if applicable.
    athleteReplacedBy ID of the athlete that replaced this athlete in the game, if applicable.
    order Integer indicating the order of display within a boxscore. For MLB, #s 1-9 indicate the batting order.
    Baseball (MLB) lineups also include:
    isPinchHitter Boolean indicating if this player entered the game as a pinch hitter.
    isPinchRunner Boolean indiciating if this player entered the game as a pinch runner.
    Back to top

     

    Sample Response

    XML

    The following XML output was rendered with an internal key calling:
    http://api.espn.com/v1/sports/basketball/mens-college-basketball/events/320590008?_accept=text/xml&disable=odds,athletes&lastdetail=true&apikey=:yourkey.

     

    JSON

    The following JSON output was rendered with an internal key calling:
    http://http://api.espn.com/v1/sports/basketball/mens-college-basketball/events/320590008?disable=odds,athletes&lastdetail=true&apikey=:yourkey.

    Back to top