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:
Connecting to the APIs requires an authentication token, which is obtained by creating an account with GameScorekeeper. Please contact us at [email protected] to create an account.
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.
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.
If fixture has been scheduled, but one or more participants are "To be determined", or TBD, the REST API will reflect this as a null value until the participants are found.
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.
The base URL for all REST API requests is https://api.gamescorekeeper.com. Each endpoints lists its path as part of the header.
Gets all supported sports.
Gets a list of LoL champions.
Gets a list of Dota2 heroes.
Gets all competitions or optionally all competition for a given sport.
When using date as string, it will automatically be converted to UTC.
Optional. No default.
When using date as string, it will automatically be converted to UTC.
Optional. No default.
name of the competition.
Possible keys are, but not limited to:
year,
season,
stage,
stage_type,
region
name, this map will be empty.
Gets a single competition by its ID.
name of the competition.
name, this map will be empty.
Gets all teams participating in the specified competition.
Gets a list of stages in the competition.
Gets a list of participants competing in the stage.
Gets a list of stage fixtures containing stage information for individual fixtures such as advancements and section name.
Gets all fixtures fitting the parameters specified.
When using date as string, it will automatically be converted to UTC.
Optional; defaults to midnight today in UTC.
When using date as string, it will automatically be converted to UTC.
Optional; defaults to midnight tomorrow in UTC.
name of the competition.
Possible keys are, but not limited to:
year,
season,
stage,
stage_type,
region
name, this map will be empty.
Gets all fixtures from the specified competition.
When using date as string, it will automatically be converted to UTC.
Optional; defaults to Jan 1 1970.
When using date as string, it will automatically be converted to UTC.
Optional; defaults to Jan 1 2100.
name of the competition.
Possible keys are, but not limited to:
year,
season,
stage,
stage_type,
region
name, this map will be empty.
Get a specific fixture by ID.
name of the competition.
Possible keys are, but not limited to:
season,
time_of_year,
year,
number,
stage,
stage_type,
region
name, this map will be empty.
Map containing which teams secured the first of each major objective.
Each of these values might be null, if the data point is unavailable.
Get the team lineups for the fixture.
For upcoming matches, these are the expected lineups. Finished fixtures will show the full verified lineup of players, including substitutions, that participated in the fixture.
Gets the map picks and bans for a given fixture.
Currently avaiable for map pick/bans for CS2 fixtures.
Gets the hero/champion picks and bans for a given fixture.
Currently avaiable for hero/champion pick/bans for LoL and Dota2 fixtures.
Get a specific attribute of metadata for a specific fixture.
Right now only streamUrl, hltvMatchUrl and gameVersion are queryable attributes, but more will be made available in the future.
404 will be returned.Get a list of stream URLs for fixture.
Gets an array of maps with detailed post match team and player stats.
All IDs used for runes, items and champions are Riot's official IDs. Detailed information on these can be acquired through Riot's Data Dragon API, documentation found here.
Gets an array of maps with detailed post match team and player stats.
All IDs used for skills, items and heroes are Valve's official IDs. Detailed information on these can be acquired through OpenDota's constants API, e.g: item information.
Gets an array of maps with round history information.
Get general info for a team with the given ID.
mixed or null if it could not be determined.mixed or null if it could not be determined.List the upcoming / future matches of a team. Returns the fixtures of the team's future matches.
Get the form of a team. Returns the results of the team's most recent matches.
Get a specific attribute of metadata for a specific team.
Right now only hltvId and hltvUrl are a queryable attributes, but more will be made available in the future.
404 will be returned.404 will be returned.Gets the average map stats for the players of a given team within a given time interval.
Get general info for player with the given ID.
Gets the average map stats for the given player ID in the given time interval.
Gets the average map stats for multiple given player IDs in the given time interval.
IDs can either be provided as individual IDs, or, as a shortcut, be the players of a given fixture.
If a fixture ID is provided, this will take precedence over any players that might be listed as well.
?id=<player1>&id=<player2>
id that might also be provided in the query string.
Connecting to the Live API should only be used in and around the time of live matches, but other use cases may arise, where one could use the events for an historic, i.e. past, match.
For validation, or testing, or odds calculation purposes, this endpoint for Historic Live Events could be used to retrieve a list of the events from a specific match.
The events will be in the same order as the Live API would have sent them, and are completely unfiltered.
{
"events":[
{
"payload": {
"fixtureId": 63039,
"timestamp": 1584751071707,
"participants": [
{
"id": "5045"
},
{
"id": "9281"
}
],
"snapshotNumber": 1746
},
"sortIndex": 9296004,
"type": "fixture_started"
},
{
"payload": {
"name": "map_started",
"mapName": "de_train",
"fixtureId": 63039,
"mapNumber": 1,
"timestamp": 1584751071714,
"participants": [
{
"id": "5045"
},
{
"id": "9281"
}
],
"snapshotNumber": 1746
},
"sortIndex": 9296005,
"type": "occurrence"
},
[..]
],
"size":387
}
Connecting to the Live API should only be used in and around the time of live matches, but other use cases may arise, where one could use the events for an historic, i.e. past, match.
For validation, or testing, or odds calculation purposes, this endpoint for Historic Live Events could be used to retrieve a list of the events from a specific match.
The events will be in the same order as the Live API would have sent them, and are completely unfiltered.
{
"events":[
{
"payload": {
"fixtureId": 63039,
"timestamp": 1584751071707,
"participants": [
{
"id": "5045"
},
{
"id": "9281"
}
],
"snapshotNumber": 1746
},
"sortIndex": 9296004,
"type": "fixture_started"
},
{
"payload": {
"name": "map_started",
"mapName": "de_train",
"fixtureId": 63039,
"mapNumber": 1,
"timestamp": 1584751071714,
"participants": [
{
"id": "5045"
},
{
"id": "9281"
}
],
"snapshotNumber": 1746
},
"sortIndex": 9296005,
"type": "occurrence"
},
[..]
],
"size":387
}
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:
wss://host/v2/live/<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.
If there are no v2live link listed in a fixture then there will be no live data available for that fixture.
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"?: <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.
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.
In order to prevent a socket from hanging, a connection will timeout after 40 seconds of inactivity.
Because games like CS2 have tactical and technical pauses/timeouts, the socket connection might experience longer inactivity than the 40 seconds.
A simple ping/pong scheme can be implemented to ensure keeping the connection alive.
Send the plain, simple string ping, without any qoutes or JSON wrapping, on the socket, and the server should respond with a message of type pong
We recommend to send a ping for every 30 seconds of inactivity.
{
"type": "pong"
}
When reconnecting to the API, you can start off with the last seen sortIndex, in order to not sieve through the entire stream of events.
Just use the seen query parameter when connecting:
wss://api.gamescorekeeper.com/v2/live/{fixtureId}/?seen={lastSeenSortIndex}
Frames with type fixture_started represent that the fixture has begun:
{
"type": "fixture_started",
"payload": {
"snapshotNumber": <integer>,
"fixtureId": <integer>,
"timestamp": <timestamp>,
"participants": [
{
"id": <integer>
},
{
"id": <integer>
}
],
}
}
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>
},
}
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. LoL fixtures consist of a number of "games" and this will be announced via game_started and game_ended occurrences that are unique for LoL. CS2 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 LoL and CS2 and the associated occurrence will be named "kill" in both games but contain different data.
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.
A fixture in CS2 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 24 rounds, which means that the actual number of rounds played can vary from game to game. Game ties are allowed at some CS2 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.
A map started occurrence is sent when a Map (game) starts. It contains the name of the map being played along with the map-number in the series.
A map ended occurrence 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.
When a map is restarted or otherwise nullified an occurrence with "map_voided" is sent. This occurrence indicates that all events between the last map_started and the map_voided were not officially part of the match.
In CS2, a map is played over a series of up to 24 rounds or more (if it goes to overtime). When a new round starts a round started event is sent as an occurrence.
When a round is concluded an occurrence with "round_ended" is sent. The round ended occurrences summarizes how many rounds each participant has won.
When a round is restarted or otherwise nullified an occurrence with "round_voided" is sent. This occurrence indicates that all events between the last round_started and the round_voided were not officially part of the match.
A half started occurrence is sent when a half has started which is at the start of a map and every time the teams switch sides (at the start of round 16 and during overtime).
A half ended occurrence is sent when a half has ended and the teams will switch sides, or the map is over.
When a half is restarted or otherwise nullified an occurrence with "half_voided" is sent. This occurrence indicates that all events between the last half_started and the half_voided were not officially part of the match.
A kill Occurrence is sent when a kill is detected.
An assist Occurrence is sent when an assist to a kill is detected.
A flash_assist Occurrence is sent when a flash assist to a kill is detected.
A suicide Occurrence is sent when a player suicide is detected.
A Bomb Planted Occurrence is sent when the bomb is planted.
A Bomb Exploded Occurrence is sent when the bomb explodes.
A snapshot of the players at that instance. The payload contains useful player information such as money and equipment, and is automaticially broadcasted at the end of a round unless otherwise specified.
Receiving "full state" event for CS2 when connecting to the Live API:
Simply adding the query parameter eventTypes along with the value cs_full_state,
like so: wss://api.gamescorekeeper.com/v2/live/{fixtureID}?eventTypes=cs_full_state
This will provide the regular events for CS2 along with the new event type "full_state", which is sent every 10 seconds. This event includes the full picture of the game at that point in time in comparison to the incremental changes of the regular events.
This query parameter only works for CS2. It has no effect on any other game, and will simply be ignored if provided.
A LoL fixture is made up of a number of games. For consistency with other live API's, a game is called a map in the occurrences
The score of a fixture is the number of games a team has won in that fixture.
The map started occurrence contains information on the side of the participants (blue/red).
A Map ended occurrence is sent when we have detected a game has ended. The winnerId refers to the ID of the participant who won the game.
A Map winner occurrence is sent when we have detected the winner of a map. The winnerId refers to the ID of the participant who won the game.
The kill occurrence is sent when a champion takedown takes place.
The tower destroyed occurrence is sent when team destroys an enemy turret.
The Inhibitor destroyed occurrence is sent when team destroys an enemy inhibitor.
The dragon slain occurrence is sent when team kills a dragon.
The Baron Slain occurrence is sent when team kills a Baron Nashor.
The full state occurrence is sent every 10 seconds during a game.
A Dota2 fixture is made up of a number of games. For consistency with other live API's, a game is called a map in the occurrences
The score of a fixture is the number of games a team has won in that fixture.
The map started occurrence contains information on the side of the participants (radiant/dire).
A Map ended occurrence is sent when we have detected a game has ended. The winnerId refers to the ID of the participant who won the game.
A Map winner occurrence is sent when we have detected the winner of a map. The winnerId refers to the ID of the participant who won the game.
The full state occurrence is sent every 5 seconds during a game.
This version of the Live API is no longer maintained, and is therefore deprecated.
Please use v2 as the primary source of live events.
It is recommended to only use this version where high-availability is needed, and as such only for backup, if v2 seems unresponsive.
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:
wss://host/v1/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.
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"?: <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.
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.
In order to prevent a socket from hanging, a connection will timeout after 40 seconds of inactivity.
Because games like CS2 have tactical and technical pauses/timeouts, the socket connection might experience longer inactivity than the 40 seconds.
A simple ping/pong scheme can be implemented to ensure keeping the connection alive.
Send the plain, simple string ping, without any qoutes or JSON wrapping, on the socket, and the server should respond with a message of type pong
We recommend to send a ping for every 30 seconds of inactivity.
{
"type": "pong"
}
When reconnecting to the API, you can start off with the last seen sortIndex, in order to not sieve through the entire stream of events.
Just use the seen query parameter when connecting:
wss://api.gamescorekeeper.com/v1/liveapi/{fixtureId}/?seen={lastSeenSortIndex}
Frames with type fixture_started represent that the fixture has begun:
{
"type": "fixture_started",
"payload": {
"snapshotNumber": <integer>,
"fixtureId": <integer>,
"timestamp": <timestamp>,
"participants": [
{
"id": <integer>
},
{
"id": <integer>
}
],
}
}
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>
},
}
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. LoL fixtures consist of a number of "games" and this will be announced via game_started and game_ended occurrences that are unique for LoL. CS2 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 LoL and CS2 and the associated occurrence will be named "kill" in both games but contain different data.
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.
A fixture in CS2 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 24 rounds, which means that the actual number of rounds played can vary from game to game. Game ties are allowed at some CS2 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.
A map started occurrence is sent when a Map (game) starts. It contains the name of the map being played along with the map-number in the series.
A map ended occurrence 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.
In CS2, a map is played over a series of up to 24 rounds or more (if it goes to overtime). When a new round starts a round started event is sent as an occurrence.
When a round is concluded an occurrence with "round_ended" is sent. The round ended occurrences summarizes how many rounds each participant has won.
When a round is restarted or otherwise nullified an occurrence with "round_voided" is sent. This occurrence indicates that all events between the last round_started and the round_voided were not officially part of the match.
A half started occurrence is sent when a half has started which is at the start of a map and every time the teams switch sides (at the start of round 16 and during overtime).
A half ended occurrence is sent when a half has ended and the teams will switch sides, or the map is over.
When a half is restarted or otherwise nullified an occurrence with "half_voided" is sent. This occurrence indicates that all events between the last half_started and the half_voided were not officially part of the match.
A kill Occurrence is sent when a kill is detected.
An assist Occurrence is sent when an assist to a kill is detected.
A flash_assist Occurrence is sent when a flash assist to a kill is detected.
A suicide Occurrence is sent when a player suicide is detected.
A Bomb Planted Occurrence is sent when the bomb is planted.
A Bomb Defused Occurrence is sent when the bomb is defused.
A Bomb Exploded Occurrence is sent when the bomb explodes.
The Image API can be used to retrieve miscellaneous logos for teams/players or pictures referenced in other endpoints.
This API is also restricted, and you need to use Authorization: Bearer <Your Token> in the header
of a request. A missing or invalid authorization header will result in a status 401.
The base URL for all Image API requests is https://img.gamescorekeeper.com.
Even though the images of this service are cached, it is urged to not reference this API directly in your application, and cache all results at your own end.
Retrieve the logo of a team by their ID
Team logos are rarely updated, so an interval of ten days is recommended as the least amount of time to cache.
We strive to have every logo in SVG, but as this is not always possible, the Content-Type header will always tell the format of a specific image.
We do not currently enforce a hard limit on the API usage, but we do encourage our users to adhere to the following limitations:
REST API: 1,000 requests per hour. If needed, we can up this limit on a per-user basis.
Live API: A single websocket connection per fixture. This can also be increase on a per-user basis.
We reserve the right to contact the user, if we monitor a large number of requests from a single user.