Battle.net API

A Node.JS library for the Battle.net Community Platform API.

battlenet-api is my attempt to provide a simple, easy-to-use interface that is up-to-date and well-documented for access to all available Battle.net Community Platform API methods. You are free to use it where and how you like as the library doesn't perform any content checking, rate limiting, or Terms of Service enforcement.

Install

Add battlenet-api to your package.json file and install with:

npm install

Or add and install it in a single step:

npm install battlenet-api --save

How to use

Step 1: require() the Battle.net API within your application:

var bnet = require('battlenet-api')();

Step 2: Call the API methods to request data:

bnet.wow.character.profile(parameters, [config,] callback);

Step 3: ???

Step 4: Profit.

Battle.net API Key

Your private Battle.net API key must be present in order to get a valid Battle.net API response. There are several ways to include it in the request:

As an optional parameter with each method

bnet.wow.character.profile(parameters, {apikey: your_api_key}, callback);

As an optional parameter with require

var bnet = require('battlenet-api')(your_api_key);

As a system environment variable

$ sudo BNET_ID=[your_api_key] node server.js

While all three ways of using the API key can be used together, the Method usage will override the Require usage which will override the Environment Variable usage. Use the most appropriate way of setting the API key that suits your needs. Please see the documentation at the Blizzard Developer Portal to obtain your own Battle.net API key.

Documentation

Each API method accepts a parameters object, an optional configuration object, and a callback function to execute once the request has completed. The available request parameters for each method are explained in the Overview.

bnet.wow.character.profile(parameters, [config,] callback);

parameters: Required. The individual per-method parameters can be found in the overview. ALL API methods will accept an origin and locale. * origin Required. This indicates which regional API endpoint to use and will match the region in which the user plays. The supported origins depends on the game you are requesting data for. * locale Optional. This localizes the returned results to the specified language. The supported locales depend on which origin is used, and when no locale is supplied the Battle.net API will default to the primary language of that region.

config: Optional. Compatible with the request module. Accepts the following configuration options: * apikey Your Battle.net API key is set here if not supplied by the Require or Environment Variable. * timeout Defaults to 10000. * gzip Defaults to true. * maxRedirects Defaults to 10. * followRedirect Defaults to true. * tunnel * proxy * proxyHeaderWhiteList * proxyHeaderExclusiveList

callback Required. The callback function accepts two arguments error and response. * error is only applicable when there's a connection issue to the API. Otherwise null. * body is the request response body parsed as JSON. If a request is successful this value can still return API errors such as 'Character not found' or 'Account forbidden'. * res is the response information such as headers and statusCode.

A fully-formed request will look something like this:

bnet.wow.character.guild({
  origin: 'us',
  realm: 'amanthul',
  name: 'charni'
}, {
  apikey: BNET_ID
}, function(err, body, res) {
  console.log(body);
});

Encoding

All API paths are passed through encodeURI() to product URL-safe values. e.g. Character names like "Légōlâs" result in "L%C3%A9g%C5%8Dl%C3%A2s". Note that WoW realm slugs should contain no special characters requiring encoding. e.g. "Aman'thul" is slugified to "amanthul". Use the Realm Status API to fetch the full realm list and their associated slugs.

Overview

User Account

• ID
• BattleTag
• World of Warcraft OAuth Profile
• Starcraft II OAuth Profile

World of Warcraft

• Achievement
• Auction
• Battle Pet
• Ability
• Species
• Stats
• Boss
• Master List
• Boss
• Challenge
• Realm Leaderboard
• Region Leaderboard
• Character
• Aggregate
• Achievements
• Appearance
• Audit
• Feed
• Guild
• Hunter Pets
• Items
• Mounts
• Pets
• Pet Slots
• Profile
• Progression
• PVP
• Quests
• Reputation
• Stats
• Statistics
• Talents
• Titles
• Data Resources
• Battlegroups
• Character Achievements
• Character Classes
• Character Races
• Guild Achievements
• Guild Perks
• Guild Rewards
• Item Classes
• Pet Types
• Talents
• Guild
• Aggregate
• Achievements
• Challenge
• Members
• News
• Profile
• Item
• Item
• Item Set
• Mount
• PVP
• Leaderboards
• Quest
• Realm Status
• Recipe
• Spell

Starcraft 2

• Data Resources
• Achievements
• Rewards
• Ladder
• Profile
• Profile
• Ladders
• Match History

Diablo 3

• Seasons
• Index
• Season
• Leaderboard
• Eras
• Index
• Era
• Leaderboard
• Data Resources
• Artisan
• Follower
• Item
• Profile
• Career
• Hero

---

User Account

The User Account API methods are available via the account object of battlenet-api.

All User Account requests take access_token as a request parameter. Access tokens are generated with OAuth 2.0 and are valid for 30 days. How you implement OAuth is up to you, although I recommend checking out Blizzard's own passport-bnet package and reading the Using OAuth article for more details.

The supported origins for the Account API are: us, eu, kr, tw, and cn.

---

User ID

Returns the authenticated user's account ID and BattleTag.

Usage

bnet.account.user({origin: 'us', access_token: users_access_token}, callback);

---

World of Warcraft OAuth Profile

Returns data for an authenticated user's World of Warcraft Profile.

Usage

bnet.account.wow({origin: 'us', access_token: users_access_token}, callback);

---

Starcraft II OAuth Profile

Returns data for an authenticated user's Starcraft III Profile.

Usage

bnet.account.sc2({origin: 'us', access_token: users_access_token}, callback);

---

World of Warcraft

The World of Warcraft API methods are available via the wow object of battlenet-api.

var wow = bnet.wow;

The supported origins and locales for the World of Warcraft API are:

Origin	Locales
us	en_US, es_MX, pt_BR
eu	en_GB, es_ES, fr_FR, ru_RU, de_DE, pl_PL, pt_PT, it_IT
kr	ko_KR
tw	zh_TW
cn	zh_CN

---

Achievement

Parameters

id the unique achievement ID.

Usage

bnet.wow.achievement({origin: 'us', id: 2144}, callback);

---

Auction

Parameters

realm the slugified realm name.

Usage

bnet.wow.auction({origin: 'us', realm: 'amanthul'}, callback);

---

Battle Pet

Abilities

Parameters

id the unique ID of the battle pet ability.

Usage

bnet.wow.battlePet.ability({origin: 'us', id: 640}, callback);

Species

Parameters

id the unique ID of the battle pet species.

Usage

bnet.wow.battlePet.species({origin: 'us', id: 258}, callback);

Stats

Parameters

id the unique ID of the battle pet species.

fields an object containing the battle pet level, breedId, and qualityId

Usage

bnet.wow.battlePet.stats({origin: 'us', id: 258, fields: { level: 25, breedId: 5, qualityId: 4 }}, callback);

---

Boss

Master List

Return the Boss master list.

Usage

bnet.wow.boss.masterList({origin: 'us'}, callback);

Boss

Returns an individual Boss specified by id.

Parameters

id The boss id.

Usage

bnet.wow.boss.boss({origin: 'us', id: 24723}, callback);

---

Challenge

Realm Leaderboard

Parameters

realm the slugified realm name.

Usage

bnet.wow.challenge.realmLeaderboard({origin: 'us', realm: 'amanthul'}, callback);

Region Leaderboard

Usage

bnet.wow.challenge.regionLeaderboard({origin: 'us'}, callback);

---

Character

All World of Warcraft character requests require the following parameters:

realm the slugified realm of the character.

name the name of the character.

Profile

Returns basic profile data about the character.

Usage

bnet.wow.character.profile({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Achievements

Returns the achievement data of the character.

Usage

bnet.wow.character.achievements({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Appearance

Returns the appearance data of the character.

Usage

bnet.wow.character.appearance({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Feed

Returns the character activity feed.

Usage

bnet.wow.character.feed({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Guild

Returns the guild data of the character.

Usage

bnet.wow.character.guild({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Hunter Pets

Returns the hunter pet data of the character (where applicable).

Usage

bnet.wow.character.hunterPets({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Items

Returns the item data of the character.

Usage

bnet.wow.character.items({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Mounts

Returns the mount data of the character.

Usage

bnet.wow.character.mounts({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Pets

Returns the pet data of the character.

Usage

bnet.wow.character.pets({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Pet Slots

Returns the pet slots data of the character.

Usage

bnet.wow.character.petSlots({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

Progression

Returns the progression data of the character.

Usage

bnet.wow.character.progression({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);

PVP

Returns the PVP data