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
.duration
.gameMode
.patchVersion
.shardId
.stats
.titleId
.rosters
- Array of Roster
Asset
Ref
.URL
.contentType
.createdAt
.description
.filename
.name
.resolve()
- Returns promise; resolves .URL
data
Roster
Ref
Participant
Ref
._actor
.actor
._stats
.stats
.player
- Player
Players
Player
.name
.shardId
.stats
.titleId
.skillTier
.karmaLevel
.createdAt