# Battle.net API
### battlenet-api is now deprecated and no longer maintained. A ground-up rewrite is available at [blizzard.js](https://github.com/benweier/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:
```javascript
var bnet = require('battlenet-api')();
```
Step 2: Call the API methods to request data:
```javascript
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**
```javascript
bnet.wow.character.profile(parameters, {apikey: your_api_key}, callback);
```
**As an optional parameter with require**
```javascript
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](https://dev.battle.net) 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](#overview).
```javascript
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](https://www.npmjs.com/package/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:
```javascript
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](#account)
* [ID](#account-user)
* [BattleTag](#account-battletag)
* [World of Warcraft OAuth Profile](#account-wow)
* [Starcraft II OAuth Profile](#account-sc2)
### [World of Warcraft](#wow)
* [Achievement](#wow-achievement)
* [Auction](#wow-auction)
* [Battle Pet](#wow-battle-pet)
* [Ability](#wow-battle-pet-ability)
* [Species](#wow-battle-pet-species)
* [Stats](#wow-battle-pet-stats)
* [Boss](#wow-boss)
* [Master List](#wow-boss-master-list)
* [Boss](#wow-boss-boss)
* [Challenge](#wow-challenge)
* [Realm Leaderboard](#wow-challenge-realm-leaderboard)
* [Region Leaderboard](#wow-challenge-region-leaderboard)
* [Character](#wow-character)
* [Aggregate](#character-aggregate)
* [Achievements](#wow-character-achievements)
* [Appearance](#wow-character-appearance)
* [Audit](#wow-character-audit)
* [Feed](#wow-character-feed)
* [Guild](#wow-character-guild)
* [Hunter Pets](#wow-character-hunter-pets)
* [Items](#wow-character-items)
* [Mounts](#wow-character-mounts)
* [Pets](#wow-character-pets)
* [Pet Slots](#wow-character-pet-slots)
* [Profile](#wow-character-profile)
* [Progression](#wow-character-progression)
* [PVP](#wow-character-pvp)
* [Quests](#wow-character-quests)
* [Reputation](#wow-character-reputation)
* [Stats](#wow-character-stats)
* [Statistics](#wow-character-statistics)
* [Talents](#wow-character-talents)
* [Titles](#wow-character-titles)
* [Data Resources](#wow-data)
* [Battlegroups](#wow-data-battlegroups)
* [Character Achievements](#wow-data-character-achievements)
* [Character Classes](#wow-data-character-classes)
* [Character Races](#wow-data-character-races)
* [Guild Achievements](#wow-data-guild-achievements)
* [Guild Perks](#wow-data-guild-perks)
* [Guild Rewards](#wow-data-guild-rewards)
* [Item Classes](#wow-data-item-classes)
* [Pet Types](#wow-data-pet-types)
* [Talents](#wow-data-talents)
* [Guild](#wow-guild)
* [Aggregate](#wow-guild-aggregate)
* [Achievements](#wow-guild-achievements)
* [Challenge](#wow-guild-challenge)
* [Members](#wow-guild-members)
* [News](#wow-guild-news)
* [Profile](#wow-guild-profile)
* [Item](#wow-item)
* [Item](#wow-item-item)
* [Item Set](#wow-item-item-set)
* [Mount](#wow-mount)
* [PVP](#wow-pvp)
* [Leaderboards](#wow-pvp-leaderboards)
* [Quest](#wow-quest)
* [Realm Status](#wow-realm-status)
* [Recipe](#wow-recipe)
* [Spell](#wow-spell)
### [Starcraft 2](#sc2)
* [Data Resources](#sc2-data)
* [Achievements](#sc2-data-achievements)
* [Rewards](#sc2-data-rewards)
* [Ladder](#sc2-ladder)
* [Profile](#sc2-profile)
* [Profile](#sc2-profile-profile)
* [Ladders](#sc2-profile-ladders)
* [Match History](#sc2-profile-match-history)
### [Diablo 3](#d3)
* [Seasons](#d3-season)
* [Index](#d3-season-index)
* [Season](#d3-season-season)
* [Leaderboard](#d3-season-leaderboard)
* [Eras](#d3-era)
* [Index](#d3-era-index)
* [Era](#d3-era-era)
* [Leaderboard](#d3-era-leaderboard)
* [Data Resources](#d3-data)
* [Artisan](#d3-data-artisan)
* [Follower](#d3-data-follower)
* [Item](#d3-data-item)
* [Profile](#d3-profile)
* [Career](#d3-profile-career)
* [Hero](#d3-profile-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](https://www.npmjs.com/package/passport-bnet) package and reading the [Using OAuth](https://dev.battle.net/docs/read/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*
```javascript
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*
```javascript
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*
```javascript
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_.
```javascript
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*
```javascript
bnet.wow.achievement({origin: 'us', id: 2144}, callback);
```
---
### Auction
*Parameters*
`realm` the slugified realm name.
*Usage*
```javascript
bnet.wow.auction({origin: 'us', realm: 'amanthul'}, callback);
```
---
### Battle Pet
#### Abilities
*Parameters*
`id` the unique ID of the battle pet ability.
*Usage*
```javascript
bnet.wow.battlePet.ability({origin: 'us', id: 640}, callback);
```
#### Species
*Parameters*
`id` the unique ID of the battle pet species.
*Usage*
```javascript
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*
```javascript
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*
```javascript
bnet.wow.boss.masterList({origin: 'us'}, callback);
```
#### Boss
Returns an individual Boss specified by id.
*Parameters*
`id` The boss id.
*Usage*
```javascript
bnet.wow.boss.boss({origin: 'us', id: 24723}, callback);
```
---
### Challenge
#### Realm Leaderboard
*Parameters*
`realm` the slugified realm name.
*Usage*
```javascript
bnet.wow.challenge.realmLeaderboard({origin: 'us', realm: 'amanthul'}, callback);
```
#### Region Leaderboard
*Usage*
```javascript
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*
```javascript
bnet.wow.character.profile({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Achievements
Returns the achievement data of the character.
*Usage*
```javascript
bnet.wow.character.achievements({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Appearance
Returns the appearance data of the character.
*Usage*
```javascript
bnet.wow.character.appearance({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Feed
Returns the character activity feed.
*Usage*
```javascript
bnet.wow.character.feed({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Guild
Returns the guild data of the character.
*Usage*
```javascript
bnet.wow.character.guild({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Hunter Pets
Returns the hunter pet data of the character (where applicable).
*Usage*
```javascript
bnet.wow.character.hunterPets({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Items
Returns the item data of the character.
*Usage*
```javascript
bnet.wow.character.items({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Mounts
Returns the mount data of the character.
*Usage*
```javascript
bnet.wow.character.mounts({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Pets
Returns the pet data of the character.
*Usage*
```javascript
bnet.wow.character.pets({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Pet Slots
Returns the pet slots data of the character.
*Usage*
```javascript
bnet.wow.character.petSlots({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Progression
Returns the progression data of the character.
*Usage*
```javascript
bnet.wow.character.progression({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### PVP
Returns the PVP data of the character.
*Usage*
```javascript
bnet.wow.character.pvp({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Quests
Returns the quest data of the character.
*Usage*
```javascript
bnet.wow.character.quests({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Reputation
Returns the reputation data of the character.
*Usage*
```javascript
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*
```javascript
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*
```javascript
bnet.wow.character.statistics({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Talents
Returns the talent data of the character.
*Usage*
```javascript
bnet.wow.character.talents({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Titles
Returns the title data of the character.
*Usage*
```javascript
bnet.wow.character.titles({origin: 'us', realm: 'amanthul', name: 'charni'}, callback);
```
#### Audit
Returns an audit of the character's equipment.
*Usage*
```javascript
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*
```javascript
bnet.wow.character.aggregate({origin: 'us', realm: 'amanthul', name: 'charni', fields: ['pets', 'petSlots']}, callback);
```
---
### Data Resources
#### Battlegroups
*Usage*
```javascript
bnet.wow.data.battlegroups({origin: 'us'}, callback);
```
#### Character Achievements
*Usage*
```javascript
bnet.wow.data.characterAchievements({origin: 'us'}, callback);
```
#### Character Classes
*Usage*
```javascript
bnet.wow.data.characterClasses({origin: 'us'}, callback);
```
#### Character Races
*Usage*
```javascript
bnet.wow.data.characterRaces({origin: 'us'}, callback);
```
#### Guild Achievements
*Usage*
```javascript
bnet.wow.data.guildAchievements({origin: 'us'}, callback);
```
#### Guild Perks
*Usage*
```javascript
bnet.wow.data.guildPerks({origin: 'us'}, callback);
```
#### Guild Rewards
*Usage*
```javascript
bnet.wow.data.guildRewards({origin: 'us'}, callback);
```
#### Item Classes
*Usage*
```javascript
bnet.wow.data.itemClasses({origin: 'us'}, callback);
```
#### Pet Types
*Usage*
```javascript
bnet.wow.data.petTypes({origin: 'us'}, callback);
```
#### Talents
*Usage*
```javascript
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*
```javascript
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*
```javascript
bnet.wow.item.set({origin: 'us', id: 1060}, callback);
```
---
### Mount
Returns the Mount master list.
*Usage*
```javascript
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*
```javascript
bnet.wow.guild.aggregate({origin: 'us', realm: 'amanthul', name: 'blackwolf', fields: ['members', 'achievements']}, callback);
```
#### Achievements
Returns the achievement data of the guild.
*Usage*
```javascript
bnet.wow.guild.achievements({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
```
#### Challenge
Returns the challenge data of the guild.
*Usage*
```javascript
bnet.wow.guild.challenge({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
```
#### Members
Returns the members data of the guild.
*Usage*
```javascript
bnet.wow.guild.members({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
```
#### News
Returns the news data of the guild.
*Usage*
```javascript
bnet.wow.guild.news({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
```
#### Profile
Returns basic profile data of the guild.
*Usage*
```javascript
bnet.wow.guild.profile({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);
```
---
### PVP
#### Leaderboards
*Parameters*
`bracket` [`2v2`, `3v3`, `5v5`, `rbg`]
*Usage*
```javascript
bnet.wow.pvp.leaderboards({origin: 'us', bracket: '2v2'}, callback);
```
---
### Quest
*Parameters*
`id` the unique quest ID.
*Usage*
```javascript
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
```javascript
bnet.wow.realmStatus({origin: 'us'}, callback);
```
Selected realms
```javascript
bnet.wow.realmStatus({origin: 'us', realms: ['proudmoore', 'blackrock']}, callback);
```
---
### Recipe
*Parameters*
`id` the unique recipe ID.
*Usage*
```javascript
bnet.wow.recipe({origin: 'us', id: 33994}, callback);
```
---
### Spell
*Parameters*
`id` the unique spell ID.
*Usage*
```javascript
bnet.wow.spell({origin: 'us', id: 8056}, callback);
```
---
## Starcraft 2
The Starcraft 2 API methods are available via the `sc2` object of _battlenet-api_.
```javascript
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*
```javascript
bnet.sc2.profile.profile({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);
```
#### Ladders
Returns ladder data for the specified player.
*Usage*
```javascript
bnet.sc2.profile.ladders({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);
```
#### Match history
Returns match history data for the specified player.
*Usage*
```javascript
bnet.sc2.profile.matchHistory({origin: 'us', id: 2137104, region: 1, name: 'skt'}, callback);
```
---
### Ladder
*Parameters*
`id` the unique ladder ID.
*Usage*
```javascript
bnet.sc2.ladder({origin: 'us', id: 655}, callback);
```
---
### Data Resources
#### Achievements
*Usage*
```javascript
bnet.sc2.data.achievements({origin: 'us'}, callback);
```
#### Rewards
*Usage*
```javascript
bnet.sc2.data.rewards({origin: 'us'}, callback);
```
---
## Diablo 3
The Diablo 3 API methods are available via the `d3` object of _battlenet-api_.
```javascript
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*
```javascript
bnet.d3.season.index({origin: 'us'}, callback);
```
#### Season
Returns a leaderboard list for a particular season.
*Parameters*
`season` the season ID.
*Usage*
```javascript
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*
```javascript
bnet.d3.season.leaderboard({origin: 'us', season: 1, leaderboard: 'achievement-points'}, callback);
```
---
### Season
#### Index
Returns base information about available eras.
*Usage*
```javascript
bnet.d3.era.index({origin: 'us'}, callback);
```
#### Era
Returns a leaderboard list for a particular era.
*Parameters*
`era` the era ID.
*Usage*
```javascript
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*
```javascript
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*
```javascript
bnet.d3.data.artisan({origin: 'us', artisan: 'blacksmith'}, callback);
```
#### Follower
*Parameters*
`follower` the name of the follower [`templar`, `enchantress`, `scoundrel`]
*Usage*
```javascript
bnet.d3.data.follower({origin: 'us', follower: 'blacksmith'}, callback);
```
#### Item
*Parameters*
`item` the item data string.
*Usage*
```javascript
bnet.d3.data.item({origin: 'us', item: 'CrABCL-oudQGEgcIBBWZWjYNHWU61OAdyg3pEx07J28kHevi5AUd8dNq1TCLAjj_AkAAUBJYBGD_AmorCgwIABDX3bKmiICA4DESGwi5u5abChIHCAQVIpaumDCPAjgAQAFYBJABAGorCgwIABCl3rKmiICA4DESGwiR9M-gAhIHCAQVIpaumDCLAjgAQAFYBJABAIABRqUBOydvJK0Bj5DKULUBAXBvArgB9aCdsg7AAQEYsuqy0wFQAFgC'} callback);
```
---
### Profile
#### Career
*Parameters*
`tag` the player's battle tag.
```javascript
bnet.d3.profile.career({origin: 'us', tag: 'skt-1884'}, callback);
```
#### Hero
*Parameters*
`tag` the player battle tag.
`hero` the hero ID.
```javascript
bnet.d3.profile.hero({origin: 'us', tag: 'skt-1884', hero: 287801}, callback);
```
---