Vainglory.js
This is a Javascript API client wrapper for Vainglory. If you run into problems or find bugs, file an issue.
Installation
$ yarn add vainglory
# or npm install vainglory
To initalize the library
import Vainglory from 'vainglory';
const vainglory = new Vainglory('api-key');
Options
Base options can be modified by passing an object during initalization.
Properties
import Vainglory from 'vainglory';
const options = {
host: 'https://api.dc01.gamelockerapp.com/shards/',
region: 'na',
title: 'semc-vainglory',
};
const vainglory = new Vainglory('api-key', options);
Documentation
Reference
All methods are named references from the Official API Reference. All methods will return a promise.
Matches
Players
Tournament
Errors
You can check on the property .errors
to determine if a response has errored and the subsequent message that follows. .debug
will provide request and header information.
Example
{ errors: true,
messages: 'The specified object could not be found.',
region: 'na',
debug:
{ url: 'https://api.dc01.gamelockerapp.com/shards/na/matches?page[offset]=0&page[limit]=50&sort=createdAt&filter[createdAt-start]=2017-03-02T00:28:32.721Z&filter[createdAt-end]=2017-03-02T03:28:32.721Z&filter[playerNames]=&filter[teamNames]=',
status: 'https://api.dc01.gamelockerapp.com/status',
headers:
{ 'Content-Encoding': 'gzip',
'Content-Type': 'application/json',
'User-Agent': 'js/vainglory',
Accept: 'application/vnd.api+json',
Authorization: 'Bearer aaa.bbb.ccc',
'X-TITLE-ID': 'semc-vainglory'
}
}
},
rateLimit:
{ limit: '10',
remaining: '9',
reset: '6000000000',
requestId: 'some-arbitrary-id' }
}
Rate Limits
Rate limit information is attached to every request. All models will return .rateLimit
, see the Reference for more information or if you need to increase your rate limit.
rateLimit:
{ limit: '10',
remaining: '9',
reset: '6000000000',
requestId: 'some-arbitrary-id' }
}
Telemetry
Telemetry data can be retrieved from the match
model under assets. Assets is an array of asset.
Example
const matchId = 'f5373c40-0aa9-11e7-bcff-0667892d829e';
vainglory.matches.single(matchId).then((match) => {
console.log(match.assets)
}).catch((err) => console.error(err));
.resolve()
If you would like to resolve telemetry data, you can call .resolve()
directly on the asset. Note that this currently returns the raw data that is associated with .URL
.
const matchId = 'f5373c40-0aa9-11e7-bcff-0667892d829e';
vainglory.matches.single(matchId).then(async (match) => {
const telemetry = await match.assets[0].resolve();
console.log(telemetry);
}).catch((err) => console.error(err));
Status
vainglory.status
Returns API meta information.
vainglory.status().then((info) => console.log(info));
Example Response
{
id: 'gamelocker', // From server
releasedAt: '2017-02-24T20:44:05Z', // From server
version: 'gamelockerd-v4.0.2', // From server
clientVersion: '0.8.1' // From VaingloryJS
}
region
vainglory.region
Changes the region for the current request.
vainglory.region('sg').matches...
vainglory.matches...
vainglory.players...
setRegion
vainglory.setRegion
Sets the region for the instance.
vainglory.setRegion('sg');
vainglory.matches...
vainglory.players...
models
vainglory.models
Exposed data models. See mock data in tests to see how data should be referenced.
const match = new vainglory.models.match({data: ...match});
const matches = new vainglory.models.matches({data: ...matches});
const player = new vainglory.models.player({data: ...player});
const participant = new vainglory.models.participant({data: ...participant});
const roster = new vainglory.models.roster({data: ...roster});
Matches
vainglory.matches
.collection({...options})
Retrieves all matches. Reference
Arguments
options
[Object] - Query paramaters
const now = new Date();
const minus28days = new Date();
minus28Days.setDate(now.getDate() - 28);
const options = {
page: {
offset: 0,
limit: 50,
},
sort: 'createdAt',
filter: {
'createdAt-start': minus28days.toISOString(),
'createdAt-end': now.toISOString(),
playerNames: [],
teamNames: [],
},
};
Returns
Example
vainglory.matches.collection(options).then((matches) => {
if (matches.errors) {
return console.log(matches);
}
console.log(matches);
}).catch((errors) => {
console.log(errors);
});
.single(matchId)
Retreives a single match by ID. Reference
Arguments
matchId
[String] - The ID of match to retrieve
Returns
Example
const matchId = '0123b560-d74c-11e6-b845-0671096b3e30';
vainglory.matches.single(matchId).then((match) => {
if (match.errors) return;
console.log(match);
}).catch((errors) => {
console.log(errors);
});
Players
vainglory.players
getById(playerId)
Retreives a single player by playerId. Reference
Arguments
playerId
[String] - The ID of player to retrieve
Returns
Example
const playerId = '6abb30de-7cb8-11e4-8bd3-06eb725f8a76';
vainglory.players.getById(playerId).then((player) => {
if (player.errors) return;
console.log(player);
}).catch((errors) => {
console.log(errors);
});
getByName(playerNames)
Retreives players by playerName. Reference
Arguments
playerNames
[Array] - The name of players to retrieve. Max length of 6.
Returns
Example
const playerNames = ['famous'];
vainglory.players.getByName(playerNames).then((players) => {
if (players.errors || players.player) return;
players.player.forEach(player => {
console.log(player.id);
console.log(player.stats);
}
}).catch((errors) => {
console.log(errors);
});
Tournament
vainglory.tournament
region(region)
Tournament data is stored in seperate shards as they take place on a private client. After you call region, you can bind the same methods you would use to call matches or player data. Reference
Arguments
region
[String] - Optional - Region of which tournament data to request (na
, eu
, sa
, ea
, sg
). Note if this is blank, it will request whichever region data that was specified from setRegion
or region
Reference
Returns
Example
vainglory.tournament.region('na').matches.collection().then((matches) => {
console.log(matches);
}).catch((err) => console.log(err));
const playerNames = ['SOMEONE','SOMEONE_ELSE'];
vainglory.tournament.region('na').players.getByName(playerNames).then((players) => {
console.log(players);
}).catch((err) => console.log(err));
Models
All results are wrapped with its respective data model.
.type
- Returns the type of data requested.id
- Returns associated ID.raw
- Returns raw data from server
Remapped items vs server names
For fields in participant
such as actor
or itemGrants
, server will return *1000_Item_HalcyonPotion*
. The client will return Halcyon Potion
automatically based on field mappings. If you would like the original response, instead of calling .stats
directly, use ._stats
or ._actor
instead of .actor
.
Matches
Match
Ref
.assets
- Array of Asset.createdAt
- a string, the match timestamp, suitable for passing to JavaScript Date
constructor. Note that this is the time when the match was initiated, which is the start of the hero pick phase. To find when the first spawns on the map were, see the timestamps on individual events in the telemetry data..duration
- an integer, match duration in seconds.gameMode
- a string, such as "Casual 5v5"
(see full list here).patchVersion
- a string, which Vainglory update the match was played on, such as "3.1"
.shardId
- a string, the region from which the match was fetched, in lower case, such as "na"
.stats
- an object with these attributes:
endGameReason
- a string, such as "victory"
or "surrender"
queue
- a string, such as "5v5_pvp_ranked"
.titleId
- always the string "semc-vainglory"
.rosters
- Array of Roster
Asset
Ref
.URL
- a string, the URL of where to download the asset.contentType
- this field is not always present.createdAt
- match timestamp as a string, suitable for passing to JavaScript Date
constructor.description
- this field is not always present, and is sometimes the empty string.filename
- meaning uncertain.name
- a string, such as "telemetry"
.resolve()
- Returns promise; resolves .URL
data
Roster
Ref
.stats
- an object with these attributes:
acesEarned
- an integer, total number of aces earned by the team in the matchgold
- an integer, total gold earned by the team in the matchheroKills
- an integer, total number of hero kills earned by the team in the matchkrakenCaptures
- an integer, total number of times the team captured the Kraken in the matchside
- a string, either "left/blue"
or "right/red"
turretKills
- an integer, total number of turrets the team destroyed in the matchturretsRemaining
- an integer, total number of turrets the team had remaining on their side at match end
.participants
- Array of Participant
Participant
Ref
._actor
- original actor data before this module did cleanup on it.actor
- name of hero used by this participant, as a string (see hero name cleanup details here)._stats
- original stats data before this module did cleanup on it.stats
- cleaned up participant stats, an object with these attributes:
assists
- an integer, the number of assists the player did (the third number in KDA)crystalMineCaptures
- an integer, the number of times the player killed the crystal sentrydeaths
- an integer, number of times the player died (the second number in KDA)farm
- an integer, meaning unclear, possibly number of monsters/minions killedfirstAfkTime
- an integer, the number of seconds into the match the player first went AFK, or -1 if they never didgold
- a number (not usually an integer), total gold earned by this player throughout the matchgoldMineCaptures
- an integer, the number of times the player killed the gold mineritemGrants
- an object whose keys are the names of the items the player purchased, and whose values are the number of times the player purchased that item; example: {"Weapon Blade":2,"Six Sins":1,"Heavy Steel":1,"Sorrowblade":1,...}
itemSells
- similar in structure to the previous, but for selling itemsitemUses
- an object whose keys are the names of items the player used, and whose values are the number of times the player used the item; example: {"Travel Boots":3,"Scout Cam":3,...}
items
- array of strings, all items the player possessed at the end of the matchjungleKills
- number of kills in jungle campskarmaLevel
- a string, one of the three listed herekills
- an integer, the number of kills the player did (the first number in KDA)krakenCaptures
- an integer, the number of times the player captured the Krakenlevel
- an integer, the level of the player (in the sense of gaining experience post-match to level up your account)minionKills
- an integer, the number of minions the player killed (including jungle creeps)nonJungleMinionKills
- an integer, the number of minions the player killed (excluding jungle creeps)skillTier
- a string such as "Rock Solid - Gold"
, as provided by this lookup tableskinKey
- a string naming the skin the player used, such as "Gwen_DefaultSkin"
turretCaptures
- an integer, the number of turrets the player destroyedwentAfk
- a boolean (true or false), whether the player went AFK during the matchwinner
- a boolean (true or false), whether the player was on the winning team
.player
- Player
Players
Player
.name
- a string, the player's IGN
.shardId
- region from which the match was fetched, in lower case (e.g., "na"
)
.stats
- an object with the following attributes:
elo_earned_season_4
- deprecated; use rankPoints
instead, documented below
elo_earned_season_5
- deprecated; use rankPoints
instead, documented below
elo_earned_season_6
- deprecated; use rankPoints
instead, documented below
elo_earned_season_7
- deprecated; use rankPoints
instead, documented below
elo_earned_season_8
- deprecated; use rankPoints
instead, documented below
elo_earned_season_9
- deprecated; use rankPoints
instead, documented below
gamesPlayed
- object whose keys are various match types (aral, blitz, blitz_rounds, casual, casual_5v5, ranked, etc.) and whose values are the number of times the player has played that match type
guildTag
- a string of up to 4 characters, the player's guild tag, or the empty string if the player has no guild
karmaLevel
- an integer, one of the three listed herelevel
- an integer, the level of the player (in the sense of gaining experience post-match to level up your account)lifetimeGold
- meaning unclearlossStreak
- number of matches the player has lost in a row, or 0 if the last match was a win (but sometimes this number and winStreak
are both zero, impossibly)played
- meaning unclearplayed_aral
- deprecated; use gamesPlayed
instead, documented aboveplayed_blitz
- deprecated; use gamesPlayed
instead, documented aboveplayed_casual
- deprecated; use gamesPlayed
instead, documented aboveplayed_ranked
- deprecated; use gamesPlayed
instead, documented aboverankPoints
- an object whose keys are "blitz"
and "ranked"
and whose values are the player's precise numerical ranks in each of those match types (5v5 rank values not yet supplied)skillTier
- an integer, which can be decoded by this lookup tablewinStreak
- number of matches the player has lost in a row, or 0 if the last match was a win (but sometimes this number and lossStreak
are both zero, impossibly)wins
- an integer, number of games wonxp
- an integer, number of experience points earned (in post-match rewards, for leveling the player's account)
.titleId
- always the string "semc-vainglory"
.skillTier
- an object containing both serverName
and name
properties, from the list in this lookup table.karmaLevel
- an object containing both serverName
and name
properties, from the list in this lookup table.createdAt
- meaning unclear; this attribute is not always present