Blizzard Api

Gem Version

This gem allow you to interface with the new blizzard api (2018) using the OAuth2 protocol for every request.

Important: This gem does not support, nor will support China endpoints.

Table of contents

  1. Installation
  2. Configuration
  3. Basic usage
  4. Available endpoints

1. Installation

Add this line to your application's Gemfile: 

gem 'blizzard_api_rb'

And then execute:

$ bundle

2. Configuration

Before you use the api you must create a developer account at https://develop.battle.net and create the client authorization keys.

Once you have a pair of client ID and SECRET you must set up an initialization code.

BlizzardApi.configure do |config|
  config.app_id = ENV['BNET_APPLICATION_ID']
  config.app_secret = ENV['BNET_APPLICATION_SECRET']
  config.region = 'us'
  config.use_cache = true
  config.redis_host = ENV['REDIS_HOST']
  config.redis_port = ENV['REDIS_PORT']
end

It is highly recommended to use redis to cache all requests as it avoids unnecessary calls and speeds up your application.

3. Basic usage

You can now consume the api by instantiating a specific endpoint:

race = BlizzardApi::Wow::Race.new :us
race_data = race.complete

or you can just use the game namespace wrapper as follows:

race = BlizzardApi::Wow.race
race_data = race.complete

Most game data endpoints will have always 3 methods available index, get and complete.

  • index is used to get a list of all resources of that endpoint.
  • get is used to get all information about a entry of the index returned data. It receives an id or slug as the first parameter, that depends on the endpoint.
  • complete is a complete information of all items listed in index. This may perform various calls to the blizzard api only use if you really need all information.

3.1 Searchable endpoints

Some endpoints support search filters. To perform a search you can use the following formats:

To use the or operator you may pass an array of values as argument to where or where_not methods.

realm = BlizzardApi::Wow.realm
realm_data = realm.search(1, 100) do |options|
  options.where 'name.en_US', %w[Azralon Nemesis]
end

To use the and operator you may call where or where_not multiple times methods.

realm = BlizzardApi::Wow.realm
realm_data = realm.search(1, 100) do |options|
  options.where 'name.en_US', 'Azralon'
  options.where 'id', 3209
end

To use the range operator you may pass a hash to where or where_not.

realm = BlizzardApi::Wow.realm
realm_data = realm.search(1, 100) do |options|
  options.where 'id', min: 3209, max: 4000, mode: :exclusive
end

Note: If you don't pass the mode key as :exclusive it will be :inclusive by default.

To sort fields you may call the order_by method multiple times:

realm = BlizzardApi::Wow.realm
realm_data = realm.search(1, 100) do |options|
  options.where 'id', min: 3209, max: 4000, mode: :exclusive
  options.order_by 'id', :desc
end

4. Available endpoints

Hint: All methods support an additional optional hash parameter that allows you to override the following configurations for a single call:

  • ttl: < int > - Cache duration (seconds) (Only works if you have redis enabled)
  • ignore_cache: true - Ignores the cache and forces an api request (Only works if you have redis enabled)
  • locale: < locale id > - Changes the default locale (if any)

World of Warcraft supports two additional options:

  • use_community_endpoint: Some methods in game data still have an odl community version available.
  • classic: Set to true to query WoW Classic data, only works for some game data endpoints.

4.1. World of Warcraft endpoints

4.2. Diablo III endpoints

4.3. Hearthstone endpoints

4.4. Starcraft II endpoints

Every endpoint requiring a region_id parameter will accepts either the integer representation of the region described in the api docs or a symbol: :US, :EU, :KO or :TW

Contributing

Bug reports and pull requests are welcome on Github at https://github.com/francis-schiavo/blizzard_api_rb/issues

License

The gem is available as open source under the terms of the MIT License.