Blizzard Community Platform API Documentation

Blizzard Entertainment

6/10/2011

Abstract

This is the documentation for the RESTful APIs exposed through the World of Warcraft community site as a service to the World of Warcraft community.

Table of Contents

Introduction
1. Features
REST
Access and Regions
Throttling
Authentication
Application Registration
Authentication Process
Formats and Protocols
Error Handling
Support
2. API Reference
Character Resources
Profile
Guild Resources
Profile API
Realm Resources
Realm Status
Data Resources
Character Races
Character Classes
Guild Rewards
Guild Perks
Items
3. API Policy
4. Frequently Asked Questions

Introduction

The Blizzard Community Platform API provides a number of resources for developers and Wow enthusiasts to gather data about their characters, guilds and arena teams. This documentation is primarily for developers and third parties.

Blizzard's epic gaming experiences often take place in game, but can lead to rewarding and lasting experiences out of game as well. Through exposing key sets of data, we can enable the community to create extended communities to continue that epic experience.

Chapter 1. Features

Table of Contents

REST
Access and Regions
Throttling
Authentication
Application Registration
Authentication Process
Formats and Protocols
Error Handling
Support

Before getting started with the Community Platform API, programmers must first understand how the API is organized and how it works. The following sections provide a high level overview of the features of this API. It is recommended that the reader have knowledge of the HTTP protocol as well as a general understanding of web technologies.

REST

The API is mostly RESTful. Data is exposed in the form of URIs that represent resources and can be fetched with HTTP clients (like web browsers). At this time, the API is limited to read-only operations.

NKG: Document support for ETAG headers.

NKG: Document support for last-modified headers.

NKG: Make note that all requests should be UTF-8 encoded.

Access and Regions

To access the API, HTTP requests can be made to specific URLs and resources exposed on the regional Battle.net domains.

Example 1.1. An example API request and response.

GET /api/wow/realm/status HTTP/1.1
Host: us.battle.net

HTTP/1.1 200 OK


{"realms":[ ... ]}

The regions where this API is available are:

  • us.battle.net

  • eu.battle.net

  • kr.battle.net

  • tw.battle.net

  • battlenet.com.cn

The data available through the API is limited to the region that it is in. Hence, US APIs accessed through us.battle.net will only contain data within US battlegroups and realms. Support for locales is limited to those supported on the World of Warcraft community sites.

Throttling

Consumers of the API can make a limited number of requests per day, as stated in the API Policy and Terms of Use. For anonymous consumers of the API, the number of requests that can be made per day is set to 3,000. Once that threshold is reached, depending on site activity and performance, subsequent requests may be denied. High limits are available to registered applications.

Authentication

Although most of the application can be accessed without any form of authentication, we do support a form application registration and authentication. Application authentication involves creating and including an application identifier and a request signature and including those values with the request headers.

The primary benefit to making requests as an authenticated application is that you can make more requests per day.

Application Registration

To send authenticated request you first need to register an application. Because registration isn't automated, application registration is limited to those who meet the following criteria:

  • You plan on making requests from one or more IP addresses. (e.g. a production environment and development environment)

  • You can justify making more than 2,000 requests per day from one or more IP addresses.

Registering an application is a matter of providing a description of the application, how you plan on using the API and your contact information to with the subject "Application Registration Request". Once we receive your request, we will contact you to either provide additional information or with application keys to use.

Authentication Process

To authenticate a request, simple include the "Authorization" header with your application identifier and the request signature.

NKG: Update the below example to use "exampleprivate" and "examplepublic".

Example 1.2. An example authenticated request

GET /api/wow/character/Medivh/Thrall HTTP/1.1
Host: us.battle.net
Date: Fri, 10 Jun 2011 20:59:24 GMT
Authorization: BNET c1fbf21b79c03191d:+3fE0RaKc+PqxN0gi8va5GQC35A=

In the above exmple, the value of the Authorization header has three parts "BNET", "c1fbf21b79c03191d" and "+3fE0RaKc+PqxN0gi8va5GQC35A=". The first part is a processing directive for the Authorization header. The second and third values are the application public key and the request signature. The application public key is assigned by Blizzard during the application registration process. The signature is generated with each request and is discribed by the following algorithm.

UrlPath = 

StringToSign = HTTP-Verb + "\n" +
    Date + "\n" +
    UrlPath + "\n";

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( PrivateKey, StringToSign ) ) );

Authorization = "BNET" + " " + PublicKey + ":" + Signature;

The above process can be seen in action by filling in the blanks:

UrlPath = "/api/wow/realm/status"

StringToSign = "GET" + "\n" +
    "Fri, 10 Jun 2011 21:37:34 GMT" + "\n" +
    UrlPath + "\n";

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( "examplesecret" ), StringToSign ) );

Authorization = "BNET" + " " + "examplekey" + ":" + Signature;

The date timestamp used in the above algorithm and example is the value of the Date HTTP header. The two date values, the first being used to sign the request and the second as sent with the request headers, must be the same and within 15 seconds of the current GMT time.

Formats and Protocols

Data returned in the response message is provided in JSON format. Please refer to the examples provided with each API section for additional information.

Error Handling

Although several of the API resources have specific error responses that corrospond to specific situations, there are several generic error responses that you should be aware of.

Errors are returned as JSON objects that contain "status" and "reason" attributes. The value of the "status" attribute will always be "nok". The reason will be an english string that may be, but is not limited to, one of the following strings.

Invalid Application

HTTP Response Code: 500

A request was made including application identification information, but either the application key is invalid or missing.

Invalid application permissions.

HTTP Response Code: 500

A request was made to an API resource that requires a higher application permission level.

Access denied, please contact api-support@blizzard.com

HTTP Response Code: 500

The application or IP address has been blocked from making further requests. This ban may not be permanent.

When in doubt, blow it up. (page not found)

HTTP Response Code: 404

A request was made to a resource that doesn't exist.

If at first you don't succeed, blow it up again. (too many requests)

HTTP Response Code: 500

The application or IP has been throttled.

Have you not been through enough? Will you continue to fight what you cannot defeat? (something unexpected happened)

HTTP Response Code: 500

There was a server error or equally catastrophic exception preventing the request from being fulfilled.

Invalid authentication header.

HTTP Response Code: 500

The application authorization information was mallformed or missing when expected.

Invalid application signature.

HTTP Response Code: 500

The application request signature was missing or invalid. This will also be thrown if the request date outside of a 15 second window from the current GMT time.

Example 1.3. An example API request and and error response

GET /api/wow/data/boss/45 HTTP/1.1
Host: us.battle.net

HTTP/1.1 404 Not Found



{"status":"nok", "reason": "When in doubt, blow it up. (page not found)"}

Support

For questions about the API, please use the Community Platform API forums as a platform to ask questions and get help.

http://us.battle.net/wow/en/forum/2626217/

You can also email for matters that you may not want public discussion for.

Chapter 2. API Reference

Table of Contents

Character Resources
Profile
Guild Resources
Profile API
Realm Resources
Realm Status
Data Resources
Character Races
Character Classes
Guild Rewards
Guild Perks
Items

Character Resources

Character APIs currently provide character profile information.

Profile

The Character Profile API is the primary way to access character information. This Character Profile API can be used to fetch a single character at a time through an HTTP GET request to a URL describing the character profile resource. By default, a basic dataset will be returned and with each request and zero or more additional fields can be retrieved. To access this API, craft a resource URL pointing to the character whos information is to be retrieved.

URL = Host + "/api/wow/character/" + Realm + "/" + CharacterName

Realm =  |

There are no required query string parameters when accessing this resource, although the "fields" query string parameter can optionally be passed to indicate that one or more of the optional datasets is to be retrieved. Those additional fields are listed in the subsection titled "Optional Fields".

Example 2.1. An example Character Profile API request and response.

GET /api/wow/character/Medivh/Uther?fields=guild
Host: us.battle.net
HTTP/1.1 200 OK


{"realm": "Medivh", "name": "Uther", "level": 85, "lastModified": 1307596000000, "thumbnail": "medivh/1/1-avatar.jpg",
"race": 1, "achievementPoints": 9745, "gender": 0, "class": 2, "guild": { ... } }

The core dataset returned includes the character's realm, name, level, last modified timestamp, thumbnail, race id, achievement points value, gender id and class id.

Optional Fields

This section contains a list of the optional fields that can be requested through the mentioned "fields" query string parameter.

guild

A summary of the guild that the character belongs to. If the character does not belong to a guild and this field is requested, this field will not be exposed.

stats

A map of character attributes and stats.

talents

A list of talent structures.

items

A list of items equipted by the character. Use of this field will also include the average item level and average item level equipped for the character.

reputation

A list of the factions that the character has an associated reputation with.

titles

A list of the titles obtained by the character.

professions

A list of the character's professions. It is important to note that when this information is retrieved, it will also include the known recipes of each of the listed professions.

appearance

A map of values that describes the face, features and helm/cloak display preferences and attributes.

companions

A list of all of the non-combat pets obtained by the character.

mounts

A list of all of the mounts obtained by the character.

pets

A list of all of the combat pets obtained by the character.

achievements

A map of achievement data including completion timestamps and criteria information.

progression

A list of raids and bosses indicating raid progression and completedness.

Example 2.2. An example Character Profile request with several addtional fields.

GET /api/wow/character/Medivh/Uther?fields=guild,items,professions,reputation,stats
Host: us.battle.net

guild

When a guild is requested, a map is returned with key/value pairs that describe a basic set of guild information. Note that the rank of the character is not included in this block as it describes a guild and not a membership of the guild. To retreive the character's rank within the guild, you must specific a seperate request to the guild profile resource.

Example 2.3. An example guild on Medivh

{
  "guild":{
    "name":"Roll the Dice",
    "realm":"Medivh",
    "level":25,
    "members":177,
    "achievementPoints":790,
    "emblem":{
      "icon":119,
      "iconColor":"ffffffb1",
      "border":-1,
      "borderColor":"ffffffff",
      "backgroundColor":"ffffff91"
    }
  }
}

items

When the items field is used, a map structure is returned that contains information on the equipped items of that character as well as the average item level of the character.

Example 2.4. An example items field

{
  "items":{
    "averageItemLevel":361,
    "averageItemLevelEquipped":359,
    "head":{
      "id":63531,
      "name":"Daybreaker Helm",
      "icon":"inv_helmet_plate_raiddeathknight_i_01",
      "quality":4,
      "tooltipParams":{
        "gem0":1813,
        "gem1":1762,
        "enchant":4206,
        "reforge":128
      }
    },
    "neck":{
      "id":59319,
      "name":"Ironstar Amulet",
      "icon":"inv_misc_necklacea3",
      "quality":4,
      "tooltipParams":{
        "reforge":140
      }
    },
    "shoulder":{
      "id":59901,
      "name":"Heaving Plates of Protection",
      "icon":"inv_shoulder_92",
      "quality":4,
      "tooltipParams":{
        "gem0":1785,
        "enchant":4198,
        "reforge":128
      }
    },
    "back":{
      "id":62383,
      "name":"Wrap of the Great Turtle",
      "icon":"inv_misc_cape_cataclysm_tank_d_01",
      "quality":4,
      "tooltipParams":{
        "enchant":4090
      }
    },
    "chest":{
      "id":60354,
      "name":"Reinforced Sapphirium Chestguard",
      "icon":"inv_chest_plate_raidpaladin_i_01",
      "quality":4,
      "tooltipParams":{
        "gem0":1758,
        "gem1":1785,
        "enchant":4070,
        "set":[
          60355,
          60357,
          60354
        ],
        "reforge":128
      }
    },
    "tabard":{
      "id":5976,
      "name":"Guild Tabard",
      "icon":"inv_shirt_guildtabard_01",
      "quality":1,
      "tooltipParams":{

      }
    },
    "wrist":{
      "id":62449,
      "name":"Sandguard Bracers",
      "icon":"inv_bracer_plate_raidwarrior_i_01",
      "quality":4,
      "tooltipParams":{
        "gem0":1774,
        "enchant":4086,
        "extraSocket":true,
        "reforge":161
      }
    },
    "hands":{
      "id":60355,
      "name":"Reinforced Sapphirium Handguards",
      "icon":"inv_gauntlets_plate_raidpaladin_i_01",
      "quality":4,
      "tooltipParams":{
        "gem0":1800,
        "gem1":1774,
        "enchant":4061,
        "set":[
          60355,
          60357,
          60354
        ],
        "extraSocket":true,
        "reforge":128
      }
    },
    "waist":{
      "id":63491,
      "name":"Thunder Wall Belt of the Rockslab",
      "icon":"inv_belt_plate_raidwarrior_i_01",
      "quality":4,
      "tooltipParams":{
        "gem0":1758,
        "gem1":1808,
        "suffix":-209,
        "extraSocket":true
      }
    },
    "legs":{
      "id":60357,
      "name":"Reinforced Sapphirium Legguards",
      "icon":"inv_pants_plate_raidpaladin_i_01",
      "quality":4,
      "tooltipParams":{
        "gem0":1758,
        "gem1":1774,
        "enchant":4124,
        "set":[
          60355,
          60357,
          60354
        ],
        "reforge":133
      }
    },
    "feet":{
      "id":65075,
      "name":"Massacre Treads",
      "icon":"inv_boots_raidwarrior_i_01",
      "quality":4,
      "tooltipParams":{
        "gem0":1774,
        "enchant":4094
      }
    },
    "finger1":{
      "id":63489,
      "name":"Permafrost Signet of the Bedrock",
      "icon":"inv_jewelry_ring_86",
      "quality":4,
      "tooltipParams":{
        "suffix":-125,
        "seed":1977024874,
        "reforge":128
      }
    },
    "finger2":{
      "id":58187,
      "name":"Ring of the Battle Anthem",
      "icon":"inv_jewelry_ring_82",
      "quality":4,
      "tooltipParams":{

      }
    },
    "trinket1":{
      "id":62471,
      "name":"Mirror of Broken Images",
      "icon":"inv_misc_platnumdisks",
      "quality":4,
      "tooltipParams":{

      }
    },
    "trinket2":{
      "id":59515,
      "name":"Vial of Stolen Memories",
      "icon":"inv_misc_cat_trinket02",
      "quality":4,
      "tooltipParams":{

      }
    },
    "mainHand":{
      "id":59347,
      "name":"Mace of Acrid Death",
      "icon":"inv_mace_1h_bwdraid_d_01",
      "quality":4,
      "tooltipParams":{
        "enchant":4098,
        "reforge":128
      }
    },
    "offHand":{
      "id":67145,
      "name":"Blockade's Lost Shield",
      "icon":"inv_shield_grimbatolraid_d_01",
      "quality":4,
      "tooltipParams":{
        "enchant":4085,
        "reforge":128
      }
    },
    "ranged":{
      "id":64676,
      "name":"Relic of Khaz'goroth",
      "icon":"inv_misc_stonetablet_03",
      "quality":4,
      "tooltipParams":{
        "gem0":1808
      }
    }
  }
}

stats

Example 2.5. An example stats field

{
  "stats":{
    "health":155263,
    "powerType":"mana",
    "power":24732,
    "str":3395,
    "agi":142,
    "sta":8017,
    "int":106,
    "spr":117,
    "attackPower":7025,
    "rangedAttackPower":0,
    "mastery":23.26104,
    "masteryRating":2736,
    "crit":1.351225,
    "critRating":0,
    "hitRating":58,
    "hasteRating":0,
    "expertiseRating":238,
    "spellPower":2133,
    "spellPen":0,
    "spellCrit":3.498852,
    "spellCritRating":0,
    "mana5":1191.0,
    "mana5Combat":1170.0,
    "armor":36505,
    "dodge":12.206712,
    "dodgeRating":1565,
    "parry":13.33957,
    "parryRating":1614,
    "block":57.335938,
    "blockRating":0,
    "resil":0,
    "mainHandDmgMin":2146.0,
    "mainHandDmgMax":2868.0,
    "mainHandSpeed":2.6,
    "mainHandDps":964.1704,
    "mainHandExpertise":10,
    "offHandDmgMin":0.0,
    "offHandDmgMax":0.0,
    "offHandSpeed":2.0,
    "offHandDps":0.0,
    "offHandExpertise":7,
    "rangedDmgMin":-1.0,
    "rangedDmgMax":-1.0,
    "rangedSpeed":-1.0,
    "rangedDps":-1.0,
    "rangedCrit":1.351225,
    "rangedCritRating":0,
    "rangedHitRating":58
  }
}

talents

Example 2.6. An example talents field

{
  "talents":[
    {
      "selected":true,
      "name":"Protection",
      "icon":"ability_paladin_shieldofthetemplar",
      "build":"000000000000000000003222300312110112123103203200000000000000",
      "trees":[
        {
          "points":"00000000000000000000",
          "total":0
        },
        {
          "points":"32223003121101121231",
          "total":31
        },
        {
          "points":"03203200000000000000",
          "total":10
        }
      ],
      "glyphs":{
        "prime":[
          {
            "glyph":195,
            "item":41105,
            "name":"Glyph of Word of Glory",
            "icon":"inv_helmet_96"
          },
          {
            "glyph":704,
            "item":45744,
            "name":"Glyph of Shield of the Righteous",
            "icon":"ability_paladin_shieldofvengeance"
          },
          {
            "glyph":561,
            "item":43869,
            "name":"Glyph of Seal of Truth",
            "icon":"spell_holy_sealofvengeance"
          }
        ],
        "major":[
          {
            "glyph":197,
            "item":41107,
            "name":"Glyph of the Ascetic Crusader",
            "icon":"spell_holy_crusaderstrike"
          },
          {
            "glyph":559,
            "item":43867,
            "name":"Glyph of Holy Wrath",
            "icon":"spell_holy_purifyingpower"
          },
          {
            "glyph":189,
            "item":41099,
            "name":"Glyph of Consecration",
            "icon":"spell_holy_innerfire"
          }
        ],
        "minor":[
          {
            "glyph":456,
            "item":43368,
            "name":"Glyph of Truth",
            "icon":"spell_holy_sealofvengeance"
          },
          {
            "glyph":453,
            "item":43340,
            "name":"Glyph of Blessing of Might",
            "icon":"spell_holy_greaterblessingofkings"
          },
          {
            "glyph":454,
            "item":43366,
            "name":"Glyph of Insight",
            "icon":"spell_holy_healingaura"
          }
        ]
      }
    },
    {
      "name":"Protection",
      "icon":"ability_paladin_shieldofthetemplar",
      "build":"002000000000000000003202302312212110123103202000000000000000",
      "trees":[
        {
          "points":"00200000000000000000",
          "total":2
        },
        {
          "points":"32023023122121101231",
          "total":32
        },
        {
          "points":"03202000000000000000",
          "total":7
        }
      ],
      "glyphs":{
        "prime":[
          {
            "glyph":704,
            "item":45744,
            "name":"Glyph of Shield of the Righteous",
            "icon":"ability_paladin_shieldofvengeance"
          },
          {
            "glyph":183,
            "item":41092,
            "name":"Glyph of Judgement",
            "icon":"spell_holy_righteousfury"
          },
          {
            "glyph":702,
            "item":45742,
            "name":"Glyph of Hammer of the Righteous",
            "icon":"ability_paladin_hammeroftherighteous"
          }
        ],
        "major":[
          {
            "glyph":559,
            "item":43867,
            "name":"Glyph of Holy Wrath",
            "icon":"spell_holy_purifyingpower"
          },
          {
            "glyph":189,
            "item":41099,
            "name":"Glyph of Consecration",
            "icon":"spell_holy_innerfire"
          },
          {
            "glyph":560,
            "item":43868,
            "name":"Glyph of Dazing Shield",
            "icon":"spell_holy_avengersshield"
          }
        ],
        "minor":[
          {
            "glyph":454,
            "item":43366,
            "name":"Glyph of Insight",
            "icon":"spell_holy_healingaura"
          },
          {
            "glyph":456,
            "item":43368,
            "name":"Glyph of Truth",
            "icon":"spell_holy_sealofvengeance"
          },
          {
            "glyph":190,
            "item":41100,
            "name":"Glyph of Righteousness",
            "icon":"spell_holy_righteousnessaura"
          }
        ]
      }
    }
  ]
}

reputation

Example 2.7. An example reputation field

{
  "reputation":[
    {
      "id":369,
      "name":"Gadgetzan",
      "standing":5,
      "value":10740,
      "max":12000
    },
    {
      "id":576,
      "name":"Timbermaw Hold",
      "standing":7,
      "value":572,
      "max":999
    },
    {
      "id":470,
      "name":"Ratchet",
      "standing":5,
      "value":10501,
      "max":12000
    },
    {
      "id":59,
      "name":"Thorium Brotherhood",
      "standing":7,
      "value":240,
      "max":999
    },
    {
      "id":1050,
      "name":"Valiance Expedition",
      "standing":7,
      "value":999,
      "max":999
    }
  ]
}

titles

Example 2.8. An example titles field

{
  "titles":[
    {
      "id":62,
      "name":"Merciless Gladiator %s"
    },
    {
      "id":79,
      "name":"%s the Diplomat"
    },
    {
      "id":72,
      "name":"Battlemaster %s"
    },
    {
      "id":48,
      "name":"Justicar %s",
      "selected":true
    },
    {
      "id":80,
      "name":"Brutal Gladiator %s"
    },
    {
      "id":53,
      "name":"%s, Champion of the Naaru"
    },
    {
      "id":78,
      "name":"%s the Explorer"
    },
    {
      "id":42,
      "name":"Gladiator %s"
    },
    {
      "id":83,
      "name":"Salty %s"
    },
    {
      "id":90,
      "name":"%s the Malefic"
    }
  ]
}

professions

Example 2.9. An example professions field

{
  "professions":{
    "primary":[
      {
        "id":755,
        "name":"Jewelcrafting",
        "icon":"inv_misc_gem_01",
        "rank":525,
        "max":525,
        "recipes":[
          25255,
          25278,
          25280,
          25283,
          25284,
          25287
        ]
      },
      {
        "id":164,
        "name":"Blacksmithing",
        "icon":"trade_blacksmithing",
        "rank":525,
        "max":525,
        "recipes":[
          2660,
          2661,
          2662,
          2663,
          2664
        ]
      }
    ],
    "secondary":[
      {
        "id":129,
        "name":"First Aid",
        "icon":"spell_holy_sealofsacrifice",
        "rank":525,
        "max":525,
        "recipes":[
          3275,
          3276,
          3277,
          3278,
          7928
        ]
      },
      {
        "id":794,
        "name":"Archaeology",
        "icon":"trade_archaeology",
        "rank":406,
        "max":450,
        "recipes":[ ]
      },
      {
        "id":356,
        "name":"Fishing",
        "icon":"trade_fishing",
        "rank":492,
        "max":525,
        "recipes":[ ]
      },
      {
        "id":185,
        "name":"Cooking",
        "icon":"inv_misc_food_15",
        "rank":525,
        "max":525,
        "recipes":[
          2538,
          2539,
          2540,
          2541,
          2542
        ]
      }
    ]
  }
}

appearance

Example 2.10. An example appearance field

{
  "appearance":{
    "faceVariation":2,
    "skinColor":0,
    "hairVariation":1,
    "hairColor":8,
    "featureVariation":2,
    "showHelm":true,
    "showCloak":true
  }
}

companions

Example 2.11. An example companions field

{
  "companions":[
    4055,
    10673,
    10674,
    10676,
    10677
  ]
}

mounts

Example 2.12. An example mounts field

{
  "mounts":[
    30174
  ]
}

pets

Example 2.13. An example pets field

{
  "pets":[
    {
      "name":"Wolf",
      "creature":17280,
      "selected":true,
      "slot":0
    },
    {
      "name":"Bear",
      "creature":29319,
      "slot":8
    },
    {
      "name":"Kat",
      "creature":28404,
      "slot":7
    },
    {
      "name":"Cat",
      "creature":2071,
      "slot":6
    }
  ]
}

achievements

NKG: To document

progression

NKG: To document

Guild Resources

Guild APIs currently provide guild profile information.

Profile API

The guild profile API is the primary way to access guild information. This guild profile API can be used to fetch a single guild at a time through an HTTP GET request to a url describing the guild profile resource. By default, a basic dataset will be returned and with each request and zero or more additional fields can be retrieved. To access this API, craft a resource URL pointing to the guild whos information is to be retrieved.

URL = Host + "/api/wow/guild/" + Realm + "/" + GuildName

Realm =  |

There are no required query string parameters when accessing this resource, although the "fields" query string parameter can optionally be passed to indicate that one or more of the optional datasets is to be retrieved. Those additional fields are listed in the subsection titled "Optional Fields".

Example 2.14. An example Guild Profile request and response.

GET /api/wow/guild/Medivh/Roll%20the%20Dice
Host: us.battle.net
HTTP/1.1 200 OK


{ "name":"Roll the Dice", "level":25, "side":"alliance", "achievementPoints":800 }

The core dataset returned includes the guild's name, level, faction and achievement points.

Optional Fields

This section contains a list of the optional fields that can be requested.

members

A list of characters that are a member of the guild

achievements

A set of data structures that describe the achievements earned by the guild.

Example 2.15. An example Guild Profile request with several addtional fields.

GET /api/wow/guild/Medivh/Roll%20the%20Dice?fields=achievements,members
Host: us.battle.net

members

When the members list is requrested, a list of character objects is returned. Each object in the returned members list contains a character block as well as a rank field.

Example 2.16. An example members block

  "members":[
    {
      "character":{
        "name":"Mequieres",
        "realm":"Medivh",
        "class":5,
        "race":1,
        "gender":"female",
        "level":85,
        "achievementPoints":6910,
        "thumbnail":"medivh/66/3930434-avatar.jpg"
      },
      "rank":1
    },
    {
      "character":{
        "name":"Berex",
        "realm":"Medivh",
        "class":2,
        "race":1,
        "gender":"male",
        "level":81,
        "achievementPoints":3410,
        "thumbnail":"medivh/159/3931551-avatar.jpg"
      },
      "rank":2
    },
    {
      "character":{
        "name":"Avalos",
        "realm":"Medivh",
        "class":2,
        "race":1,
        "gender":"male",
        "level":85,
        "achievementPoints":9755,
        "thumbnail":"medivh/2/4022530-avatar.jpg"
      },
      "rank":1
    },
    {
      "character":{
        "name":"Getafixes",
        "realm":"Medivh",
        "class":11,
        "race":4,
        "gender":"male",
        "level":85,
        "achievementPoints":7225,
        "thumbnail":"medivh/220/4064988-avatar.jpg"
      },
      "rank":7
    },
    {
      "character":{
        "name":"Thomaslv",
        "realm":"Medivh",
        "class":2,
        "race":1,
        "gender":"male",
        "level":85,
        "achievementPoints":5130,
        "thumbnail":"medivh/61/4090173-avatar.jpg"
      },
      "rank":6
    },
    {
      "character":{
        "name":"Jeanelly",
        "realm":"Medivh",
        "class":8,
        "race":7,
        "gender":"female",
        "level":85,
        "achievementPoints":9175,
        "thumbnail":"medivh/16/11635728-avatar.jpg"
      },
      "rank":3
    },
    {
      "character":{
        "name":"Shaynk",
        "realm":"Medivh",
        "class":4,
        "race":22,
        "gender":"male",
        "level":85,
        "achievementPoints":7005,
        "thumbnail":"medivh/13/11885837-avatar.jpg"
      },
      "rank":1
    },
    {
      "character":{
        "name":"Odette",
        "realm":"Medivh",
        "class":7,
        "race":11,
        "gender":"female",
        "level":85,
        "achievementPoints":3335,
        "thumbnail":"medivh/214/14322390-avatar.jpg"
      },
      "rank":8
    },
    {
      "character":{
        "name":"Addeon",
        "realm":"Medivh",
        "class":9,
        "race":7,
        "gender":"male",
        "level":85,
        "achievementPoints":4755,
        "thumbnail":"medivh/11/16220683-avatar.jpg"
      },
      "rank":3
    },
    {
      "character":{
        "name":"Tinkerton",
        "realm":"Medivh",
        "class":4,
        "race":7,
        "gender":"male",
        "level":85,
        "achievementPoints":7755,
        "thumbnail":"medivh/7/50893575-avatar.jpg"
      },
      "rank":3
    },
    {
      "character":{
        "name":"Itaachi",
        "realm":"Medivh",
        "class":8,
        "race":7,
        "gender":"female",
        "level":85,
        "achievementPoints":5975,
        "thumbnail":"medivh/154/74538650-avatar.jpg"
      },
      "rank":3
    },
    {
      "character":{
        "name":"Korale",
        "realm":"Medivh",
        "class":5,
        "race":22,
        "gender":"male",
        "level":85,
        "achievementPoints":5620,
        "thumbnail":"medivh/88/81679704-avatar.jpg"
      },
      "rank":7
    }
  ]

achievements

When requesting achievement data, several sets of data will be returned.

achievementsCompleted

A list of achievement ids.

achievementsCompletedTimestamp

A list of timestamps whose places corrospond to the achievement ids in the "achievementsCompleted" list. The value of each timestamp indicates when the related achievement was earned by the guild.

criteria

A list of criteria ids that can be used to determine the partial completedness of guild achievements.

criteriaQuantity

A list of values associated with a given achievement criteria. The position of a value corrosponds to the position of a given achivement criteria.

criteriaTimestamp

A list of timestamps where the value represents when the criteria was considered complete. The position of a value corrosponds to the position of a given achivement criteria.

criteriaCreated

A list of timestamps where the value represents when the criteria was considered started. The position of a value corrosponds to the position of a given achivement criteria.

Example 2.17. An example achievements block

"achievements":{
    "achievementsCompleted":[4860,4861,4912,4913,4943],
    "achievementsCompletedTimestamp":[1305087854000,1292834684000,1307514307000,1296629625000,1292837842000],
    "criteria":[13756,13757,13835,13864,13865],
    "criteriaQuantity":[25,500300151,1,525,525],
    "criteriaTimestamp":[1307514307000,1296629625000,1292834684000,1292744289000,1293154824000],
    "criteriaCreated":[1291708917000,1291716646000,1292834684000,1292573188000,1292728137000]
  }

Realm Resources

Realm APIs currently provide realm status information.

Realm Status

The realm status API allows developers to retrieve realm status information. This information is limited to whether or not the realm is up, the type and state of the realm and the current population.

URL = Host + "/api/wow/realm/status"

There are no required query string parameters when accessing this resource, although the "realms" query string parameter can optionally be passed to limit the realms returned to one or more.

Example 2.18. An example Realm Status request and response

GET /api/wow/realm/status?realms=Medivh,Lightbringer HTTP/1.1
Host: us.battle.net

HTTP/1.1 200 OK


{
  "realms":[
    {
      "type":"pve",
      "queue":false,
      "status":true,
      "population":"high",
      "name":"Lightbringer",
      "slug":"lightbringer"
    },
    {
      "type":"pve",
      "queue":false,
      "status":true,
      "population":"medium",
      "name":"Medivh",
      "slug":"medivh"
    }
  ]
}

Data Resources

The data APIs provide information that can compliment profile information to provide structure, definition and context.

Character Races

The character races data API provides a list of character races.

URL = Host + "/api/wow/data/character/races"

Character Classes

The character classes data API provides a list of character classes.

URL = Host + "/api/wow/data/character/classes"

Guild Rewards

The guild rewards data API provides a list of all guild rewards.

URL = Host + "/api/wow/data/guild/rewards"

Guild Perks

The guild perks data API provides a list of all guild perks.

URL = Host + "/api/wow/data/guild/perks"

Items

The items data API provides detailed item information.

URL = Host + "/api/wow/data/item/" + ItemId

Example 2.19. An example Item Data API request and response

GET /api/wow/data/item/38268 HTTP/1.1
Host: us.battle.net

HTTP/1.1 200 OK


{
  "id":38268,
  "disenchantingSkillRank":-1,
  "description":"Give to a Friend",
  "name":"Spare Hand",
  "stackable":1,
  "itemBind":{
    "id":0
  },
  "bonusStats":[],
  "itemSpells":[],
  "buyPrice":12,
  "itemClass":{
    "class":2,
    "name":"Weapon"
  },
  "itemSubClass":{
    "subclassId":14,
    "name":"Miscellaneous"
  },
  "containerSlots":0,
  "weaponInfo":{
    "damage":[
      {
        "minDamage":1,
        "maxDamage":2
      }
    ],
    "weaponSpeed":2.5,
    "dps":0.6
  },
  "inventoryType":13,
  "equippable":true,
  "itemLevel":1,
  "maxCount":0,
  "maxDurability":16,
  "minFactionId":0,
  "minReputation":0,
  "quality":0,
  "sellPrice":2,
  "requiredLevel":70,
  "requiredSkill":0,
  "requiredSkillRank":0,
  "itemSource":{
    "sourceId":0,
    "sourceType":"NONE"
  },
  "baseArmor":0,
  "hasSockets":false,
  "isAuctionable":true
}

Chapter 3. API Policy

The final policy document is being reviewed and will be published at a later date.

Chapter 4. Frequently Asked Questions

4.1.1. Is there an official library or reference implementation provided with these web APIs?
4.1.2. What about XML/Atom/JSONP/Other data forms?
4.1.3. How are realm names normalized?
4.1.1. Is there an official library or reference implementation provided with these web APIs?
4.1.2. What about XML/Atom/JSONP/Other data forms?
4.1.3. How are realm names normalized?

4.1.1.

Is there an official library or reference implementation provided with these web APIs?

No, Blizzard Entertainment has not released an officially support client library to consume the web APIs. There are a number of unofficial libraries that follow the spec provided by this documentation. You are not limited to or forced to use one of the libraries below and can create your own.

Python

https://github.com/vishnevskiy/battlenet

4.1.2.

What about XML/Atom/JSONP/Other data forms?

We decided to roll out JSON for numerous reasons. One of the main reasons is that it allows developers and website operators to easily embed requests that consume this date into their websites.

4.1.3.

How are realm names normalized?

Cord's answer goes here.