Travis CI Code Climate Test Coverage Gem Version Inline docs MIT License


A Ruby libary wrapper for the Vainglory API

See also: YARD Documentation, Official Vainglory API Documentation

Getting Started

VaingloryAPI works with Ruby 2.0 onwards. Please refer to the YARD Documentation for a better understanding of how everything works.


You can add it to your Gemfile with:

gem 'vainglory-api'

Then run bundle install

You can also install it manually with:

gem install vainglory-api


You can create an instance of the API client by initializing with your API key and specified region (na is the default):

client ='YOUR_API_KEY', 'na')

Region Errors

A valid region short name is required when instantiating a client. Providing an invalid region short name will raise VaingloryAPI::RegionNameError.

Helper Attributes

All client methods return an OpenStruct object containing the response attributes with some additional helper attributes.

response = client.samples

response.code     # The HTTP response code
response.success? # Returns true if the response code is less than 300
response.raw      # The complete HTTP response

Rate Limits

Each request will return data about your rate limits.

response.rate_limit     # Request limit per day / per minute
response.rate_remaining # The number of requests left for the time window
response.rate_reset     # The remaining window before the rate limit is refilled in UTC epoch nanoseconds.

More information:


Currently, filters are supported by these client methods:

  • VaingloryAPI::Client#matches
  • VaingloryAPI::Client#samples

You can pass filters in as a hash using the exact Query Parameter key names outlined in the Vainglory API Documentation.

# Example matches request with filter
client.matches('filter[playerNames]' => 'boombastic04,IHaveNoIdea')


To get multiple matches:


To get single match data, you must provide the ID of a match:


You can search for data of one or more players by passing their in-game names (IGNs):

client.players('boombastic04', 'IHaveNoIdea')

To get data about a single player, you must provide the ID of the player:


To get Telemetry data, you must provide the data URL:



Bug reports and pull requests are welcome on GitHub at


MIT License. Copyright 2017 Chet Bortz