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'

And then execute:

$ bundle

You can also install the gem and use as a standalone binary:

gem install blizzard_api

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.redis_url = 'redis://localhost:6379/0'
  config.cache_access_token = true
end

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

3. Using the shipped binary

This gem ships with a binary that allows you to perform requests to the api directly from the command line. Suppoerted arguments:

3.1 Configuration

Argument Description
-a, --auth A pair of application ID and secret created on the Blizzard API dev portal. Argument must be provided as APP_ID:APP_SECRET
-c, --cache A valid Redis connection string. redis://user:password@host:port/db
-h, --help Prints this help
-j, --json Outputs the payload as JSON.
-J, --formatted-json Outputs the payload as pretty formatted JSON.
-l, --locale Locale to use when retrieving data.
-o, --output Path to an output file.
-r, --region Region to use for the API calls. Default is us
-t, --cache-access-token Cache the access token in Redis
-v, --version Prints the version

Some arguments can be loaded from environment variables:

Environment Variable Description Replaced argument
BNET_APPLICATION_ID Blizzard API application ID -a
BNET_APPLICATION_SECRET Blizzard API application secret -a
REGION Blizzard API region -r
BNET_REDIS_URL Redis connection string -c
BNET_CACHE_ACCESS_TOKEN Cache the access token in Redis -t

Note: You can also use Dotenv to load the environment variables from a .env file as long as you have Dotenv installed and the .env file is present in the same directory you are invoking the binary from.

3.2. Command line usage

You can fetch API endpoints data by using the following format:

blizzard_api <game namespace> <api endpoint> <endpoint method> [arguments]

3.3. Examples

3.3.1. Using the binary to get a list of realms

blizzard_api wow realm index

3.3.1. Using the binary to get a specific realm

Full payload:

blizzard_api wow realm get 5909

Full payload as formatted JSON:

blizzard_api -J wow realm get 5909

Full payload as formatted JSON to file:

blizzard_api -Jo realm.json wow realm get 5909

en-US only payload as formatted JSON:

blizzard_api -Jl en_US wow realm get 5909

4. 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.

4.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

5. 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.

5.1. World of Warcraft endpoints

5.2. Diablo III endpoints

5.3. Hearthstone endpoints

5.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/issues

License

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