Skip to content

Instantly share code, notes, and snippets.

@quantum0813

quantum0813/espn_scoreboard_api_documentation.md

Created January 6, 2019 06:53
Show Gist options
  • Save quantum0813/6aa87103b46e84ef8ab29b2bb66905d6 to your computer and use it in GitHub Desktop.
Save quantum0813/6aa87103b46e84ef8ab29b2bb66905d6 to your computer and use it in GitHub Desktop.
Download ZIP
ESPN API v2 Scoreboard Endpoint Documentation
Raw
espn_scoreboard_api_documentation.md

ESPN API v2 Scoreboard Endpoint Documentation

URL: http://site.api.espn.com/apis/site/v2/sports/{sport-name}/{league-name}/scoreboard

For endpoints and parameters, refer to: https://gist.github.com/akeaswaran/b48b02f1c94f873c6655e7129910fc3b

Scoreboard Endpoint

The scoreboard endpoint returns a large amount of information about games for a particular sport in a particular league. This is a complete documentation of the values returned after a call to the scoreboard endpoint. The example here uses NCAA Men's Basketball as the example, but the majority of the values should be the same for all sports.

The structure of the JSON is as follows:

  • leagues [array] - A list of leagues (which should always be one), and information about each league, including start and end dates of the season.
    • id [string] - A number representing the id of the league
      • Ex: 41
    • uid [string] - A unique id representing the league (contains letters, numbers and other characters)
      • Ex: s:40~l:41
    • name [string] - The full name of the league
      • Ex: NCAA Men's Basketball
    • abbreviation [string] - The short, abbreviated name of the league
      • Ex: NCAAM
    • midsizeName [string] - The middle sized name of the league, between abbreviation and name lengths
      • Ex: NCAAM Basketball
    • slug [string] - ??? Not quite sure exactly what this is used for. It seems to correspond to the league name part of the endpoint path.
      • Ex mens-college-basketball
    • season [object] - Information about the league's season
      • year [int] - The year of the current season for the league
        • Ex: 2019
      • startDate [string] - The start date of the season, in ISO date format
        • Ex: 2018-07-01T07:00Z
      • endDate [string] - The end date of the season, in ISO date format
        • Ex: 2019-04-11T06:59Z
      • type [object] - ??? Information about the type of the league?
        • id [string] - ??? The id of the type of the league
          • Ex: 2
        • type [int] - ???
          • Ex: 2
        • name [string] - The name of the type of league
          • Ex: Regular Season
        • abbreviation [string] - An abbreviated form of the name above
          • Ex: Reg
    • calendarType [string] - ???
      • Ex: day
    • calendarIsWhitelist [boolean] - ???
      • Ex: true
    • calendarStartDate [string] - ??? Seems to correspond to season start date, ISO date format
      • Ex: 2018-07-01T07:00Z
    • calendarEndDate [string] - ??? Seems to correspond to season end date, ISO date format
      • Ex: 2019-04-11T06:59Z
    • calendar [array] - ??? An array of ISO dates, possibly corresponding to each calendar day of the season
      • Ex: ["2018-11-06T08:00Z", "2018-11-07T08:00Z",...]
  • events [array] - An array of events in the league's season, limited by date passed as parameter to endpoint
    • id [string] - A numeric id for the event
      • Ex: 401082482
    • uid [string] - The unique id for the event, contains letters, numbers, etc.
      • Ex: s:40l:41e:401082482
    • date [string] - The date for the current event, in ISO date format
      • Ex: 2019-01-05T17:00Z
    • name [string] - The name of the event, usually in the form of team 1 at team 2, or team 1 vs team 2
      • Ex: Michigan State Spartans at Ohio State Buckeyes
    • shortName [string] - The abbreviated name of the event, usually 2-5 letters for team name with vs or @ between them
      • Ex: MSU @ OSU
    • season [object] - Information about the season in which the event takes place
      • year [int] - Year of the season
        • Ex: 2019
      • type [int] - Seems to correspond to the season type above
    • competitions [array] - A list of competitions for an event (not sure of a case when there would ever be more than 1)
      • id [string] - The id of the competition
        • Ex: 401082482
      • uid [string] - The unique id of the competition, contains letters, numbers, etc.
        • Ex: s:40l:41e:401082482~c:401082482
      • date [string] - The date of the competition, in ISO date format
        • Ex: 2019-01-05T17:00Z
      • attendance [int] - The attendance for the competition
        • Ex: 18809
      • timeValid [boolean] - ???
        • Ex: true
      • neutralSite [boolean] - Whether or not the competition was hosted at a neutral location
        • Ex: false
      • conferenceCompetition [boolean] - Whether or not the competition took place between 2 opponents in the same conference
        • Ex: true
      • recent [boolean] - ???
        • Ex: false
      • venue [object] - Information about the venue in which the competition was held
        • id [string] - The id of the venue
          • Ex: 317
        • fullName [string] - The full name of the venue
          • Ex: Value City Arena
        • address [object] - The address of the venue (city, state)
          • city [string] - The city where the venue is located
            • Ex: Columbus
          • state [string] - The state where the venue is located (abbreviation)
            • Ex: OH
        • capacity [int] - The capacity of the venue
          • Ex: 18809
        • indoor [boolean] - Whether or not the venue is indoors, such as an arena, or outdoors such as a stadium
          • Ex: true
      • competitors [array] - Array of competitors in the competition (normally 2)
        • id [string] - The id of the competitor
          • Ex: 194
        • uid [string] - The unique id of the competitor
          • Ex: s:40l:41t:194
        • type [string] - The type of the competitor
          • Ex: team
        • order [int] - ???
          • Ex: 0
        • homeAway [string] - The string "home" or "away" indicating which one this competitor is
          • Ex: home
        • winner [boolean] - Whether or not this competitor won the competition
          • Ex: false
        • team [object] - Information about the team (this might not exist if competitor type is not "team")
          • id [string] - The id of the team (seems to be the same as competitor id)
            • Ex: 194
          • uid [string] - The unique id of the team (seems to be the same as competitor uid)
            • Ex: s:40l:41t:194
          • location [string] - The location of the team. In the case of college sports, this seems to be the name of the university. For pro sports it's probably the name of the city.
            • Ex: Ohio State
          • name [string] - The name of the team
            • Ex: Buckeyes
          • abbreviation [string] - The abbreviated name of the team
            • Ex: OSU
          • displayName [string] - The full display name of the team
            • Ex: Ohio State Buckeyes
          • shortDisplayName [string] - The shortened display name of the team
            • Ex: Ohio State
          • color [string] - The primary color of the team as a hex string
            • Ex: de3129
          • alternateColor [string] - The secondary color of the team as a hex string
            • Ex: 666666
          • isActive [boolean] - Whether or not the team is active (I would assume it has to be to be a competitor in the competition)
            • Ex: true
          • venue [object] - Object containing the venue id
            • id [string] - The id of the venue as described in venue object above
              • Ex: 317
          • links [array] - Array containing various links to ESPN pages containing information such as the team roster and stats
          • logo [string] - A URL for the team's logo on ESPN's website
          • conferenceId [string] - The id of the team's conference
            • Ex: 7
        • score [string] - The total amount of points scored by this team in the competition
          • Ex: 77
        • linescores [array] - The amount of points scored by this team during each quarter/half/period of the game. The values in the array are in sequential order. So, for example, in basketball, the first element is the amount of points scored by this team in the first half of the game, and the second element is the amount of points scored in the second half. For football it would be quarters, etc.
          • value [int] - The amount of points scored by this team during this period of the game
        • statistics [array] - An array containing statistics for the game such as rebounds, assists, etc. The values in this array will vary based on the sport.
          • name [string] - The name of the statistic
            • Ex: rebounds
          • abbreviation [string] - The abbreviated name of the statistics, usually a few letters
            • Ex: REB
          • displayValue [string] - The value for the statistic, usually a number or percentage
            • Ex: 26
        • leaders [array] - An array containing information about the leaders of the game, such as most points scored. Again, the data in this array will vary based on the sport.
          • name [string] - The name of the type of leader
            • Ex: points
          • displayName [string] - The "user-friendly" name for the type of leader
            • Ex: Points
          • shortDisplayName [string] - The shortened version of the display name
            • Ex: Pts
          • abbreviation [string] - The abbreviated version of the display name
            • Ex: Pts
          • leaders [array] - Information about the leaders of this type. There can be multiple leaders for each type.
            • displayValue [string] - The value corresponding to the value that made the person a leader. This will usually be a number or percentage.
              • Ex: 25
            • athlete [object] - Information about the athlete who was the leader in this category
              • id [string] - The id of the leader
                • Ex: 4277975
              • fullName [string] - The full name of the athlete
                • Ex: Kaleb Wesson
              • displayName *[string] - The display name of the athlete (not sure when this would differ from fullName)
                • Ex: Kaleb Wesson
              • shortName *[string] - The shortened name of the athlete, usually first initial and full last name
                • Ex: K. Wesson
              • links [array] - An array containing links to ESPN articles about the athlete's achievements in the competition.
              • jersey [string] - The jersey number of the athlete
                • Ex: 34
              • headshot [string] - A link to a headshot of the athlete on ESPN's website
              • position [object] - Information about the athlete's position on the team
                • abbreviation [string] - The abbreviated name for the player's position on the team
                  • Ex: F
              • team [object] - Information about the player's team
                • id [string] - The id of the team the player is on
              • active [boolean] - Whether or not the player is active on the team
                • Ex: true
            • team [object] - Yet another reference to the team
              • id [string] - The id of the team
                • Ex: 194
        • curatedRank [object] - Object containing information about the competitor's rank. May not exist if the team is not ranked. Seems to refer to the AP rankings.
          • current [int] - The team's current ranking in the AP polls
        • records [array] - An array containing information about the team's records for the current season including overall, home, away and league win records.
          • name [string] - The name of the record
            • Ex: YTD
          • abbreviation [string] - The abbreviation for the name of the record (this may not exist)
            • Ex: Game
          • type [string] - The type of the record (total, home, away, etc.)
            • Ex: total
          • summary [string] - The record itself, seems to be of the form: W-L
            • Ex: 12-2
      • notes [array] - ???
        • Ex: Example in my JSON is an empty array
      • status [object] - The status of the past, ongoing, or present competition
        • clock [float] - The current reading of the scoreboard clock (floating point value)
          • Ex: 0.0
        • displayClock [string] - A nicely formatted version of the scoreboard clock. It is of the format m:ss
          • Ex: 0:00
        • period [int] - The current period of the game
          • Ex: 2
        • type [object] - More information about the tyoe if the status
          • id [string] - The id of the type
            • Ex: 3
          • name [string] - The name of the type of status (STATUS_SCHEDULED, STATUS_FINAL, etc.)
            • Ex: STATUS_FINAL
          • state [string] - The state of the competition (pre, post, etc.)
            • Ex: post
          • completed [boolean] - Whether or not the competition has completed
            • Ex: true
          • description [string] - Description of the status (Scheduled, Final, etc.)
            • Ex: Final
          • detail [string] - Detail about when the game is scheduled for future games, or "Final" for completed games.
            • Ex: Sun, January 6th at 12:00 PM EST or Final
          • shortDetail [string] - Shortened version of detail above, or "Final" for completed game
            • Ex: 1/6 - 12:00 PM EST or Final
      • broadcasts [array] - Array of information about TV broadcasts for competition
        • market [string] - The market in which the competition is going to be/was broadcast in (national, local, etc.)
          • Ex: national
        • names [array] - Names of the TV networks for broadcasts
          • Ex: ["FOX",...]
      • groups [object] - Information about the group (conference) this team belongs to
        • id [string] - The id of the group
          • Ex: 7
        • name [string]* - The name of the group
          • Ex: Big Ten Conference
        • shortName [string] - The shortened name of the group
          • Ex: Big Ten
        • isConference [boolean] - Whether or not the group is a conference (not sure what else it would be)
          • Ex: true
      • startDate [string] - The start date of the competition in ISO date format
        • Ex: 2019-01-05T17:00Z
      • geoBroadcasts [array] - Geographical broadcasts?
        • type [object] - Type of broadcast information
          • id [string] - Id of the type of broadcast
            • Ex: 1
          • shortName [string] - Short name of type of broadcast
            • Ex: TV
        • market [object] - Information about the broadcast market
          • id [string] - Market id
            • Ex: 1
          • type [string] - Type of market
            • Ex: National
        • media [object] - Information about the broadcast media
          • shortName [string] - The short name of the media
            • Ex: FOX
        • lang [string] - The language of the broadcast
          • Ex: en
        • region [string] - The region of the broadcast
          • Ex: us
      • headlines [array] - An array containing information about headlines during the competition
        • description [string] - The full description of the headline
          • Ex: Cassius Winston scored 25 points, Nick Ward added 21 and No. 8 Michigan State extended its unbeaten streak to eight games with an 86-77 victory over No. 14 Ohio State on Saturday.
        • type [string] - The type of headline
          • Ex: Recap
        • shortLinkText [string] - A shortened version of the description
          • Ex: No. 8 Michigan State holds off No. 14 Ohio State 86-77
        • video [array] - An array containing link and metadata for video highlights
          • id [int] - The id of the video
            • Ex: 25691686
          • source [string] - The source of the video
            • Ex: espn
          • headline [string] - The headline of the video
            • Ex: Winston drains big 3 for Spartans
          • thumbnail [string] - URL for the thumbnail of the video
          • duration [int] - Duration of the video in seconds
            • Ex: 17
          • tracking [object] - Tracking metadata for the video
            • sportName [string] - Name of the sport
              • Ex: ncb
            • leagueName [string] - Name of the league
              • Ex: No League
            • coverageType [string] - The type of content the video covers
              • Ex: Final Game Highlight
            • trackingName [string] - Metadata
              • Ex: NCB_One-Play (Winston drains big 3 for Spartans) 2019/1/5 ESHEET
            • trackingId [string] - Metadata
              • Ex: dm_190105_Winston_drains_big_3_for_Spartans
          • deviceRestrictions [object] - ???
            • type [string] - ???
              • Ex: whitelist
            • devices [array] - ???
              • Ex: ["desktop","settop","handset",]
          • links [object] - This object contains more objects that themselves contain objects. Basically it's a huge nested list of objects for different types of videos. I'm not going to list them all here. Nobody probably cares about them anyways.
    • links [array] - Links to ESPN's website for various articles and scores related to the competition.
      • language [string] - The language of the content at the link
        • Ex: en
      • rel [array] - An array of strings. Not sure exactly what they're for
        • Ex: ["summary","desktop","event",...]
      • href [string] A URL for the article or other content
      • text [string] - Text describing what type of content is at the URL
        • Ex: Gamecast
      • shortText [string] - A shortened version of text
        • Ex: Gamecast
      • isExternal [boolean] - I think this indicates whether or not the content is external to ESPN. I'm not 100% sure about this though.
        • Ex: false
      • isPremium [boolean] - Whether or not you have to pay for the content
        • Ex: false
    • weather [object] - The weather for a competition in the past, or predicted weather for a competition in the future
      • displayValue [string] - The display value for the type of weather (Partly Cloudy, Sunny, etc.)
        • Ex: Cloudy
      • temperature [int] - The temperature at the time of the competition
        • Ex: 40
      • conditionId [string] - An id representing the type of weather
    • status [object] - The status of the past, ongoing, or present competition
      • clock [float] - The current reading of the scoreboard clock (floating point value)
        • Ex: 0.0
      • displayClock [string] - A nicely formatted version of the scoreboard clock. It is of the format m:ss
        • Ex: 0:00
      • period [int] - The current period of the game
        • Ex: 2
      • type [object] - More information about the tyoe if the status
        • id [string] - The id of the type
          • Ex: 3
        • name [string] - The name of the type of status (STATUS_SCHEDULED, STATUS_FINAL, etc.)
          • Ex: STATUS_FINAL
        • state [string] - The state of the competition (pre, post, etc.)
          • Ex: post
        • completed [boolean] - Whether or not the competition has completed
          • Ex: true
        • description [string] - Description of the status (Scheduled, Final, etc.)
          • Ex: Final
        • detail [string] - Detail about when the game is scheduled for future games, or "Final" for completed games.
          • Ex: Sun, January 6th at 12:00 PM EST or Final
        • shortDetail [string] - Shortened version of detail above, or "Final" for completed game
          • Ex: 1/6 - 12:00 PM EST or Final
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment