Battle.net API

A Node JS wrapper for the Battle.net API

Install

npm install https://github.com/trevonromanuik/battlenet-api/tarball/master --save

How to use

Simply require() the Battle.net API within your application and pass in a valid Battle.net API key:

var bnet = require('battlenet-api')(/* your API KEY here */);

Then you can access the API methods to request data:

bnet.wow.character.profile(params, callback);

Battle.net API Key

You can get a Battle.net API key here: https://dev.battle.net/

Documentation

Each API method takes in a parameters object for the request, and a callback function to execute once the request has completed. The available request parameters are explained for each method below.

Each callback function receives two arguments: error and response.

error applicable when there's an issue with the request connection.

response is the request response body parsed as JSON.

Overview

World of Warcraft

• Achievement
• Auction
• Battle Pet
  • Ability
  • Species
  • Stats
• Challenge
  • Realm Leaderboard
  • Region Leaderboard
• Character
  • Aggregate
  • Achievements
  • Appearance
  • Audit
  • Guild
  • Hunter Pets
  • Items
  • Mounts
  • Pets
  • Pet Slots
  • Profile
  • Progression
  • PVP
  • Quests
  • Reputation
  • Stats
  • 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
• PVP
  • Leaderboards
• Quest
• Realm Status
• Recipe
• Spell

Starcraft 2

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

Diablo 3

• Data Resources
  • Artisan
  • Follower
  • Item
• Profile
  • Career
  • Hero

---

World of Warcraft

The World of Warcraft API methods are available through the wow object of the Battle.net API.

var wow = bnet.wow;

ALL World of Warcraft API methods take the following parameters.

origin: required. This indicates which regional API endpoint to use, and will match the region in which the user plays. The supported origins are us, eu, kr, tw.

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 set the Battle.net API will default to the first value.

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

---

Achievement

Parameters

origin [us, eu, kr, tw]

id the unique achievement ID.

Usage

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

---

Auction

Parameters

origin [us, eu, kr, tw].

realm the slugified realm name.

Usage

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

---

Battle Pet

Abilities

Parameters

origin [us, eu, kr, tw].

id the unique ID of the battle pet ability.

Usage

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

Species

Parameters

origin [us, eu, kr, tw].

id the unique ID of the battle pet species.

Usage

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

Stats

Parameters

origin [us, eu, kr, tw].

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);

---

Challenge

Realm Leaderboard

Parameters

origin [us, eu, kr, tw].

realm the slugified realm name.

Usage

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

Region Leaderboard

Parameters

origin [us, eu, kr, tw].

Usage

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

---

Character

All character requests require the following parameters:

origin [us, eu, kr, tw].

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: 'proudmoore', name: 'charni'}, callback);

Achievements

Returns the achievement data of the character.

Usage

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

Appearance

Returns the appearance data of the character.

Usage

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

Guild

Returns the guild data of the character.

Usage

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

Hunter Pets

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

Usage

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

Items

Returns the item data of the character.

Usage

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

Mounts

Returns the mount data of the character.

Usage

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

Pets

Returns the pet data of the character.

Usage

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

Pet Slots

Returns the pet slots data of the character.

Usage

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

Progression

Returns the progression data of the character.

Usage

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

PVP

Returns the PVP data of the character.

Usage

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

Quests

Returns the quest data of the character.

Usage

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

Reputation

Returns the reputation data of the character.

Usage

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

Stats

Returns the statistics data of the character.

Usage

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

Talents

Returns the talent data of the character.

Usage

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

Titles

Returns the title data of the character.

Usage

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

Audit

Returns an audit of the character's equipment.

Usage

bnet.wow.character.audit({origin: 'us', realm: 'proudmoore', 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: 'proudmoore', name: 'charni', fields: ['pets', 'petSlots']}, callback);

---

Data Resources

Battlegroups

Parameters

origin [us, eu, kr, tw].

Usage

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

Character Achievements

Parameters

origin [us, eu, kr, tw].

Usage

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

Character Classes

Parameters

origin [us, eu, kr, tw].

Usage

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

Character Races

Parameters

origin [us, eu, kr, tw].

Usage

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

Guild Achievements

Parameters

origin [us, eu, kr, tw].

Usage

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

Guild Perks

Parameters

origin [us, eu, kr, tw].

Usage

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

Guild Rewards

Parameters

origin [us, eu, kr, tw].

Usage

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

Item Classes

Parameters

origin [us, eu, kr, tw].

Usage

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

Pet Types

Parameters

origin [us, eu, kr, tw].

Usage

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

Talents

Parameters

origin [us, eu, kr, tw].

Usage

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

---

Item

Item

Returns the item data of the specified item ID.

Parameters

origin [us, eu, kr, tw].

id the unique item ID.

Usage

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

Item Set

Returns the item set data of the specified set ID.

Parameters

origin [us, eu, kr, tw].

id the unique item set ID.

Usage

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

---

Guild

All guild requests require the following parameters:

origin [us, eu, kr, tw].

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: 'proudmoore', name: 'black wolf mercenaries', fields: ['members', achievements]}, callback);

Achievements

Returns the achievement data of the guild.

Usage

bnet.wow.guild.achievements({origin: 'us', realm: 'proudmoore', name: 'black wolf mercenaries'}, callback);

Challenge

Returns the challenge data of the guild.

Usage

bnet.wow.guild.challenge({origin: 'us', realm: 'proudmoore', name: 'black wolf mercenaries'}, callback);

Members

Returns the members data of the guild.

Usage

bnet.wow.guild.members({origin: 'us', realm: 'proudmoore', name: 'black wolf mercenaries'}, callback);

News

Returns the news data of the guild.

Usage

bnet.wow.guild.news({origin: 'us', realm: 'proudmoore', name: 'black wolf mercenaries'}, callback);

Profile

Returns basic profile data of the guild.

Usage

bnet.wow.guild.profile({origin: 'us', realm: 'proudmoore', name: 'black wolf mercenaries'}, callback);

---

PVP

Leaderboards

Parameters

origin [us, eu, kr, tw].

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

Usage

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

---

Quest

Parameters

origin [us, eu, kr, tw].

id the unique quest ID.

Usage

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

---

Realm Status

Parameters

origin [us, eu, kr, tw].

fields [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', 'frostmourne']]}, callback);

---

Recipe

Parameters

origin [us, eu, kr, tw].

id the unique recipe ID.

Usage

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

---

Spell

Parameters

origin [us, eu, kr, tw].

id the unique spell ID.

Usage

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

---

Starcraft 2

The Starcraft 2 API methods are available through the sc2 object of the Battle.net API.

var sc2 = bnet.sc2;

ALL Starcraft 2 API methods take the following parameters.

origin: required. This indicates which regional API endpoint to use, and will match the region in which the user plays. The supported origins are us, eu, sea, kr, tw.

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 set the Battle.net API will default to the first value.

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

---

Profile

All profile requests require the following parameters.

origin [us, eu, sea, kr, tw].

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

origin [us, eu, sea, kr, tw].

id the unique ladder ID.

Usage

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

---

Data Resources

Achievements

Paramters

origin [us, eu, sea, kr, tw].

Usage

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

Rewards

Parameters

origin [us, eu, sea, kr, tw].

Usage

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

---

Diablo 3

The Diablo 3 API methods are available through the d3 object of the Battle.net API.

var d3 = bnet.d3;

ALL Diablo 3 API methods take the following parameters.

origin: required. This indicates which regional API endpoint to use, and will match the region in which the user plays. The supported origins are us, eu, kr, tw.

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 set the Battle.net API will default to the first value.

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

---

Data Resources

Artisan

Parameters

origin [us, eu, kr, tw].

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

Usage

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

Follower

Parameters

origin [us, eu, kr, tw].

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

Usage

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

Item

Parameters

origin [us, eu, kr, tw].

item the item data string.

Usage

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

---

Profile

Career

Parameters

origin [us, eu, kr, tw].

tag the player's battle tag.

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

Hero

Parameters

origin [us, eu, kr, tw].

tag the player battle tag.

hero the hero ID.

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

---