NAV Navbar
Logo
shell java python ruby javascript go

Introduction

The first version of the Vainglory Game Data Service is an exciting step forward towards making it easier for users to have open access to in-game data.

Build something great!

At the moment this Service is in Alpha Preview mode. You can see sample data, test the interface, and provide feedback to our development team.

While we initially took a different approach, based on community feedback the Server now makes every attempt to implement the required features of the JSON-API specification. Where a deviation occurs, it is likely unintentional and can be reported to the team in our Discord.

We show example language bindings using CURL and plan to add libraries for Ruby, NodeJS, Java, Python and more. Community contributions are welcome and rewarded with good karma (and swag!) You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

We're planning to roll out Version 1.0 Q1 2017.

Versioning

We following SEMVER standards, using a MAJOR.MINOR.PATCH versioning scheme. This means that we will increment versioning in the following way:

You can see the current version and deploy date by viewing the Status endpoint.

Datacenters

We operate several Datacenters around the world. Each datacenter holds all information for one or more Regions of the game. Currently all data is located in DC01, but this may change in the future. Users will be notified prior to the change and an API endpoint will be made available to provide metadata describing where each regions data can be found.

Authorization

To specify the Headers, use this code:

  # With shell, you can just pass the correct header with each request
  curl "<endpoint-url>" \
  -H "Authorization: <api-key>"
  -H "Accept: application/vnd.api+json"
import java.io.*;
import java.net.*;

URL url = new URL("<endpoint-url>");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization","<api-key>");
conn.setRequestProperty("Accept", "application/vnd.api+json");

conn.getInputStream()
import requests

url = "<endpoint-url>"

header = {
    "Authorization": "<api-key>",
    "Accept": "application/vnd.api+json"
}

r = requests.get(url, headers=header)
import "net/http"

client := &http.Client{}
req, _ := http.NewRequest("GET","<endpoint-url>",nil)
req.Header.Set("Authorization", "<api-key>")
req.Header.Set("Accept", "application/vnd.api+json")
res, _ := client.Do(req)

We require a JSON Web Token (JWT) be sent along with your request via the Authorization header.
JWTs are passed as bearer tokens in the Authorization header, and look like the following:

Authorization: <Enter your API Key>

There's no need to create JWTs manually, they will be created for you when you register for the API - Register Here!

In some cases an X-API-KEY will give you more access to information, and in all cases it means that you are operating under a per-token rate limit.

Titles

The TitleID for a request is determined by the JWT in the Authorization header automatically and may appear in responses.

Making Requests

Content Negotiation

Clients using the api should specify that they accept responses using the application/vnd.api+json format, for convenience we will also accept application/json since it is the default for many popular client libraries.

The Server will respond with a Content-Type header that mirrors the format requested by the Client.

Regions

To specify the regions, use this code:

"...gamelockerapp.com/shards/<region>/..."
"...gamelockerapp.com/shards/<region>/..."
"...gamelockerapp.com/shards/<region>/..."
"...gamelockerapp.com/shards/<region>/..."
"...gamelockerapp.com/shards/<region>/..."
"...gamelockerapp.com/shards/<region>/..."

The Vainglory Game Data Service currently supports the following regions:

General Region Shards

To find data regarding live servers, where all data is found, please use the following shards.

Tournament Region Shards

To find data regarding professional eSport, which take place on the private client only, please use the following shards.

Choosing a specific region is currently required

GZIP

To specify the header Accept-Encoding, use this code:

-H "Accept-Encoding: gzip"
conn.setRequestProperty("Accept-Encoding","gzip");

header = {"Accept-Encoding":"gzip"}
req.Header.Set("Accept-Encoding", "gzip")

Clients can specify the header Accept-Encoding: gzip and the server will compress responses.
Responses will be returns with Content-Encoding: gzip.

Given the size of matches, this can have significant performance benefits.

Pagination

Where applicable, the server allows requests to limit the number of results returned via pagination. To paginate the primary data, supply pagination information to the query portion of the request using the limit and offset parameters.
To fetch items 2 through 10 you would specify a limit of 8 and an offset of 2:

If not specified, the server will default for matches tolimit=5 and offset=0, and for players/samples to limit=50 and offset=0

Time

Sorting

The example below will return the oldest articles first:

".../matches?sort=createdAt"
".../matches?sort=createdAt"
".../matches?sort=createdAt"
".../matches?sort=createdAt"
".../matches?sort=createdAt"
".../matches?sort=createdAt"

The example below will return the newest articles first.

".../matches?sort=-createdAt"
".../matches?sort=-createdAt"
".../matches?sort=-createdAt"
".../matches?sort=-createdAt"
".../matches?sort=-createdAt"
".../matches?sort=-createdAt"

The default sort order is always ascending. Ascending corresponds to the standard order of numbers and letters, i.e. A to Z, 0 to 9). For dates and times, ascending means that earlier values precede later ones e.g. 1/1/2000 will sort ahead of 1/1/2001.

All resource collections have a default sort order. In addition, some resources provide the ability to sort according to one or more criteria ("sort fields").

If sort fields are is prefixed with a minus, the order will be changed to descending.

JSON-P Callbacks

curl -g "https://api.dc01.gamelockerapp.com/status?callback=foo"

You can send a ?callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

Cross Origin Resource Sharing

curl -i https://api.dc01.gamelockerapp.com/status -H "Origin: http://example.com"
  HTTP/1.1 200 OK
  ...
  Access-Control-Allow-Origin: *
  Access-Control-Expose-Headers: Content-Length

This is what the CORS preflight request looks like:

curl -i https://api.dc01.gamelockerapp.com/status -H "Origin: http://example.com" -X OPTIONS
  HTTP/1.1 200 OK
  ...
  Access-Control-Allow-Headers: Origin,X-Title-Id,Authorization
  Access-Control-Allow-Methods: GET,POST,OPTIONS
  Access-Control-Allow-Origin: *
  Access-Control-Max-Age: 86400

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

Here's a sample request sent from a browser hitting http://example.com:

Receiving Responses

Payload

All Server responses contain a root JSON object.

{
  "data": {
    "type": "match",
    "id": "skarn",
    "attributes": {
      // ... this matches attributes
    },
    "relationships": {
      // ... this matches relationships
    }
  }
}
{
  "data": {
    "type": "match",
    "id": "1"
  }
}

A response will contain at least one of the following top-level members:

A response may contain any of these top-level members:

If a document does not contain a top-level data key, the included member will not be present either.

Primary data will be either:

For example, the following primary data is a single resource object:

The following primary data is a single [resource identifier object] that references the same resource:

A logical collection of resources will always be represented as an array, even if it only contains one item or is empty.

Rate Limits

The rate limit headers are defined as follows:

X-RateLimit-Limit - Request limit per day / per minute
X-RateLimit-Remaining - The number of requests left for the time window
X-RateLimit-Reset - The remaining window before the rate limit is refilled in UTC epoch nanoseconds.
* Limit tokens are incrementally filled by 60(sec)/ rate limit. ex: 60(sec)/10(rate) gets rate token every 6 seconds up to max rate limit.  

Be nice. If you're sending too many requests too quickly, we'll send back a
429 error code (server unavailable).

Matches

Matches records are created every time players complete a game session. Each Match contains high level information about the game session, including info like duration, gameMode, and more. Each Match has two Rosters.

Rosters

{
  "type": "roster",
  "id": "eca49808-d510-11e6-bf26-cec0c932ce01",
  "attributes": {
    "stats": {
      "acesEarned": 2,
      "gold": 32344,
      "etc..."
    }
  },
  "relationships": {
    "team": {
      "data": {
        "type": "team",
        "id": "753d464c-d511-11e6-bf26-cec0c932ce01"
      }
    },
    "participants": {
      "data": [
        {
          "type": "participant",
          "id": "eca49a7e-d510-11e6-bf26-cec0c932ce01"
        },
        "etc..."
      ]
    }
  }
}

Rosters track the scores of each opposing group of Participants. If players entered matchmaking as a team, the Roster will have a related Team. Rosters have many Participants objects, one for each member of the Roster. Roster objects are only meaningful within the context of a Match and are not exposed as a standalone resource.

Participants

{
  "type": "participant",
  "id": "ea77c3a7-d44e-11e6-8f77-0242ac130004",
  "attributes": {
    "actor": "*Hero009*",
    "stats": {
      "assists": 4,
      "crystalMineCaptures": 1,
      "deaths": 2,
      "farm": 49.25,
      "etc..."
    }
  }
}

Participant objects track each member in a Roster. Participants may be anonymous Players, registered Players, or bots. In the case where the Participant is a registered Player, the Participant will have a single Player relationship. Participant objects are only meaningful within the context of a Match and are not exposed as a standalone resource.

Get a collection of Matches

curl -g "https://api.dc01.gamelockerapp.com/shards/na/matches?sort=createdAt&page[limit]=3&filter[createdAt-start]=2017-02-27T13:25:30Z&filter[playerNames]=<playerName>" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"
//There are a variety of Java HTTP libraries that support query-parameters.
import requests

url = "https://api.dc01.gamelockerapp.com/shards/na/matches"

header = {
    "Authorization": "<api-key>",
    "Accept": "application/vnd.api+json"
}

query = {
    "sort": "createdAt",
    "filter[playerNames]": "<playerName>",
    "filter[createdAt-start]": "2017-02-28T13:25:30Z",
    "page[limit]": "3"
}

r = requests.get(url, headers=header, params=query)
q := req.URL.Query()
q.Add("sort", "createdAt")
q.Add("filter[playerNames]", "<playerName>")
q.Add("filter[createdAt-start]", "2017-02-27T13:25:30Z")
q.Add("page[limit]", "3")
req.URL.RawQuery = q.Encode()
res, _ := client.Do(req)

The above command returns JSON structured like this:

{
  "data": [
    {
      "type": "match",
      "id": "02b90214-c64d-11e6-9f6b-062445d3d668",
      "attributes": {
        "createdAt": "2017-01-06T20:30:08Z",
        "duration": 1482195372,
        "gameMode": "casual",
        "patchVersion": "1.0.0",
        "shardId": "na",
        "stats": "acesEarned: 3, etc..."
      },
      "relationships": {
        "rosters": {
          "data": [{
            "type": "roster",
            "id": "ea77c2eb-d44e-11e6-8f77-0242ac130004"
          }, {
            "type": "roster",
            "id": "dc2c14b4-d50c-11e6-bf26-cec0c932ce01"
          }]
        }
      }
    }
  ]
}

This endpoint retrieves data from matches. Bulk scraping matches is prohibited.

HTTP Request

GET https://api.dc01.gamelockerapp.com/shards/na/matches

Query Parameters

Parameter Default Description
page[offset] 0 Allows paging over results
page[limit] 50 The default (and current maximum) is 50. Values less than 50 and great than 2 are supported.
sort createdAt By default, Matches are sorted by creation time ascending.
filter[createdAt-start] 3hrs ago Must occur before end time. Format is iso8601 Usage: filter[createdAt-start]=2017-01-01T08:25:30Z
filter[createdAt-end] Now Queries search the last 3 hrs. Format is iso8601 i.e. filter[createdAt-end]=2017-01-01T13:25:30Z
filter[playerNames] none Filters by player name. Usage: filter[playerNames]=player1,player2,...
filter[playerIds] none Filters by player Id. Usage: filter[playerIds]=playerId,playerId,...
filter[teamNames] none Filters by team names. Team names are the same as the in game team tags. Usage: filter[teamNames]=TSM,team2,...
filter[gameMode] none filter by gameMode Usage: filter[gameMode]=casual,ranked,...

Get a single Match

curl "https://api.dc01.gamelockerapp.com/shards/na/matches/<matchID>" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"
//There are a variety of Java HTTP libraries that support URL parameters

The above command returns JSON structured like this:

{
  "data": {
    "type": "match",
    "id": "02b90214-c64d-11e6-9f6b-062445d3d668",
    "attributes": {
      "createdAt": "2017-01-06T20:30:08Z",
      "duration": 1482195372,
      "gameMode": "casual",
      "patchVersion": "1.0.0",
      "shardId": "na",
      "stats": "acesEarned: 3, etc..."
    },
    "relationships": {
      "rosters": {
        "data": [{
          "type": "roster",
          "id": "ea77c2eb-d44e-11e6-8f77-0242ac130004"
        }, {
          "type": "roster",
          "id": "dc2c14b4-d50c-11e6-bf26-cec0c932ce01"
        }]
      }
    }
  }
}

This endpoint retrieves a specific match.

HTTP Request

GET https://api.dc01.gamelockerapp.com/shards/na/matches/<ID>

URL Parameters

Parameter Description
ID The ID of the match to retrieve

Match Data Summary

Special thanks to Kashz for helping to create this! GitHub: iAm-Kashif

Match Object

Variable Type Description
type str Match
id str Match ID
createdAt str (iso8601) Time of Match Played
duration int Time of match in seconds
gameMode str Game Mode
patchVersion str Version of API
shardId str Match Shard
stats map See Match.stats
assets obj See Match.assets
rosters obj See Rosters

Match.stats (End of game statistics)

Variable Type Description
endGameReason str "Victory" or "Defeat"
queue str Game Mode

Match.assets (Telemetry Data)

Variable Type Description
type string asset
createdAt str (iso8601) Time of Telemtry creation
description str ""
filename str telemetry.json
id str ID of Asset
contentType str application/json
name str telemetry
url str Link to Telemetry.json file

Rosters Object

Variable Type Description
id str ID of Roster
type str Roster
participants obj See Participants
stats obj See Rosters.stats
team obj See Rosters.team

Rosters.stats

Variable Type
acesEarned int
gold int
heroKills int
krakenCaptures int
side Either "right/red" or "left/blue"
turretKills int
turretRemaining int

Rosters.team

Variable Type Description
id str ID of Team or None
name str Name of Team or None
type str team

Participants Object

Variable Type Description
actor str Hero
id str Same as ID of Roster
player obj See Participants.player
stats map See Participants.stats
type str participants

Participants.player

Variable Type Description
id str UID of player
name str IGN of player
stats map See Participants.player.stats
type str player

Participants.stats

Variable Type
assists int
crystalMineCaptures int
deaths int
farm int
firstAfkTime int: -1 for no AFK
goldMineCaptures int
itemGrants map of {itemsBought : int}
itemSells map of {itemsSold : int}
itemUses map of {itemsUsed : int}
items list of final build (Len: 6)
jungleKills int
karmaLevel int
kills int
krakenCaptures int
level int
minionKills int
nonJungleMinionKills int
skillTier int
skinKey str
turretCaptures int
wentAfk bool
winner bool

Participants.player.stats

Variable Type
level int
lifetimeGold float
lossStreak int
played int
played_ranked int
winStreak int
wins int
xp int

Players

Player objects contain aggregated lifetime information about each Player. At this time Players are fairly sparse, but there are plans to add much richer data as it becomes available.

Get a single Player

curl "https://api.dc01.gamelockerapp.com/shards/na/players/<ID>" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"
//There are a variety of Java HTTP libraries that support query-parameters.

The above command returns JSON structured like this:

{
"data": {
  "attributes": {
      "stats": {
          "lossStreak": 1,
          "winStreak": 0,
          "lifetimeGold": 10536.0
      },
      "name": "boombastic04"
  },
  "type": "player",
  "id": "6abb30de-7cb8-11e4-8bd3-06eb725f8a76"
}
}

This endpoint retrieves a specific player.

HTTP Request

GET https://api.dc01.gamelockerapp.com/shards/na/players/<ID>

URL Parameters

Parameter Description
ID The ID of the player to retrieve

Get a collection of players

This endpoint retrieves a collection of up to 6 players, filtered by name. Player names are specific to each region. If a player has changed names, it is possible that there are multiple ID's for a single player name.

curl "https://api.dc01.gamelockerapp.com/shards/na/players?filter[playerNames]=player1,player2" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"
//There are a variety of Java HTTP libraries that support query-parameters.

HTTP Request

GET https://api.dc01.gamelockerapp.com/shards/na/players

Query Parameters

Parameter Default Description
filter[playerNames] none Filters by player names. Usage: filter[playerNames]=player1,player2

Samples

The samples endpoint provides an easy way to access hourly batches of random match data to aggregate stats.

Get a collection of Samples

curl "https://api.dc01.gamelockerapp.com/shards/na/samples" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"
//There are a variety of Java HTTP libraries that support query-parameters.

The above command returns JSON structured like this:

{
      "type": "sample",
      "id": "sample-na-2017-02-28T07:15:30Z",
      "attributes": {
        "URL": "URL of Sample Matches",
        "createdAt": "2017-02-28T07:15:30Z",
        "shardId": "na",
        "t0": "2017-02-28T07:15:30Z",
        "t1": "2017-02-28T08:15:30Z",
        "titleId": "semc-vainglory"
      },
      "relationships": {
        "assets": {
          "data": []
        }
      }
    }

This endpoint retrieves a collection of randomly selected matches.

HTTP Request

GET https://api.dc01.gamelockerapp.com/shards/na/samples

Query Parameters

Parameter Default Description
page[offset] 0 Allows paging over results
page[limit] 50 The default (and current maximum) is 50. Values less than 50 and great than 2 are supported.
sort createdAt By default, samples are sorted by creation time ascending.
filter[createdAt-Start] none Must occur before time. Format is iso8601 Usage: filter[createdAt-end]=2017-01-01T08:25:30Z
filter[createdAt-End] none Must occur after time. Format is iso8601 Usage: filter[createdAt-end]=2017-01-01T13:25:30Z

Telemetry

The telemtry provides us insights into the match. It gives us details of various events that happened in the match alongwith the time when they happened. Some of the events also have location which can be plotted on a Vainglory Game map. Telemtry is very useful to generate a timeline visualtions of how the match went for replays, or create heatmaps of where a certin hero or ability is most useful. These are just some of the exmaples of where Telemtry can be used.

You will get telemtry data as part of the matches endpoint.

And a map of the Halcyon Fold here!

To get Telemetry data

You start by pulling a list of matches using the matches endopoint.

The HTTP Request to get matches is GET https://api.dc01.gamelockerapp.com/shards/na/matches

curl "https://api.dc01.gamelockerapp.com/shards/na/matches" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"
//There are a variety of Java HTTP libraries that support query-parameters.

The above command returns JSON structured like this:

  "data": [
    {
      "type": "match",
      "id": "f5373c40-0aa9-11e7-bcff-0667892d829e",
      "attributes": {
        "createdAt": "2017-03-17T00:38:00Z",
        "duration": 259,
        "gameMode": "blitz_pvp_ranked",
        "patchVersion": "",
        "shardId": "na",
        "stats": {
          "endGameReason": "victory",
          "queue": "blitz_pvp_ranked"
        },
        "titleId": "semc-vainglory"
      },
      "relationships": {
        "assets": {
          "data": [
            {
              "type": "asset",
              "id": "b900c179-0aaa-11e7-bb12-0242ac110005"
            }
          ]
        },
        "rosters": {
          "data": [
            {
              "type": "roster",
              "id": "b8f6640a-0aaa-11e7-bb12-0242ac110005"
            },
            {
              "type": "roster",
              "id": "b8f65271-0aaa-11e7-bb12-0242ac110005"
            }
          ]
        },
        "rounds": {
          "data": []
        }
      }
    },

You need to look for Assets JSON node which points to telemetry. Check for the following in the response:

      "relationships": {
        "assets": {
          "data": [
            {
              "type": "asset",
              "id": "b900c179-0aaa-11e7-bb12-0242ac110005"
            }
          ]
        },

Once you have located this ID, you now have to search for the following JSON segment in the response object. The following response object will provide you a link to the Telemtry data

    {
      "type": "asset",
      "id": "b900c179-0aaa-11e7-bb12-0242ac110005",
      "attributes": {
        "URL": "https://gl-prod-us-east-1.s3.amazonaws.com/assets/semc-vainglory/na/2017/03/17/00/43/b900c179-0aaa-11e7-bb12-0242ac110005-telemetry.json",
        "contentType": "application/json",
        "createdAt": "2017-03-17T00:43:22Z",
        "description": "",
        "filename": "telemetry.json",
        "name": "telemetry"
      }
    },

you can download the data with following commands. Please note that you do not need API Key to get this data.

curl "https://gl-prod-us-east-1.s3.amazonaws.com/assets/semc-vainglory/na/2017/03/17/00/43/b900c179-0aaa-11e7-bb12-0242ac110005-telemetry.json" \
  -H "Accept: application/vnd.api+json"
//There are a variety of Java HTTP libraries that support query-parameters.

this request will return you a response as follows:

   { "time": "2017-02-18T06:37:15+0000",
     "type": "DealDamage",
     "payload": {
       "Team": "Left",
       "Actor": "*Ringo*",
       "Target": "*Turret*",
       "Source": "Unknown",
       "Damage": 405,
       "Delt":  613,
       "IsHero": 1,
       "TargetIsHero": 0
     }
   }

Event Data Dictionary

Telemetry data is classified into several event of interest. Following is a list of every event type with an example.

PlayerFirstSpawn

At the start of the game when players spawn.

  {
    "time": "2017-03-17T00:38:32+0000",
    "type": "PlayerFirstSpawn",
    "payload": {
      "Team": "Right",
      "Actor": "*Alpha*"
    }
  }

Level Up

When a player gains a level in the game. In game types Brawl, you will find 9 events at the exact same time.

  {
    "time": "2017-03-17T00:38:32+0000",
    "type": "LevelUp",
    "payload": {
      "Team": "Right",
      "Actor": "*Alpha*",
      "Level": 1,
      "LifetimeGold": 0
    }
  }

BuyItem

When a player buys an item.

  {
    "time": "2017-03-17T00:38:45+0000",
    "type": "BuyItem",
    "payload": {
      "Team": "Left",
      "Actor": "*Vox*",
      "Item": "Breaking Point",
      "Cost": 2600
    }
  }

SellItem

When a player sells an item. json { "time": "2017-03-31T02:49:37+0000", "type": "SellItem", "payload": { "Team": "Left", "Actor": "*Lyra*", "Item": "Flare", "Cost": 15 } }

LearnAbility

When a player puts a point into one of the abilities. Please note there can be a time difference between when a player gains a level and learns an ability json { "time": "2017-03-17T00:38:52+0000", "type": "LearnAbility", "payload": { "Team": "Right", "Actor": "*Sayoc*", "Ability": "HERO_ABILITY_SAYOC_C", "Level": 1 } },

UseAbility

This event is recorded when a player uses an ability and it will hold information about the hero who used it together with the co-ordinates for the map. json { "time": "2017-03-17T00:39:08+0000", "type": "UseAbility", "payload": { "Team": "Right", "Actor": "*Kestrel*", "Ability": "HERO_ABILITY_KESTREL_A_NAME", "Position": [ 39.39, 0.01, 27.26 ] } },

UseItemAbility

This event is recorded when a player uses an activatable item or a charm/taunt. json { "time": "2017-03-31T03:10:17+0000", "type": "UseItemAbility", "payload": { "Team": "Left", "Actor": "*Lyra*", "Ability": "Travel Boots", "Position": [ -17.51, 0.01, 41.63 ], "TargetActor": "None", "TargetPosition": [ -17.51, 0.01, 41.63 ] } }

EarnXP

This event is recorded when a player gains XP from any source. it could be killing a minion, miner or a hero. json { "time": "2017-03-17T00:39:09+0000", "type": "EarnXP", "payload": { "Team": "Left", "Actor": "*Koshka*", "Source": "*JungleMinion_TreeEnt*", "Amount": 67, "Shared With": 1 } },

DealDamage

This event is recorded when any actor (player, turret, minion, etc.) deals damage to any other. json { "time": "2017-03-31T02:47:34+0000", "type": "DealDamage", "payload": { "Team": "Left", "Actor": "*Skaarf*", "Target": "*Vox*", "Source": "Unknown", "Damage": 105, "Delt": 80, "IsHero": 1, "TargetIsHero": 1 } }

KillActor

This event is recorded when a player kills anything in game. it could be a a minion, miner or a hero. You will generally see EarnXP and KillActor events come at the sme time.

  {
    "time": "2017-03-17T00:39:09+0000",
    "type": "KillActor",
    "payload": {
      "Team": "Left",
      "Actor": "*Koshka*",
      "Killed": "*JungleMinion_TreeEnt*",
      "KilledTeam": "Neutral",
      "Gold": "80",
      "IsHero": 1,
      "TargetIsHero": 0,
      "Position": [
        -21.95,
        0,
        24
      ]
    }
  },

NPCkillNPC

When one non-player actor kills another, such as the Kraken or a minion killing a turret. json { "time": "2017-03-31T03:07:21+0000", "type": "NPCkillNPC", "payload": { "Team": "Left", "Actor": "*Kraken_Captured*", "Killed": "*Turret*", "KilledTeam": "Right", "Gold": "300", "IsHero": 0, "TargetIsHero": 0, "Position": [ 54, 0, 2.92 ] } }

GoldFromTowerKill

When a player earns gold from the destruction of a turret belonging to the enemy team. json { "time": "2017-03-31T02:57:02+0000", "type": "GoldFromTowerKill", "payload": { "Team": "Left", "Actor": "*Idris*", "Amount": 300 } }

GoldFromGoldMine

When a player earns gold from his or her team capturing the gold miner. json { "time": "2017-03-31T03:00:43+0000", "type": "GoldFromGoldMine", "payload": { "Team": "Left", "Actor": "*Idris*", "Amount": 300 } }

GoldFromKrakenKill

When a player earns gold from his or her team killing a Kraken released by the enemy team. json { "time": "2017-03-31T03:07:43+0000", "type": "GoldFromKrakenKill", "payload": { "Team": "Right", "Actor": "*Kestrel*", "Amount": 500 } }

Download sample telemetry data here!

...

Teams (Coming Soon!)

Team objects contain aggregated lifetime information about each Team.

Get a collection of Teams

curl "https://api.dc01.gamelockerapp.com/shards/na/teams?filter[teamNames]=team1" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"

This endpoint retrieves a collection of up to 6 teams.

HTTP Request

GET https://api.dc01.gamelockerapp.com/teams

Query Parameters

Parameter Default Description
filter[teamNames] none Filters by team name. Usage: filter[teamNames]=team1
filter[teamIds] none Filter by team id. Usage: filter[teamIds]=12345

Get a single Team

curl "https://api.dc01.gamelockerapp.com/teams/<ID>" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"

The above command returns JSON structured like this:

{
  "id": 2,
  "name": "Max",
  "breed": "unknown",
  "fluffiness": 5,
  "cuteness": 10
}

This endpoint retrieves a specific team.

HTTP Request

GET https://api.dc01.gamelockerapp.com/teams/<ID>

URL Parameters

Parameter Description
ID The ID of the team to retrieve

Links (Coming Soon!)

curl "https://api.dc01.gamelockerapp.com/shards/na/link/{id}" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"

This endpoint checks to see if a link object exists for a given code.

HTTP Request

GET https://api.dc01.gamelockerapp.com/link

Query Parameters

Parameter Default Description

Post a Link

curl -XPOST "https://api.dc01.gamelockerapp.com/shards/na/link/{player_id}" \
  -H "Authorization: Bearer <api-key>" \
  -H "Accept: application/vnd.api+json"

This endpoint creates a PlayerLink object if the verification code matches the one provided by the game.

HTTP Request

POST https://api.dc01.gamelockerapp.com/link/{player_id}

Query Parameters

Parameter Default Description
code The verification code
{
  "attributes": {
      "playerId": "fb374a7b-78be-4fcc-83ed-6a532a8a6f55",
      "shardId": "na",
      "titleId": "semc-vainglory"
  },
  "id": "2454e5ac-0a69-4468-ad12-8616f066e817",
  "type": "playerLink"
}

Community SDK's

Community contributions are welcome and rewarded with good karma (and swag!) If you are currently working on an API, let us know on the Discord server and we will add a link!

Java

A Java adaptation of the Vainglory API - DominicGunn/flicker

Python

Python 3 wrapper for the Gamelocker API - schneefux/python-gamelocker

Python 3 wrapper for the Gamelocker API - ClarkThyLord/madglory-ezl

JavaScript

A JavaScript API client - seripap/vainglory

R

A project providing R6 classes (for the R language) for accessing the API - nathancarter/rvgapi

Go

A proof of concept go client for the Vainglory Developer API - madglory/vainglory-go-client

Ruby

A Ruby gem wrapper for the Vainglory Developer API - Ruby Gem | Github

Errors

The server will stop processing if a problem is encountered and return the correct HTTP error status code. Errors may additionally include error objects, which are returned as an array keyed by errors in the top level of a JSON API document.

An error objects have the following members:

The Server uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request sucks
401 Unauthorized -- Your API key is wrong
403 Forbidden -- The object requested is hidden for administrators only
404 Not Found -- The specified object could not be found
405 Method Not Allowed -- You tried to access a object with an invalid method
406 Not Acceptable -- You requested a format that isn't JSON
410 Gone -- The object requested has been removed from our servers
418 I'm a teapot
429 Too Many Requests -- You're requesting too much data! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.