Product
Socket Now Supports uv.lock Files
Socket now supports uv.lock files to ensure consistent, secure dependency resolution for Python projects and enhance supply chain security.
By Trevor Norris - Jan 09, 2025
Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
battlenet-api
Advanced tools
Battle.net API
A Node JS wrapper for the Battle.net API
Install
Add battlenet-api to your application's package.json file and run:
npm install
Alternatively:
npm install battlenet-api --save
How to use
Simply require() the Battle.net API within your application:
var bnet = require('battlenet-api');
And then access the API methods to request data:
bnet.wow.character.profile(obj, callback);
Battle.net API Key
Your private Battle.net API key is input with the BATTLENET_API_KEY environment variable. This must be present in order to get a valid Battle.net API response. There are several ways to set this variable but the easiest is to run your node server with the variable from the command line.
$ sudo BATTLENET_API_KEY=[your_api_key] node server.js
Documentation
Each API method receives 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
- Challenge
- Character
- Data Resources
- Guild
- Item
- PVP
- Quest
- Realm Status
- Recipe
- Spell
Starcraft 2
Diablo 3
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({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);
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.
Package last updated on 30 Aug 2014
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.
Related posts
Research
Security News
Gmail For Exfiltration: Malicious npm Packages Target Solana Private Keys and Drain Victims' Wallets
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.
By Kirill Boychenko - Jan 08, 2025
Security News
New Python Packaging Proposal Aims to Solve Phantom Dependency Problem with SBOMs
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.
By Sarah Gooding - Jan 07, 2025