GameScorekeeper

Overview

Welcome to the GameScorekeeper API documentation

This document is intended as a guide and look-up reference for developers creating apps and sites powered by the GameScorekeeper APIs.

The GameScorekeeper APIs provide data from Esports matches. There are currently two APIs available that a user or app can connect to in order to retrieve data:

  • REST API: The REST API provides access to all data on past and future fixtures, for example final results of matches already played and start times of scheduled matches.
  • Live Data API: The live API makes it possible to establish live WebSocket connections with the GameScorekeeper data platform to retrieve real-time results and stats from fixtures currently being played.

Connecting to the APIs requires an authentication token, which is obtained by creating an account with GameScorekeeper. Please contact us at sales@gamescorekeeper.com to create an account.

Terminology

Timestamps

All timestamps are Unix-timestamps in milliseconds.

Sport

A sport is an Esport, ie. a video game, supported by the GameScorekeeper data platform.

Examples

  • Counter-Strike: Global Offensive
  • Heroes of the Storm
  • Dota 2
  • League of Legends

Competition

A competition is a group of fixtures. Competitions includes both tournaments, where matches are usually played at the same venue over a short time span, and leagues, where matches can be played over a longer time span in a range of geographical locations.

Examples

  • Blast Pro Series 2017
  • HGC Spring 2018
  • The International 2017
  • 2018 NA LCS Spring Split

Fixture

A fixture, also known as a match, represents a series of one or more games played between two or more participants.

A fixture is part of a competition.

Each fixture has a scheduled start time. This is the planned start time for the fixture according to the fixture organiser. Actual start time may differ from the scheduled start time.

Examples

  • Astralis vs North in Blast Pro Series 2017
  • Fnatic vs Misfits in HGC Spring 2018
  • Team Liquid vs Invictus Gaming in The International 2017
  • Cloud9 vs Counter Logic Gaming in 2018 NA LCS Spring Split

Participant

A participant represents a team, player or other entity participating in a fixture. Though participants are most commonly esports teams, some sports and events feature 1v1 matches and national, regional or all-star teams.

Participants may have individual handicaps in any given fixture.

Examples

  • Team Liquid
  • Life
  • Brazil
  • All-Stars West

REST API

The REST API is used to retrieve upcoming and completed fixtures. Use Authorization : Bearer <Your Token> in the header of a request. A missing or invalid authorization header will result in a status 401.

Get Fixture

Get a specific fixture by ID.

Parameters

Path Parameters

fixtureId
The fixture ID.
long

Responses

Response Schema

id
The fixture ID.
integer
tie
Whether this fixture ended as a tie. Optional.
boolean
winnerId
ID of the winning participant. Optional.
integer
status
Valid values: Scheduled, Started, Ended
string
format
name
The name of the format
string
FormatDTO
competition
id
The id of the competition
integer
name
The name of the competition
string
CompetitionDTO
comment
An optional comment.
string
scheduledStartTime
Timestamp for when this fixture is scheduled to start. As milliseconds since Unix Epoch.
timestamp
startTime
Timestamp for when this fixture actually started.
timestamp
endTime
Timestamp for when this fixture ended.
timestamp
sport
alias
The id of the sport
integer
name
The name of the sport
string
SportSummaryDTO
participants
id
The id of the participant.
integer
name
The name of the participant.
string
score
Current score for this participant in the fixture - including handicap.
integer
scoreWithoutHandicap
Current score for this participant in the fixture - not including handicap.
integer
handicap
The handicap of the participant in this specific fixture. Is added to scoreWithoutHandicap to determine final score.
integer
Array of ParticipantDTO
links
rel
The link relation. Allowed values: liveapi
integer
link
A URI pointing to the relation.
uri
Array of LinkDTO

Example /fixtures/2

    List Fixtures

    Gets all fixtures fitting the parameters specified.

    Parameters

    Query Parameters

    sport
    The sport to filter on (the alias).
    string
    competitionId
    The competition id to filter on.
    string
    from
    The date to query from.
    DateParamStartOfDay
    to
    The date to query to.
    DateParamEndOfDay
    page
    The page to list (default 1).
    integer
    pageCount
    Amount of results per page.
    integer

    Responses

    Response Schema

    fixtures
    A list of fixtures matching the search criteria.
    id
    The id of the fixture.
    integer
    tie
    Whether this fixture ended as a tie. Optional.
    boolean
    winnerId
    ID of the winning participant. Optional.
    integer
    status
    Valid values: Scheduled, Started, Ended
    string
    format
    name
    Name of the format
    string
    competition
    CompetitionSummaryDTO
    id
    ID of the competition.
    integer
    name
    Name of the competition.
    string
    comment
    An optional comment.
    string
    scheduledStartTime
    Timestamp for when this fixture is scheduled to start.
    timestamp
    startTime
    Timestamp for when this fixture actually started.
    timestamp
    endTime
    Timestamp for when this fixture ended.
    timestamp
    sport
    SportSummaryDTO
    alias
    Alias uniquely identifying the sport.
    integer
    name
    Name of the sport.
    string
    participants
    id
    The id of the participant.
    integer
    name
    The name of the participant.
    string
    score
    Current score for this participant in the fixture - including handicap.
    integer
    scoreWithoutHandicap
    Current score for this participant in the fixture - not including handicap.
    integer
    handicap
    The handicap of the participant in this specific fixture. Is added to scoreWithoutHandicap to determine final score.
    integer
    Array of ParticipantDTO
    links
    rel
    The link relation. Allowed values: liveapi
    integer
    link
    A URI pointing to the relation.
    uri
    Array of LinkDTO
    Array of FixtureDTO
    totalCount
    The total count of fixtures matching the query
    integer

    Example /fixtures?page=1&pageCount=2

      List Sports

      Gets all supported sports.

      Responses

      Response Schema

      sports
      SportDTO
      name
      Name of the sport.
      string
      alias
      Alias of the sport.
      string

      Example /sports

        List Competitions

        Gets all competitions or optinally all competition for a given sport.

        Query Parameters

        sport
        string
        The sport alias to filter on.

        Responses

        Response Schema

        competitions
        Array of CompetitionDTO
        id
        ID of the competition.
        integer
        name
        Name of the competition.
        string
        sportAlias
        Alias of the sport this competition is held for.

        Example /competitions?sport=HotS

          Live Data API

          The Live Data API uses WebSockets to push live data to clients. Each connection to the API can deliver data for one specific fixture.

          URIs for Live Data WebSockets are based on fixture IDs as such:

              ws://host:8000/liveapi/<fixtureId>
                                  

          When connecting to the WebSocket, after having authenticated, all events from the start of the fixture are sent. This means that connecting late will not result in a loss of information, only its delay.

          Protocol

          The protocol of the Live Data API is simple. Data is sent in “messages” with the following structure:

              {
                  "type": "<the type of message being sent>",
                  "payload"?: <json object>
              }

          The types are explained below along with a description of the specific payloads.

          The time in timestamp is when the message was originally generated. This means that the timestamp of a specific message will be the same regardless of when you connect to the WebSocket.

          Authentication

          When connecting to a Live Data WebSocket you will receive an authentication message like this:

              {
                  "type": "auth"
              }

          And to authenticate you must respond with your token like this:

              {
                  "token": "<your bearer token>"
              }

          The bearer token to use is the same as when connecting to the REST API.

          Once authenticated you will begin receiving messages representing game data for the specified fixture once it starts. No data is received for an unstarted fixture.

          Example

          • {
          • "type": "auth"
          • }

          Fixture Started

          Frames with type fixture_started represent that the fixture has begun:

              {
                  "type": "fixture_started",
                  "payload": {
                      "snapshotNumber": <integer>,
                      "fixtureId": <integer>,
                      "timestamp": <timestamp>
                  }
              }
              

          Example

            Property Changed

            Frames with type property_changed represent that one or more in-game properties have changed. Which properties depend entirely on the game, and can be anything from number of kills, team level or amount of gold to whether or not a tower has been taken over or if a (de)buff is applied. The format is as follows:

                {
                    "type": "property_changed",
                    "payload": {
                        "changes": {
                            <partial game-specific object>
                        }
                        "snapshotNumber": <integer>,
                        "fixtureId": <integer>,
                        "timestamp": <timestamp>
                    }
                }
            

            Example (teams switching side in CS:GO)

              Score Changed

              Frames with type score_changed indicate that the overall score for the fixture has changed. While the specific meaning of the score is game specific the format is the same:

                  {
                      "type": "score_changed",
                      "payload": {
                          "scores": [
                              {
                                  "participantId": <id>,
                                  "score": <integer>
                              }
                          ],
                          "snapshotNumber": <integer>
                      },
                      "timestamp": <timestamp>
                  }
                                  

              Example

                Occurrence

                Frames with type occurrence represent that some discreet in-game event occurred. This might be one player killing another or the destruction of a tower. The game-specific progression of fixtures will also be announced via occurrences.

                E.g. HotS fixtures consist of a number of "games" and this will be announced via game_started and game_ended occurrences that are unique for HotS. CS:GO fixtures, on the other hand, consist of a number of "maps" themselves consisting of a number of "rounds", which again is announced via map_started/ended and round_started/ended occurrences.

                The data for these specific occurrences is described in detail in the sections relating to the specific games supported.

                Overall the structure of an occurrence message is as such:

                    {
                        "type": "occurrence",
                        "payload": {
                            "name": "<name of occurrence, e.g. game_started>",
                            "timestamp": <timestamp>,
                            "fixtureId": <integer>,
                            <occurrence specific properties>,
                            "snapshotNumber": <integer>
                        },
                    }
                

                Note that occurrences with the same name may occur in different games. E.g. players kill each other in both HotS and CS:GO and the associated occurrence will be named "kill" in both games but contain different data.

                Example (bomb exploded in CS:GO)

                  Fixture Ended

                  Once the entire fixture has been played the fixture_ended message is sent containing the final score and the winner (or indication of being tied).

                      {
                          "type": "fixture_ended",
                          "payload": {
                              "timestamp": <timestamp>,
                              "fixtureId": <integer>
                              "winnerId"?: <id>,
                              "scores": [
                                  {
                                      "participantId": <id>,
                                      "score": <score as integer>
                                  },
                                  {
                                      "participantId": <id>,
                                      "score": <score as integer>
                                  }
                              ],
                              "isTie": <boolean>,
                              "snapshotNumber": <integer>
                          }
                      }
                                      

                  The property winnerId can be null if the fixture ended in a tie.

                  Example

                    Counter-Strike Global Offensive (CS:GO) Live Data API

                    A fixture in CS:GO is made up of one or more games. Each game is played on a specific map and consists of a number of rounds. Games are usually played as best of 30 rounds, which means that the actual number of rounds played can vary from game to game. Game ties are allowed at some CS:GO events, while other events add additional rounds in case of a tie.

                    The score of a fixture is the number of games a team has won in that fixture.

                    Map Started

                    A map started event is sent when a Map (game) starts. It contains the name of the map being played along with the map-number in the series.

                    Example

                      Map Ended

                      A map ended event is sent when a Map (game) has been decided. Either because a winner has been found, or in tournaments that allows ties, because the map was tied.

                      Properties

                      winnerId
                      The participantId of the team who won the map. May be null.
                      integer
                      isTie
                      True if the map ended as a tie.
                      boolean

                      Example

                        Round Started

                        In CS:GO, a map is played over a series of 30 rounds. When a new round starts a round started event is sent as an occurrence.

                        Example

                          Round Ended

                          When a round is concluded an occurrence with "round_ended" is sent. The round ended occurrences summarizes how many rounds each participant has won.

                          Example

                            Kill Occurrence

                            A kill Occurrence is sent when a kill is detected.

                            Properties

                            name
                            The name of the occurrence: "kill"
                            string
                            killerId
                            The GameScorekeeper ID of the player who performed the kill.
                            integer
                            killerSide
                            The side the killer plays for. "CT" or "TERRORIST".
                            string
                            victimId
                            The GameScorekeeper ID of the player who was killed.
                            integer
                            victimSide
                            The side the victim plays for. "CT" or "TERRORIST".
                            string
                            weapon
                            The weapon used to perform the kill.
                            string
                            headshot
                            Whether the kill was a headshot or not.
                            boolean
                            timestamp
                            The actual time the kill occurred.
                            timestamp

                            Example

                              Bomb Planted Occurrence

                              A Bomb Planted Occurrence is sent when the bomb is planted.

                              Properties

                              name
                              The name of the occurrence: "bomb_planted"
                              string
                              planterId
                              The GameScorekeeper ID of the player who planted the bomb.
                              integer
                              timestamp
                              The actual time the bomb was planted.
                              timestamp

                              Example

                                Bomb Defused Occurrence

                                A Bomb Defused Occurrence is sent when the bomb is planted.

                                Properties

                                name
                                The name of the occurrence: "bomb_defused"
                                string
                                defuserId
                                The GameScorekeeper ID of the player who defused the bomb.
                                integer
                                timestamp
                                The actual time the bomb was defused.
                                timestamp

                                Example

                                  Bomb Exploded Occurrence

                                  A Bomb Exploded Occurrence is sent when the bomb explodes.

                                  Properties

                                  name
                                  The name of the occurrence: "bomb_exploded"
                                  string
                                  timestamp
                                  The actual time the bomb was planted.
                                  timestamp

                                  Example

                                    Property Changed

                                    Participant properties

                                    Participant specific properties are identified by a prefix in the path: "participants.<id>.<property>". Here <id> is the participant ID as used elsewhere and property is the specific property as explained below.

                                    Properties

                                    side
                                    The side of the team. Can be CT or Terrorist. The side changes at half-time and during overtime.
                                    string

                                    Example

                                      Heroes of the Storm (HotS) Live Data API

                                      A Heroes of the Storm fixture is made up of a number of games. Each game is played on a specific map (also known as a battleground).

                                      The score of a fixture is the number of games a team has won in that fixture.

                                      Game Started

                                      The game started occurrence contains information on the battleground (map) and side and color of the participants.

                                      Payload

                                      name
                                      string
                                      game_started
                                      timestamp
                                      timestamp
                                      The time the game started.
                                      fixtureId
                                      integer
                                      Id for the fixture.
                                      snapshotNumber
                                      integer
                                      gameNumber
                                      integer
                                      1st game in a series is gameNumber 1, second is 2 etc.
                                      mapName
                                      string
                                      The name of the map this game is played on.
                                      participants
                                      Array of participants
                                      id
                                      Id of the participant.
                                      integer
                                      side
                                      Side of the participant. left or right.
                                      string
                                      color
                                      Color of the participant.
                                      string

                                      Example

                                        Property Changed

                                        Properties for Heroes of the Storm are grouped into "Global Properties" and "Participant Properties". Participant properties are properties that are tied to a specific participant, such as level, while Global Properties are not, such as gameTime.

                                        Global properties

                                        Some properties are general and have no special path prefix.

                                        Properties

                                        gameTime
                                        The in-game time in seconds. It is the time as reported by the game, not the amount of wall clock time elapsed since the fixture started. Game time may be negative.
                                        integer

                                        Participant properties

                                        Changes to participants are reflected in the participants array. While the id never changes it is included in the participant object to identify which participant the changes apply for.

                                        Properties

                                        id
                                        Identifier for the participant. This property does not change, but is always included.
                                        integer
                                        level
                                        The current level of the team. 1.4 means that the team is level 1 and 40% of the way to level 2.
                                        float
                                        kills
                                        The amount of kills the team has
                                        integer
                                        core
                                        currentHealth
                                        Current health of the core. Percentage can be calculated by taken currentHealth / maxHealth
                                        integer
                                        maxHealth
                                        Maximum health of the core
                                        integer
                                        currentShield
                                        A number representing the amount of shield on the core
                                        float
                                        maxShield
                                        The maximum value possible for core shield.
                                        float
                                        towers
                                        current
                                        The amount of towers the team currently has
                                        integer
                                        start
                                        The amount of towers the team starts with.
                                        integer

                                        Example

                                          Game Ended Occurrence

                                          A game ended occurrence is sent when a winner is detected in a game. The winnerId refers to the ID of the participant who won the game.

                                          Example

                                            Dota2 Live Data API

                                            A Dota2 fixture is made up of a number of games.

                                            The score of a fixture is the number of games a team has won in that fixture.

                                            Game Started

                                            The game started occurrence contains information on the side of the participants (radiant/dire).

                                            Participant

                                            id
                                            integer
                                            The id of the participant.
                                            side
                                            string
                                            The side of the participant. Can be dire or radiant.

                                            Example

                                              Property Changed

                                              Currently we don't send property changed messages for Dota2.

                                              Game Ended Occurrence

                                              A game ended occurrence is sent when a winner is detected in a game. The winnerId refers to the ID of the participant who won the game.

                                              Example

                                              League of Legends Live Data API

                                              A LoL fixture is made up of a number of games.

                                              The score of a fixture is the number of games a team has won in that fixture.

                                              Game Started

                                              The game started occurrence contains information on the side of the participants (blue/red).

                                              Participant

                                              id
                                              integer
                                              The id of the participant.
                                              side
                                              string
                                              The side of the participant. Can be blue or red.

                                              Example

                                                Property Changed

                                                Properties for League of Legends are grouped into "Global Properties" and "Participant Properties". Participant properties are properties that are tied to a specific participant, such as level, while Global Properties are not, such as gameTime.

                                                Global properties

                                                Some properties are general and have no special path prefix.

                                                Properties

                                                gameTime
                                                The in-game time in milliseconds. It is the time as reported by the game, not the amount of wall clock time elapsed since the fixture started.
                                                integer

                                                Participant properties

                                                Changes to participants are reflected in the participants object where each key is the id of a participant which had changes to their properties

                                                Properties

                                                baronsKilled
                                                Number of barons the team has killed
                                                integer
                                                dragonsKilled
                                                Number of dragons the team has killed
                                                integer
                                                inhibitorsKilled
                                                Number of inhibitors the team has destroyed
                                                integer
                                                towersKilled
                                                Number of towers the team has destroyed
                                                integer
                                                color
                                                The color of the team
                                                string
                                                firstBlood
                                                Whether or not the team has gotten first blood
                                                boolean
                                                playerStats
                                                JSON
                                                player1
                                                Properties specific to the participant's top laner (see PlayerStats below)
                                                PlayerStats
                                                player2
                                                Properties specific to the participant's jungler (see PlayerStats below)
                                                PlayerStats
                                                player3
                                                Properties specific to the participant's mid laner (see PlayerStats below)
                                                PlayerStats
                                                player4
                                                Properties specific to the participant's ADC (see PlayerStats below)
                                                PlayerStats
                                                player5
                                                Properties specific to the participant's support (see PlayerStats below)
                                                PlayerStats

                                                PlayerStats Property

                                                summonerName
                                                In-game name (including team alias) of the player.
                                                string
                                                championName
                                                Slug name of the champion the player is playing.
                                                string
                                                championId
                                                Riot ID of the champion.
                                                integer
                                                level
                                                Player level.
                                                integer
                                                kills
                                                Number of kills.
                                                integer
                                                assists
                                                Number of assists.
                                                integer
                                                deaths
                                                Number of deaths.
                                                integer
                                                creepScore
                                                Creep Score (Also known as 'CS'). The number of minions and monsters killed
                                                integer
                                                currentGold
                                                Current gold available to spend.
                                                integer
                                                totalGold
                                                Total gold earned so far in the game.
                                                integer
                                                health
                                                Current health.
                                                integer
                                                maxHealth
                                                Maximum health.
                                                integer
                                                power
                                                Current power (Mana/energy/rage etc.)
                                                integer
                                                maxPower
                                                Maximum power (Mana/energy/rage etc.)
                                                integer
                                                attackDamage
                                                Attack damage. The amount of base damage (before mitigation/multipliers) that the player does with auto attacks.
                                                integer
                                                abilityPower
                                                Ability power. Amplifies the damage of some player abilities.
                                                integer
                                                armor
                                                Armor. Mitigates physical damage received.
                                                integer
                                                magicResist
                                                Magic resist. Mitigates magical damage received.
                                                integer
                                                attackSpeed
                                                Attack speed. Increases rate of auto attacks.
                                                integer
                                                movementSpeed
                                                Movement speed. The amount of in-game units (distance) the player can move per second.
                                                integer
                                                armorPen
                                                Armor penetration. The amount of flat armor the player ignores on enemies when doing physical damage.
                                                integer
                                                magicPen
                                                Magic penetration. The amount of flat magic resist the player ignores on enemies when doing magical damage.
                                                integer
                                                armorPenPercent
                                                Armor penetration percentage. The percentage of armor the player ignores on enemies when doing physical damage.
                                                integer
                                                magicPenPercent
                                                Magic penetration percentage. The percentage of magic resist the player ignores on enemies when doing magical damage.
                                                integer
                                                spellVamp
                                                Spell vamp. Percentage of damage caused by abilities and active that is healed as health.
                                                integer
                                                lifesteal
                                                Life steal. Percentage of damage caused by auto attacks is healed as health.
                                                integer
                                                tenacity
                                                Tenacity (Crowd-control reduction). Reduces the duration of crowd control effects (Stun, slow, root etc.) by this percentage.
                                                integer
                                                healthRegen
                                                Health regeneration (also known as HP10). The amount of health naturally restored over 10 seconds
                                                integer
                                                powerRegen
                                                Power regeneration (also known as MP10). The amount of power naturally restored over 10 seconds
                                                integer
                                                xp
                                                Total amount of xp accrued in the game
                                                integer
                                                wardsPlaced
                                                Amount of wards placed in the game.
                                                integer
                                                wardsKilled
                                                Amount of wards destroyed in the game.
                                                integer
                                                summonersSpell1
                                                ID of the player's first summoner spell.
                                                integer
                                                summonersSpell2
                                                ID of the player's second summoner spell.
                                                integer
                                                x
                                                X-coordinate of the player's position on the map (0 o 14820)
                                                integer
                                                y
                                                Y-coordinate of the player's position on the map (0 o 14820)
                                                integer
                                                totalDmg
                                                Total damage dealt to champions, minions and monsters.
                                                integer
                                                magicDmg
                                                Total magical damage dealt to champions, minions and monsters.
                                                integer
                                                physicalDmg
                                                Total physical damage dealt to champions, minions and monsters.
                                                integer
                                                trueDmg
                                                Total true damage dealt to champions, minions and monsters.
                                                integer
                                                totalChampionDmg
                                                Total damage dealt to champions
                                                integer
                                                magicChampionDmg
                                                Total magical damage dealt to champions
                                                integer
                                                physicalChampionDmg
                                                Total physical damage dealt to champions
                                                integer
                                                trueChampionDmg
                                                Total true damage dealt to champions
                                                integer
                                                items
                                                List of IDs of items the player possesses
                                                array
                                                skills
                                                Json object where the keys represent the level the player selected a skill, and the value denotes which skill was leveled up (1: Q, 2: W, 3: E, 4: R)
                                                json
                                                doubleKills
                                                Number of double-kills the player has done
                                                integer
                                                tripleKills
                                                Number of triple-kills the player has done
                                                integer
                                                quadraKills
                                                Number of quadra-kills the player has done
                                                integer
                                                pentaKills
                                                Number of penta-kills the player has done
                                                integer

                                                Example

                                                  Game Ended Occurrence

                                                  A game ended occurrence is sent when a winner is detected in a game. The winnerId refers to the ID of the participant who won the game.

                                                  Example