Not Particularly Meaningful

    battlenet-api

    0.13.0-deprecated • Public • Published

    Battle.net API

    Status: Deprecated

    battlenet-api is now deprecated and no longer maintained. A ground-up rewrite is available at 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:

    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.

    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

    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.

    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.

    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.
    • 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:

    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

    World of Warcraft

    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

    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

    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

    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.

    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

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

    Auction

    Parameters

    realm the slugified realm name.

    Usage

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

    Battle Pet

    Abilities

    Parameters

    id the unique ID of the battle pet ability.

    Usage

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

    Species

    Parameters

    id the unique ID of the battle pet species.

    Usage

    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

    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

    bnet.wow.boss.masterList({origin: 'us'}, callback);

    Boss

    Returns an individual Boss specified by id.

    Parameters

    id The boss id.

    Usage

    bnet.wow.boss.boss({origin: 'us', id: 24723}, callback);

    Challenge

    Realm Leaderboard

    Parameters

    realm the slugified realm name.

    Usage

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

    Region Leaderboard

    Usage

    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

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

    Achievements

    Returns the achievement data of the character.

    Usage

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

    Appearance

    Returns the appearance data of the character.

    Usage

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

    Feed

    Returns the character activity feed.

    Usage

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

    Guild

    Returns the guild data of the character.

    Usage

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

    Hunter Pets

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

    Usage

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

    Items

    Returns the item data of the character.

    Usage

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

    Mounts

    Returns the mount data of the character.

    Usage

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

    Pets

    Returns the pet data of the character.

    Usage

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

    Pet Slots

    Returns the pet slots data of the character.

    Usage

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

    Progression

    Returns the progression data of the character.

    Usage

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

    PVP

    Returns the PVP data of the character.

    Usage

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

    Quests

    Returns the quest data of the character.

    Usage

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

    Reputation

    Returns the reputation data of the character.

    Usage

    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

    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

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

    Talents

    Returns the talent data of the character.

    Usage

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

    Titles

    Returns the title data of the character.

    Usage

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

    Audit

    Returns an audit of the character's equipment.

    Usage

    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

    bnet.wow.character.aggregate({origin: 'us', realm: 'amanthul', name: 'charni', fields: ['pets', 'petSlots']}, callback);

    Data Resources

    Battlegroups

    Usage

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

    Character Achievements

    Usage

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

    Character Classes

    Usage

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

    Character Races

    Usage

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

    Guild Achievements

    Usage

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

    Guild Perks

    Usage

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

    Guild Rewards

    Usage

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

    Item Classes

    Usage

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

    Pet Types

    Usage

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

    Talents

    Usage

    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

    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

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

    Mount

    Returns the Mount master list.

    Usage

    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

    bnet.wow.guild.aggregate({origin: 'us', realm: 'amanthul', name: 'blackwolf', fields: ['members', 'achievements']}, callback);

    Achievements

    Returns the achievement data of the guild.

    Usage

    bnet.wow.guild.achievements({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);

    Challenge

    Returns the challenge data of the guild.

    Usage

    bnet.wow.guild.challenge({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);

    Members

    Returns the members data of the guild.

    Usage

    bnet.wow.guild.members({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);

    News

    Returns the news data of the guild.

    Usage

    bnet.wow.guild.news({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);

    Profile

    Returns basic profile data of the guild.

    Usage

    bnet.wow.guild.profile({origin: 'us', realm: 'amanthul', name: 'blackwolf'}, callback);

    PVP

    Leaderboards

    Parameters

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

    Usage

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

    Quest

    Parameters

    id the unique quest ID.

    Usage

    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

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

    Selected realms

    bnet.wow.realmStatus({origin: 'us', realms: ['proudmoore', 'blackrock']}, callback);

    Recipe

    Parameters

    id the unique recipe ID.

    Usage

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

    Spell

    Parameters

    id the unique spell ID.

    Usage

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

    Starcraft 2

    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

    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

    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

    id the unique ladder ID.

    Usage

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

    Data Resources

    Achievements

    Usage

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

    Rewards

    Usage

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

    Diablo 3

    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

    Season

    Index

    Returns base information about available seasons.

    Usage

    bnet.d3.season.index({origin: 'us'}, callback);

    Season

    Returns a leaderboard list for a particular season.

    Parameters

    season the season ID.

    Usage

    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

    bnet.d3.season.leaderboard({origin: 'us', season: 1, leaderboard: 'achievement-points'}, callback);

    Season

    Index

    Returns base information about available eras.

    Usage

    bnet.d3.era.index({origin: 'us'}, callback);

    Era

    Returns a leaderboard list for a particular era.

    Parameters

    era the era ID.

    Usage

    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

    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

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

    Follower

    Parameters

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

    Usage

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

    Item

    Parameters

    item the item data string.

    Usage

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

    Profile

    Career

    Parameters

    tag the player's battle tag.

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

    Hero

    Parameters

    tag the player battle tag.

    hero the hero ID.

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

    Install

    npm i battlenet-api

    DownloadsWeekly Downloads

    6

    Version

    0.13.0-deprecated

    License

    MIT

    Last publish

    Collaborators

    • benweier