battlerite-api v1.2.0

battlerite-api

a promise based library for accessing the battlerite api for nodejs

battlerite-api is a Node.js package wrapping the official Battlerite API, this is unopinionated-ish and returns the response data or the axios error if something went wrong. You can use the rawResponses option when creating the BattleriteAPI object to return the raw axios response instead

You can find the documentation for the Battlerite API here: http://battlerite-docs.readthedocs.io/en/latest/introduction.html

And I also recommend reading the JSON-API Specifications as well: http://jsonapi.org/

Table of Contents

• Todo
• Dependencies
• Installation
• Usage
• API
• License

Todo

• Add unit tests
• Make it work in browser

Dependencies

axios - for making promise based HTTP requests

Installation

This project uses nodejs and npm

npm install --save battlerite-api

Usage

const BattleriteAPI = require('battlerite-api');

// creates a new instance of the battlerite api
const api = new BattleriteAPI({
  apiKey: '<api_key>',
});

// gets a collection of matches
api.getMatches().then((response) => {
  // handle the reponse
}).catch((error) => {
  // handle the error
});

API

new BattleriteAPI(options)

Creates a new BattleriteAPI object with the options provided

Parameters:

• options Object options
  • apiKey String a string containing the api key from here https://developer.battlerite.com/ REQUIRED
  • defaultDatacenter String a string defines the datacenter to use, defaults to 'dc1'
  • baseURL String a string defines the baseURL, passed to axios, defaults to `https://api.${this.defaultDatacenter}.gamelockerapp.com`
  • timeout Number a number defining the maximum time in milliseconds before timing out the requests, passed to axios, defaults to 2000
  • defaultShardString a string that defines the default shard to use (http://battlerite-docs.readthedocs.io/en/master/makingrequests/makingrequests.html#regions)
  • userAgent String a string defining the user agent, defaults to 'js/battlerite-api'
  • headers Object<String, String> an object that defines the additional headers to send with requests, defaults to adding the Accept, Accept-Encoding, Authorization, and User-Agent headers

Example:

const api = new BattleriteAPI({
    apiKey: '<api_key>',
});

BattleriteAPI#getStatus()

Gets the status of the api, including version, and release of the official api http://battlerite-docs.readthedocs.io/en/master/status/status.html

Returns:

• response Object response object
  • data Object the response
    • type String the type of data, should be "status"
    • id String the id, should be "gamelocker"
    • attributes Object attributes
      • releasedAtString the date the current version was released at
      • version String the version, uses SEMVER (http://battlerite-docs.readthedocs.io/en/master/introduction.html#versioning)

Example:

api.getStatus().then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getMatches(options = {})

Gets a collection of matches http://battlerite-docs.readthedocs.io/en/master/matches/matches.html#get-a-collection-of-matches

Parameters:

• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set
  • sort String a string that defines how to sort the results, defaults to createdAt, add a minus in front of it to sort backwards
  • page Object allows for paging (http://jsonapi.org/format/#fetching-pagination)
    • offset Number a number that defines the offset for paging
    • limit Number a number that defines the limit for paging, allowed values between 1-5
  • filter Object allows for filtering
    • createdAt Object an object that defines the values for the filter createdAt
      • start String a string that defines the start, must be iso8601
      • end String a string that defines the end, must be iso8601
    • playerIds Array an array with playerIDs to filter with
    • serverType String a string that defines the server type (eg. QUICK2V2, QUICK3V3)
    • rankingType String a string that defines the ranking type

Returns:

• response Object response object
  • data Array an array with match objects
  • included Array an array with player, roster, participant, asset, and round structures
  • links Object an object that includes the link to self and next

Example:

api.getMatches({
    sort: '-createdAt',
    filter: {
        createdAt: { start: '2017-01-01T08:25:30Z', end: '2017-01-01T13:25:30Z', },
    },
}).then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getMatch(matchID, options = {})

Gets a specific match by id http://battlerite-docs.readthedocs.io/en/master/matches/matches.html#get-a-single-match Parameters:

• matchID String a string that defines the match to get by id
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Object an object with match object
  • included Array an array with player, roster, participant, asset, and round structures
  • links Object an object that includes the link to self and next

Example:

api.getMatch('<matchID>').then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getPlayersById(playerIDs, options = {})

Gets a collection of players up to 6 from an array of player ids http://battlerite-docs.readthedocs.io/en/latest/players/players.html#get-a-collection-of-players

Parameters:

• playerIDs Array[String] an array of player IDs
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • response.data Array an array with player objects
  • response.links Object contains a link to self

Example:

api.getPlayersById(['<id_1>', '<id_2>']).then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getPlayerById(playerID, options = {})

Get a specific player by id http://battlerite-docs.readthedocs.io/en/latest/players/players.html#get-a-single-player

Parameters:

• playerID String a string with a player ID
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Object a player object
  • links Object contains a link to self

Example:

api.getPlayerById('<player_id>').then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getPlayersByName(playerNames, options = {})

Gets a collection of players up to 6 from an array of player names http://battlerite-docs.readthedocs.io/en/latest/players/players.html#get-a-collection-of-players

Parameters:

• playerNames Array[String] an array of player names
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Array an array with player objects
  • links Object contains a link to self

Example:

api.getPlayersByName(['<name_1>', '<name_2>']).then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getPlayerByName(playerName, options = {})

Get a specific player by name http://battlerite-docs.readthedocs.io/en/latest/players/players.html#get-a-collection-of-players

Parameters:

• playerName String a string with a player name
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Array an array with one player object
  • links Object contains a link to self

Example:

api.getPlayerByName('<player_id>').then((data) => {
    // handle the data
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getPlayersBySteamId(steamIDs, options = {})

Gets a collection of players up to 6 from an array of steam ids http://battlerite-docs.readthedocs.io/en/latest/players/players.html#get-a-collection-of-players

Parameters:

• steamIDs Array[String] an array of steam ids
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Array an array with player objects
  • links Object contains a link to self

Example:

api.getPlayersBySteamId(['<id_1>', '<id_2>']).then((data) => {
    // handle the data
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getPlayerBySteamId(steamID, options = {})

Get a specific player by steam id http://battlerite-docs.readthedocs.io/en/latest/players/players.html#get-a-collection-of-players

Parameters:

• steamID String a string that defines the steam id
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Object a player object
  • links Object contains a link to self

Example:

api.getPlayerBySteamId('<steam_id>').then((data) => {
    // handle the data
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getTelemetry(matchID, options = {})

Get the telemetry by match id http://battlerite-docs.readthedocs.io/en/latest/telemetry/telemetry.html Uses BattleriteAPI#getMatch() and passes on the options object (uses a api request)

Parameters:

• matchID String a string that defines the match id
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set
  • url boolean a boolean that if set and set to true returns the url to the telemetry instead of the object

Returns: if options.url is true

• url String a string with the url to telemetry

else

• response Array an array of match events

BattleriteAPI#getTeamsByPlayerIds(playerIDs, season, options = {})

Gets a collection of teams by player ids http://battlerite-docs.readthedocs.io/en/master/teams/teams.html

Parameters:

• playerIDs Array an array with player ids
• season String a string that defines the season to search in
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Array an array with team objects
  • links Object contains a link to self

Example:

api.getTeamsByPlayerIds(['<id_1>', '<id_2>']).then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

BattleriteAPI#getTeamsByPlayerId(playerID, season, options = {})

Gets a collection of teams from a player id http://battlerite-docs.readthedocs.io/en/master/teams/teams.html

Parameters:

• playerID String a string that defines the player id
• season String a string that defines the season to search in
• options Object options
  • bashard String a string defining the shard to use with the request, defaults to defaultShard if not set

Returns:

• response Object response object
  • data Array an array with team objects
  • links Object contains a link to self

Example:

api.getTeamsByPlayerId('<player_id>', '6').then((response) => {
    // handle the response
}).catch((error) => {
    // handle the error
});

License

MIT @ Johan Jansson