Battle.net API
blizzard.js featuring a major version number, a cleaner API, promises support, a test suite, richer documentation, and an example app.
battlenet-api is now deprecated and no longer maintained. A ground-up rewrite is available atPlease 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 = ;
Step 2: Call the API methods to request data:
bnetwowcharacterprofileparameters 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
bnetwowcharacterprofileparameters apikey: your_api_key callback;
As an optional parameter with require
var bnet = 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.
bnetwowcharacterprofileparameters 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 whichorigin
is used, and when nolocale
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. Otherwisenull
.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 asheaders
andstatusCode
.
A fully-formed request will look something like this:
bnetwowcharacter;
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
World of Warcraft
- Achievement
- Auction
- Battle Pet
- Boss
- Challenge
- Character
- Data Resources
- Guild
- Item
- Mount
- PVP
- Quest
- Realm Status
- Recipe
- Spell
Starcraft 2
Diablo 3
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
bnetaccount;
World of Warcraft OAuth Profile
Returns data for an authenticated user's World of Warcraft Profile.
Usage
bnetaccount;
Starcraft II OAuth Profile
Returns data for an authenticated user's Starcraft III Profile.
Usage
bnetaccount;
World of Warcraft
The World of Warcraft API methods are available via the wow
object of battlenet-api.
var wow = bnetwow;
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
bnetwow;
Auction
Parameters
realm
the slugified realm name.
Usage
bnetwow;
Battle Pet
Abilities
Parameters
id
the unique ID of the battle pet ability.
Usage
bnetwowbattlePet;
Species
Parameters
id
the unique ID of the battle pet species.
Usage
bnetwowbattlePet;
Stats
Parameters
id
the unique ID of the battle pet species.
fields
an object containing the battle pet level
, breedId
, and qualityId
Usage
bnetwowbattlePet;
Boss
Master List
Return the Boss master list.
Usage
bnetwowboss;
Boss
Returns an individual Boss specified by id.
Parameters
id
The boss id.
Usage
bnetwowboss;
Challenge
Realm Leaderboard
Parameters
realm
the slugified realm name.
Usage
bnetwowchallenge;
Region Leaderboard
Usage
bnetwowchallenge;
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
bnetwowcharacterprofileorigin: 'us' realm: 'amanthul' name: 'charni' callback;
Achievements
Returns the achievement data of the character.
Usage
bnetwowcharacter;
Appearance
Returns the appearance data of the character.
Usage
bnetwowcharacter;
Feed
Returns the character activity feed.
Usage
bnetwowcharacter;
Guild
Returns the guild data of the character.
Usage
bnetwowcharacter;
Hunter Pets
Returns the hunter pet data of the character (where applicable).
Usage
bnetwowcharacter;
Items
Returns the item data of the character.
Usage
bnetwowcharacter;
Mounts
Returns the mount data of the character.
Usage
bnetwowcharacter;
Pets
Returns the pet data of the character.
Usage
bnetwowcharacter;
Pet Slots
Returns the pet slots data of the character.
Usage
bnetwowcharacter;
Progression
Returns the progression data of the character.
Usage
bnetwowcharacter;
PVP
Returns the PVP data of the character.
Usage
bnetwowcharacter;
Quests
Returns the quest data of the character.
Usage
bnetwowcharacter;
Reputation
Returns the reputation data of the character.
Usage
bnetwowcharacter;
Stats
Returns the character sheet stats of the character like Strength and Agility. Note the difference between the stats
and statistics
methods.
Usage
bnetwowcharacter;
Statistics
Returns the gameplay statistics of the character like 'Used X bandages' etc. Note the difference between the stats
and statistics
methods.
Usage
bnetwowcharacter;
Talents
Returns the talent data of the character.
Usage
bnetwowcharacter;
Titles
Returns the title data of the character.
Usage
bnetwowcharacter;
Audit
Returns an audit of the character's equipment.
Usage
bnetwowcharacter;
Aggregate
Returns the specified character fields aggregated in a single request.
Parameters
fields
an array of one or more character fields.
Usage
bnetwowcharacter;
Data Resources
Battlegroups
Usage
bnetwowdata;
Character Achievements
Usage
bnetwowdata;
Character Classes
Usage
bnetwowdata;
Character Races
Usage
bnetwowdata;
Guild Achievements
Usage
bnetwowdata;
Guild Perks
Usage
bnetwowdata;
Guild Rewards
Usage
bnetwowdata;
Item Classes
Usage
bnetwowdata;
Pet Types
Usage
bnetwowdata;
Talents
Usage
bnetwowdata;
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
bnetwowitem;
Item Set
Returns the item set data of the specified set ID.
Parameters
id
the unique item set ID.
Usage
bnetwowitem;
Mount
Returns the Mount master list.
Usage
bnetwow;
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
bnetwowguild;
Achievements
Returns the achievement data of the guild.
Usage
bnetwowguild;
Challenge
Returns the challenge data of the guild.
Usage
bnetwowguild;
Members
Returns the members data of the guild.
Usage
bnetwowguild;
News
Returns the news data of the guild.
Usage
bnetwowguild;
Profile
Returns basic profile data of the guild.
Usage
bnetwowguildprofileorigin: 'us' realm: 'amanthul' name: 'blackwolf' callback;
PVP
Leaderboards
Parameters
bracket
[2v2
, 3v3
, 5v5
, rbg
]
Usage
bnetwowpvp;
Quest
Parameters
id
the unique quest ID.
Usage
bnetwow;
Realm Status
Parameters
realms
[optional] an array of one or more realms to limit.
Usage
All realms
bnetwow;
Selected realms
bnetwow;
Recipe
Parameters
id
the unique recipe ID.
Usage
bnetwow;
Spell
Parameters
id
the unique spell ID.
Usage
bnetwow;
Starcraft 2
The Starcraft 2 API methods are available via the sc2
object of battlenet-api.
var sc2 = bnetsc2;
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
bnetsc2profileprofileorigin: 'us' id: 2137104 region: 1 name: 'skt' callback;
Ladders
Returns ladder data for the specified player.
Usage
bnetsc2profile;
Match history
Returns match history data for the specified player.
Usage
bnetsc2profile;
Ladder
Parameters
id
the unique ladder ID.
Usage
bnetsc2;
Data Resources
Achievements
Usage
bnetsc2data;
Rewards
Usage
bnetsc2data;
Diablo 3
The Diablo 3 API methods are available via the d3
object of battlenet-api.
var d3 = bnetd3;
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
bnetd3seasonindexorigin: 'us' callback;
Season
Returns a leaderboard list for a particular season.
Parameters
season
the season ID.
Usage
bnetd3season;
Leaderboard
Returns a leaderboard.
Parameters
season
the season ID.
leaderboard
the leaderboard to lookup, found in the Season API call.
Usage
bnetd3season;
Season
Index
Returns base information about available eras.
Usage
bnetd3eraindexorigin: 'us' callback;
Era
Returns a leaderboard list for a particular era.
Parameters
era
the era ID.
Usage
bnetd3era;
Leaderboard
Returns a leaderboard.
Parameters
era
the era ID.
leaderboard
the leaderboard to lookup, found in the Era API call.
Usage
bnetd3era;
Data Resources
Artisan
Parameters
artisan
the name of the artisan [blacksmith
, jeweller
, mystic
]
Usage
bnetd3data;
Follower
Parameters
follower
the name of the follower [templar
, enchantress
, scoundrel
]
Usage
bnetd3data;
Item
Parameters
item
the item data string.
Usage
bnetd3data;
Profile
Career
Parameters
tag
the player's battle tag.
bnetd3profile;
Hero
Parameters
tag
the player battle tag.
hero
the hero ID.
bnetd3profile;