Battle.net API

battlenet-api is now deprecated and no longer maintained. A ground-up rewrite is available at blizzard.js featuring a major version number, a cleaner API, promises support, a test suite, richer documentation, and an example app.

Please migrate to blizzard.js as any issues will be redirected.

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 of the character.

Usage

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

Quests

Returns the quest data of the character.

Usage

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

Reputation

Returns the reputation data of the character.

Usage

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

Stats

Returns the character sheet stats of the character like Strength and Agility. Note the difference between the stats and statistics methods.

Usage

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

Statistics

Returns the gameplay statistics of the character like 'Used X bandages' etc. Note the difference between the stats and statistics methods.

Usage

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

Talents

Returns the talent data of the character.

Usage

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

Titles

Returns the title data of the character.

Usage

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

Audit

Returns an audit of the character's equipment.

Usage

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

Aggregate

Returns the specified character fields aggregated in a single request.

Parameters

fields an array of one or more character fields.

Usage

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

Data Resources

Battlegroups

Usage

bnet.wow.data.battlegroups({origin: 'us'}, callback);

Character Achievements

Usage

bnet.wow.data.characterAchievements({origin: 'us'}, callback);

Character Classes

Usage

bnet.wow.data.characterClasses({origin: 'us'}, callback);

Character Races

Usage

bnet.wow.data.characterRaces({origin: 'us'}, callback);

Guild Achievements

Usage

bnet.wow.data.guildAchievements({origin: 'us'}, callback);

Guild Perks

Usage

bnet.wow.data.guildPerks({origin: 'us'}, callback);

Guild Rewards

Usage

bnet.wow.data.guildRewards({origin: 'us'}, callback);

Item Classes

Usage

bnet.wow.data.itemClasses({origin: 'us'}, callback);

Pet Types

Usage

bnet.wow.data.petTypes({origin: 'us'}, callback);

Talents

Usage

bnet.wow.data.talents({origin: 'us'}, callback);

Item

Item

Returns the item data of the specified item ID.

Parameters

id the unique item ID.

context optional the context used to select a specific version of an item.

bonusList optional an array of bonus list of IDs applied to the item.

Usage

bnet.wow.item.item({origin: 'us', id: 18803}, callback);

Item Set

Returns the item set data of the specified set ID.

Parameters

id the unique item set ID.

Usage

bnet.wow.item.set({origin: 'us', id: 1060}, callback);

Mount

Returns the Mount master list.

Usage

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

Guild

All World of Warcraft guild requests require the following parameters:

realm the slugified realm of the guild.

name the name of the guild.

Aggregate

Returns the specified guild fields aggregated in a single request.

Parameters

fields an array of one or more guild fields.

Usage

bnet.wow.guild.aggregate({origin: 'us', realm: 'amanthul', name: 'blackwolf', fields: ['members', 'achievements']}, callback);

Achievements

Returns the achievement data of the guild.

Usage

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

Challenge

Returns the challenge data of the guild.

Usage

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

Members

Returns the members data of the guild.

Usage

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

News

Returns the news data of the guild.

Usage

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

Profile

Returns basic profile data of the guild.

Usage

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

PVP

Leaderboards

Parameters

bracket [2v2, 3v3, 5v5, rbg]

Usage

bnet.wow.pvp.leaderboards({origin: 'us', bracket: '2v2'}, callback);

Quest

Parameters

id the unique quest ID.

Usage

bnet.wow.quest({origin: 'us', id: 13146}, callback);

Realm Status

Parameters

realms [optional] an array of one or more realms to limit.

Usage

All realms

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

Selected realms

bnet.wow.realmStatus({origin: 'us', realms: ['proudmoore', 'blackrock']}, callback);

Recipe

Parameters

id the unique recipe ID.

Usage

bnet.wow.recipe({origin: 'us', id: 33994}, callback);

Spell

Parameters

id the unique spell ID.

Usage

bnet.wow.spell({origin: 'us', id: 8056}, callback);

Starcraft 2

The Starcraft 2 API methods are available via the sc2 object of battlenet-api.

var sc2 = bnet.sc2;

The supported origins and locales for the Starcraft 2 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 sea | en_US kr | ko_KR tw | zh_TW cn | zh_CN

Profile

All Starcraft 2 profile requests require the following parameters.

id the unique player ID.

region the player's region ID.

name the player's profile name.

Profile

Returns basic profile data for the specified player.

Usage

bnet.sc2.profile.profile({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);

Ladders

Returns ladder data for the specified player.

Usage

bnet.sc2.profile.ladders({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);

Match history

Returns match history data for the specified player.

Usage

bnet.sc2.profile.matchHistory({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);

Ladder

Parameters

id the unique ladder ID.

Usage

bnet.sc2.ladder({origin: 'us', id: 655}, callback);

Data Resources

Achievements

Usage

bnet.sc2.data.achievements({origin: 'us'}, callback);

Rewards

Usage

bnet.sc2.data.rewards({origin: 'us'}, callback);

Diablo 3

The Diablo 3 API methods are available via the d3 object of battlenet-api.

var d3 = bnet.d3;

The supported origins and locales for the Diablo 3 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

Season

Index

Returns base information about available seasons.

Usage

bnet.d3.season.index({origin: 'us'}, callback);

Season

Returns a leaderboard list for a particular season.

Parameters

season the season ID.

Usage

bnet.d3.season.season({origin: 'us', season: 1}, callback);

Leaderboard

Returns a leaderboard.

Parameters

season the season ID.

leaderboard the leaderboard to lookup, found in the Season API call.

Usage

bnet.d3.season.leaderboard({origin: 'us', season: 1, leaderboard: 'achievement-points'}, callback);

Season

Index

Returns base information about available eras.

Usage

bnet.d3.era.index({origin: 'us'}, callback);

Era

Returns a leaderboard list for a particular era.

Parameters

era the era ID.

Usage

bnet.d3.era.era({origin: 'us', season: 1}, callback);

Leaderboard

Returns a leaderboard.

Parameters

era the era ID.

leaderboard the leaderboard to lookup, found in the Era API call.

Usage

bnet.d3.era.leaderboard({origin: 'us', season: 1, leaderboard: 'rift-barbarian'}, callback);

Data Resources

Artisan

Parameters

artisan the name of the artisan [blacksmith, jeweller, mystic]

Usage

bnet.d3.data.artisan({origin: 'us', artisan: 'blacksmith'}, callback);

Follower

Parameters

follower the name of the follower [templar, enchantress, scoundrel]

Usage

bnet.d3.data.follower({origin: 'us', follower: 'blacksmith'}, callback);

Item

Parameters

item the item data string.

Usage

bnet.d3.data.item({origin: 'us', item: 'CrABCL-oudQGEgcIBBWZWjYNHWU61OAdyg3pEx07J28kHevi5AUd8dNq1TCLAjj_AkAAUBJYBGD_AmorCgwIABDX3bKmiICA4DESGwi5u5abChIHCAQVIpaumDCPAjgAQAFYBJABAGorCgwIABCl3rKmiICA4DESGwiR9M-gAhIHCAQVIpaumDCLAjgAQAFYBJABAIABRqUBOydvJK0Bj5DKULUBAXBvArgB9aCdsg7AAQEYsuqy0wFQAFgC'} callback);

Profile

Career

Parameters

tag the player's battle tag.

bnet.d3.profile.career({origin: 'us', tag: 'skt-1884'}, callback);

Hero

Parameters

tag the player battle tag.

hero the hero ID.

bnet.d3.profile.hero({origin: 'us', tag: 'skt-1884', hero: 287801}, callback);