battlenet-api
Advanced tools
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.
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
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.
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.
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.tunnelproxyproxyHeaderWhiteListproxyHeaderExclusiveListcallback 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);
});
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.
Returns the authenticated user's account ID and BattleTag.
Usage
bnet.account.user({origin: 'us', access_token: users_access_token}, callback);
Returns data for an authenticated user's World of Warcraft Profile.
Usage
bnet.account.wow({origin: 'us', access_token: users_access_token}, callback);
Returns data for an authenticated user's Starcraft III Profile.
Usage
bnet.account.sc2({origin: 'us', access_token: users_access_token}, callback);
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 |
Parameters
id the unique achievement ID.
Usage
bnet.wow.achievement({origin: 'us', id: 2144}, callback);
Parameters
realm the slugified realm name.
Usage
bnet.wow.auction({origin: 'us', realm: 'amanthul'}, callback);
Parameters
id the unique ID of the battle pet ability.
Usage
bnet.wow.battlePet.ability({origin: 'us', id: 640}, callback);
Parameters
id the unique ID of the battle pet species.
Usage
bnet.wow.battlePet.species({origin: 'us', id: 258}, callback);
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);
Parameters
realm the slugified realm name.
Usage
bnet.wow.challenge.realmLeaderboard({origin: 'us', realm: 'amanthul'}, callback);
Usage
bnet.wow.challenge.regionLeaderboard({origin: 'us'}, callback);
All World of Warcraft character requests require the following parameters:
realm the slugified realm of the character.
name the name of the character.
Returns basic profile data about the character.
Usage
bnet.wow.character.profile({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the achievement data of the character.
Usage
bnet.wow.character.achievements({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the appearance data of the character.
Usage
bnet.wow.character.appearance({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the character activity feed.
Usage
bnet.wow.character.feed({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the guild data of the character.
Usage
bnet.wow.character.guild({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the hunter pet data of the character (where applicable).
Usage
bnet.wow.character.hunterPets({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the item data of the character.
Usage
bnet.wow.character.items({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the mount data of the character.
Usage
bnet.wow.character.mounts({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the pet data of the character.
Usage
bnet.wow.character.pets({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the pet slots data of the character.
Usage
bnet.wow.character.petSlots({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the progression data of the character.
Usage
bnet.wow.character.progression({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the PVP data of the character.
Usage
bnet.wow.character.pvp({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the quest data of the character.
Usage
bnet.wow.character.quests({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the reputation data of the character.
Usage
bnet.wow.character.reputation({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
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);
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);
Returns the talent data of the character.
Usage
bnet.wow.character.talents({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns the title data of the character.
Usage
bnet.wow.character.titles({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
Returns an audit of the character's equipment.
Usage
bnet.wow.character.audit({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
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);
Usage
bnet.wow.data.battlegroups({origin: 'us'}, callback);
Usage
bnet.wow.data.characterAchievements({origin: 'us'}, callback);
Usage
bnet.wow.data.characterClasses({origin: 'us'}, callback);
Usage
bnet.wow.data.characterRaces({origin: 'us'}, callback);
Usage
bnet.wow.data.guildAchievements({origin: 'us'}, callback);
Usage
bnet.wow.data.guildPerks({origin: 'us'}, callback);
Usage
bnet.wow.data.guildRewards({origin: 'us'}, callback);
Usage
bnet.wow.data.itemClasses({origin: 'us'}, callback);
Usage
bnet.wow.data.petTypes({origin: 'us'}, callback);
Usage
bnet.wow.data.talents({origin: 'us'}, callback);
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.
Usage
bnet.wow.item.item({origin: 'us', id: 18803}, callback);
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);
All World of Warcraft guild requests require the following parameters:
realm the slugified realm of the guild.
name the name of the guild.
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);
Returns the achievement data of the guild.
Usage
bnet.wow.guild.achievements({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
Returns the challenge data of the guild.
Usage
bnet.wow.guild.challenge({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
Returns the members data of the guild.
Usage
bnet.wow.guild.members({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
Returns the news data of the guild.
Usage
bnet.wow.guild.news({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
Returns basic profile data of the guild.
Usage
bnet.wow.guild.profile({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
Parameters
bracket [2v2, 3v3, 5v5, rbg]
Usage
bnet.wow.pvp.leaderboards({origin: 'us', bracket: '2v2'}, callback);
Parameters
id the unique quest ID.
Usage
bnet.wow.quest({origin: 'us', quest: 13146}, callback);
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);
Parameters
id the unique recipe ID.
Usage
bnet.wow.recipe({origin: 'us', id: 33994}, callback);
Parameters
id the unique spell ID.
Usage
bnet.wow.spell({origin: 'us', id: 8056}, callback);
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 |
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.
Returns basic profile data for the specified player.
Usage
bnet.sc2.profile.profile({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);
Returns ladder data for the specified player.
Usage
bnet.sc2.profile.ladders({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);
Returns match history data for the specified player.
Usage
bnet.sc2.profile.matchHistory({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);
Parameters
id the unique ladder ID.
Usage
bnet.sc2.ladder({origin: 'us', id: 655}, callback);
Usage
bnet.sc2.data.achievements({origin: 'us'}, callback);
Usage
bnet.sc2.data.rewards({origin: 'us'}, callback);
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 |
Parameters
artisan the name of the artisan [blacksmith, jeweller, mystic]
Usage
bnet.d3.data.artisan({origin: 'us', artisan: 'blacksmith'}, callback);
Parameters
follower the name of the follower [templar, enchantress, scoundrel]
Usage
bnet.d3.data.follower({origin: 'us', follower: 'blacksmith'}, callback);
Parameters
item the item data string.
Usage
bnet.d3.data.item({origin: 'us', item: 'CrABCL-oudQGEgcIBBWZWjYNHWU61OAdyg3pEx07J28kHevi5AUd8dNq1TCLAjj_AkAAUBJYBGD_AmorCgwIABDX3bKmiICA4DESGwi5u5abChIHCAQVIpaumDCPAjgAQAFYBJABAGorCgwIABCl3rKmiICA4DESGwiR9M-gAhIHCAQVIpaumDCLAjgAQAFYBJABAIABRqUBOydvJK0Bj5DKULUBAXBvArgB9aCdsg7AAQEYsuqy0wFQAFgC'} callback);
Parameters
tag the player's battle tag.
bnet.d3.profile.career({origin: 'us', tag: 'skt-1884'}, callback);
Parameters
tag the player battle tag.
hero the hero ID.
bnet.d3.profile.hero({origin: 'us', tag: 'skt-1884', hero: 287801}, callback);
FAQs
A Node.JS library for the Battle.net Community Platform API
The npm package battlenet-api receives a total of 4 weekly downloads. As such, battlenet-api popularity was classified as not popular.
We found that battlenet-api demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.