8/15/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.
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.
Table of Contents
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.
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.
The character and guild API resources do honor HTTP requests that contain the "If-Modified-Since" header.
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 headers>
HTTP/1.1 200 OK
<http headers>
{"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.
All of the API resources provided adhere to the practice of
providing localized strings using the locale query string
parameter. The locales supported vary from region to region and align
with those supported on the community sites.
en_US
es_MX
en_GB
es_ES
fr_FR
ru_RU
de_DE
ko_KR
zh_TW
zh_CN
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.
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.
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 <api-support@blizzard.com> 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.
To authenticate a request, simple include the "Authorization" header with your application identifier and the request signature.
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:BNETc1fbf21b79c03191d:+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 = <HTTP-Request-URI, from the port to the query string>
StringToSign = HTTP-Verb + "\n" +
Date + "\n" +
UrlPath + "\n";
Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( PrivateKey, StringToSign ) ) );
Header = "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 ) );
Header = "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 180 seconds of the current GMT time.
We strongly advise that client library developers make secure requests using SSL whenever application authentication is used.
Data returned in the response message is provided in JSON format. Please refer to the examples provided with each API section for additional information.
Although several of the API resources have specific error responses that correspond 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.
HTTP Response Code: 500
A request was made including application identification information, but either the application key is invalid or missing.
HTTP Response Code: 500
A request was made to an API resource that requires a higher application permission level.
HTTP Response Code: 500
The application or IP address has been blocked from making further requests. This ban may not be permanent.
HTTP Response Code: 404
A request was made to a resource that doesn't exist.
HTTP Response Code: 500
The application or IP has been throttled.
HTTP Response Code: 500
There was a server error or equally catastrophic exception preventing the request from being fulfilled.
HTTP Response Code: 500
The application authorization information was mallformed or missing when expected.
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 headers>
HTTP/1.1 404 Not Found
<http headers>
{"status":"nok", "reason": "When in doubt, blow it up. (page not found)"}
For questions about the API, please use the Community Platform API forums as a platform to ask questions and get help.
You can also email <api-support@blizzard.com> for
matters that you may not want public discussion for.
Table of Contents
Character APIs currently provide character profile information.
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 = <proper realm name> | <normalized realm name>
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
<http headers>
{"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.
This section contains a list of the optional fields that can
be requested through the mentioned "fields" query
string parameter.
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.
A map of character attributes and stats.
A list of talent structures.
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.
A list of the factions that the character has an associated reputation with.
A list of the titles obtained by the character including the currently selected title.
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.
A map of values that describes the face, features and helm/cloak display preferences and attributes.
A list of all of the non-combat pets obtained by the character.
A list of all of the mounts obtained by the character.
A list of all of the combat pets obtained by the character.
A map of achievement data including completion timestamps and criteria information.
A list of raids and bosses indicating raid progression and completedness.
A map of pvp information including arena team membership and rated battlegrounds information.
A list of quests completed by the character.
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
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 field
{
"guild":{
"name":"Knights of the Silver Hand",
"realm":"Medivh",
"level":25,
"members":50,
"achievementPoints":7500,
"emblem":{
"icon":119,
"iconColor":"ffb1b8b1",
"border":0,
"borderColor":"ffffffff",
"backgroundColor":"ff006391"
}
}
}
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" : 353,
"averageItemLevelEquipped" : 335,
"back" : { "icon" : "inv_misc_cape_naxxramas_01",
"id" : 56450,
"name" : "Azureborne Cloak",
"quality" : 3,
"tooltipParams" : { }
},
"chest" : { "icon" : "inv_chest_robe_pvppriest_c_01",
"id" : 60476,
"name" : "Vicious Gladiator's Satin Robe",
"quality" : 4,
"tooltipParams" : { "enchant" : 4077,
"gem0" : 52207,
"gem1" : 52226,
"set" : [ 60474,
60476,
60477,
60475,
60473
]
}
},
"feet" : { "icon" : "inv_boots_robe_dungeonrobe_c_03",
"id" : 63440,
"name" : "Boots of Lingering Sorrow",
"quality" : 3,
"tooltipParams" : { "gem0" : 52117 }
},
"finger1" : { "icon" : "inv_jewelry_ring_68",
"id" : 56333,
"name" : "Rose Quartz Band",
"quality" : 3,
"tooltipParams" : { }
},
"finger2" : { "icon" : "inv_jewelry_ring_75",
"id" : 56418,
"name" : "Band of Life Energy",
"quality" : 3,
"tooltipParams" : { }
},
"hands" : { "icon" : "inv_gauntlets_robe_pvppriest_c_01",
"id" : 60473,
"name" : "Vicious Gladiator's Satin Gloves",
"quality" : 4,
"tooltipParams" : { "enchant" : 4068,
"gem0" : 52245,
"set" : [ 60474,
60476,
60477,
60475,
60473
]
}
},
"head" : { "icon" : "inv_helm_robe_pvppriest_c_01",
"id" : 60474,
"name" : "Vicious Gladiator's Satin Hood",
"quality" : 4,
"tooltipParams" : { "enchant" : 4207,
"gem0" : 52296,
"gem1" : 52207,
"set" : [ 60474,
60476,
60477,
60475,
60473
]
}
},
"legs" : { "icon" : "inv_pants_robe_pvppriest_c_01",
"id" : 60475,
"name" : "Vicious Gladiator's Satin Leggings",
"quality" : 4,
"tooltipParams" : { "enchant" : 4112,
"gem0" : 52207,
"gem1" : 52245,
"set" : [ 60474,
60476,
60477,
60475,
60473
]
}
},
"mainHand" : { "icon" : "inv_staff_13",
"id" : 65167,
"name" : "Emberstone Staff",
"quality" : 3,
"tooltipParams" : { }
},
"neck" : { "icon" : "inv_jewelry_necklace_44",
"id" : 70075,
"name" : "Bloodthirsty Amberjewel Pendant",
"quality" : 3,
"tooltipParams" : { }
},
"ranged" : { "icon" : "inv_wand_1h_cataclysm_b_01",
"id" : 63735,
"name" : "Darklight Torch",
"quality" : 2,
"tooltipParams" : { }
},
"shirt" : { "icon" : "inv_shirt_purple_01",
"id" : 45037,
"name" : "Epic Purple Shirt",
"quality" : 4,
"tooltipParams" : { }
},
"shoulder" : { "icon" : "inv_shoulder_robe_pvppriest_c_01",
"id" : 60477,
"name" : "Vicious Gladiator's Satin Mantle",
"quality" : 4,
"tooltipParams" : { "gem0" : 52226,
"set" : [ 60474,
60476,
60477,
60475,
60473
]
}
},
"tabard" : { "icon" : "inv_epicguildtabard",
"id" : 69210,
"name" : "Renowned Guild Tabard",
"quality" : 4,
"tooltipParams" : { }
},
"trinket1" : { "icon" : "spell_shadow_lifedrain",
"id" : 56351,
"name" : "Tear of Blood",
"quality" : 3,
"tooltipParams" : { }
},
"trinket2" : { "icon" : "inv_jewelry_trinketpvp_01",
"id" : 18862,
"name" : "Insignia of the Alliance",
"quality" : 3,
"tooltipParams" : { }
},
"waist" : { "icon" : "inv_belt_cloth_raidpriest_i_01",
"id" : 62386,
"name" : "Cord of the Raven Queen",
"quality" : 4,
"tooltipParams" : { "gem0" : 52244 }
},
"wrist" : { "icon" : "inv_bracer_cloth_pvpwarlock_c_01",
"id" : 60634,
"name" : "Vicious Gladiator's Cuffs of Prowess",
"quality" : 4,
"tooltipParams" : { }
}
} }
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
}
}
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"
}
]
}
}
]
}
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
}
]
}
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"
}
]
}
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
]
}
]
}
}
Example 2.10. An example appearance field
{
"appearance":{
"faceVariation":2,
"skinColor":0,
"hairVariation":1,
"hairColor":8,
"featureVariation":2,
"showHelm":true,
"showCloak":true
}
}
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
}
]
}
Example 2.14. An example achievements field
{
"achievements":{
"achievementsCompleted":[6,7,8,9,10],
"achievementsCompletedTimestamp":[1224283700000,1224283700000,1224283700000,1224283700000,1224283700000],
"criteria":[34,35,36,37,38],
"criteriaQuantity":[85,85,85,85,85],
"criteriaTimestamp":[1309580447000,1309580447000,1309580447000,1309580447000,1309580447000],
"criteriaCreated":[1309580447000,1309580447000,1309580447000,1309580447000,1309580447000]
}
}
Example 2.15. An example progression field
{
"progression":{
"raids":[
{
"name":"Molten Core",
"normal":2,
"heroic":0,
"id":2717,
"bosses":[
{
"name":"Ragnaros",
"normalKills":1,
"heroicKills":0,
"id":11502
}
]
},
{
"name":"Blackwing Lair",
"normal":0,
"heroic":0,
"id":2677,
"bosses":[
{
"name":"Nefarian",
"normalKills":0,
"heroicKills":0,
"id":11583
}
]
},
{
"name":"Ruins of Ahn'Qiraj",
"normal":2,
"heroic":0,
"id":3429,
"bosses":[
{
"name":"Ossirian the Unscarred",
"normalKills":-1,
"heroicKills":0,
"id":15339
}
]
},
{
"name":"Ahn'Qiraj Temple",
"normal":2,
"heroic":0,
"id":3428,
"bosses":[
{
"name":"C'Thun",
"normalKills":1,
"heroicKills":0,
"id":15727
}
]
},
{
"name":"Karazhan",
"normal":2,
"heroic":0,
"id":3457,
"bosses":[
{
"name":"Prince Malchezaar",
"normalKills":-1,
"heroicKills":0,
"id":15690
}
]
},
{
"name":"Magtheridon's Lair",
"normal":2,
"heroic":0,
"id":3836,
"bosses":[
{
"name":"Magtheridon",
"normalKills":-1,
"heroicKills":0,
"id":17257
}
]
},
{
"name":"Gruul's Lair",
"normal":2,
"heroic":0,
"id":3923,
"bosses":[
{
"name":"Gruul the Dragonkiller",
"normalKills":-1,
"heroicKills":0,
"id":19044
}
]
},
{
"name":"Serpentshrine Cavern",
"normal":2,
"heroic":0,
"id":3607,
"bosses":[
{
"name":"Lady Vashj",
"normalKills":-1,
"heroicKills":0,
"id":21212
}
]
},
{
"name":"Tempest Keep",
"normal":2,
"heroic":0,
"id":3845,
"bosses":[
{
"name":"Kael'thas Sunstrider",
"normalKills":2,
"heroicKills":0,
"id":19622
}
]
},
{
"name":"The Battle for Mount Hyjal",
"normal":0,
"heroic":0,
"id":3606,
"bosses":[
{
"name":"Archimonde",
"normalKills":0,
"heroicKills":0,
"id":17968
}
]
},
{
"name":"Black Temple",
"normal":2,
"heroic":0,
"id":3959,
"bosses":[
{
"name":"Illidan Stormrage",
"normalKills":1,
"heroicKills":0,
"id":22917
}
]
},
{
"name":"The Sunwell",
"normal":0,
"heroic":0,
"id":4075,
"bosses":[
{
"name":"Kil'jaeden",
"normalKills":0,
"heroicKills":0,
"id":25315
}
]
},
{
"name":"Vault of Archavon",
"normal":2,
"heroic":0,
"id":4603,
"bosses":[
{
"name":"Archavon the Stone Watcher",
"normalKills":8,
"heroicKills":0,
"id":31125
},
{
"name":"Emalon the Storm Watcher",
"normalKills":2,
"heroicKills":0,
"id":33993
},
{
"name":"Koralon the Flame Watcher",
"normalKills":5,
"heroicKills":0,
"id":35013
},
{
"name":"Toravon the Ice Watcher",
"normalKills":5,
"heroicKills":0,
"id":38433
}
]
},
{
"name":"Naxxramas",
"normal":2,
"heroic":0,
"id":3456,
"bosses":[
{
"name":"Anub'Rekhan",
"normalKills":9,
"heroicKills":0,
"id":15956
},
{
"name":"Grand Widow Faerlina",
"normalKills":6,
"heroicKills":0,
"id":15953
},
{
"name":"Maexxna",
"normalKills":7,
"heroicKills":0,
"id":15952
},
{
"name":"Patchwerk",
"normalKills":9,
"heroicKills":0,
"id":16028
},
{
"name":"Grobbulus",
"normalKills":8,
"heroicKills":0,
"id":15931
},
{
"name":"Gluth",
"normalKills":7,
"heroicKills":0,
"id":15932
},
{
"name":"Thaddius",
"normalKills":7,
"heroicKills":0,
"id":15928
},
{
"name":"Noth the Plaguebringer",
"normalKills":10,
"heroicKills":0,
"id":15954
},
{
"name":"Heigan the Unclean",
"normalKills":9,
"heroicKills":0,
"id":15936
},
{
"name":"Loatheb",
"normalKills":9,
"heroicKills":0,
"id":16011
},
{
"name":"Instructor Razuvious",
"normalKills":8,
"heroicKills":0,
"id":16061
},
{
"name":"Gothik the Harvester",
"normalKills":7,
"heroicKills":0,
"id":16060
},
{
"name":"The Four Horsemen",
"normalKills":7,
"heroicKills":0,
"id":59450
},
{
"name":"Sapphiron",
"normalKills":8,
"heroicKills":0,
"id":15989
},
{
"name":"Kel'Thuzad",
"normalKills":8,
"heroicKills":0,
"id":15990
}
]
},
{
"name":"The Obsidian Sanctum",
"normal":2,
"heroic":0,
"id":4493,
"bosses":[
{
"name":"Sartharion",
"normalKills":9,
"heroicKills":0,
"id":28860
}
]
},
{
"name":"The Eye of Eternity",
"normal":2,
"heroic":0,
"id":4500,
"bosses":[
{
"name":"Malygos",
"normalKills":9,
"heroicKills":0,
"id":28859
}
]
},
{
"name":"Ulduar",
"normal":1,
"heroic":0,
"id":4273,
"bosses":[
{
"name":"Flame Leviathan",
"normalKills":6,
"heroicKills":0,
"id":33113
},
{
"name":"Razorscale",
"normalKills":5,
"heroicKills":0,
"id":33186
},
{
"name":"XT-002 Deconstructor",
"normalKills":2,
"heroicKills":0,
"id":33293
},
{
"name":"Ignis the Furnace Master",
"normalKills":2,
"heroicKills":0,
"id":33118
},
{
"name":"Assembly of Iron",
"normalKills":0,
"heroicKills":0,
"id":65195
},
{
"name":"Kologarn",
"normalKills":0,
"heroicKills":0,
"id":32930
},
{
"name":"Auriaya",
"normalKills":1,
"heroicKills":0,
"id":33515
},
{
"name":"Hodir",
"normalKills":0,
"heroicKills":0,
"id":64899
},
{
"name":"Thorim",
"normalKills":0,
"heroicKills":0,
"id":64985
},
{
"name":"Freya",
"normalKills":0,
"heroicKills":0,
"id":65074
},
{
"name":"Leviathan Mk II",
"normalKills":0,
"heroicKills":0,
"id":33432
},
{
"name":"General Vezax",
"normalKills":0,
"heroicKills":0,
"id":33271
},
{
"name":"Yogg-Saron",
"normalKills":0,
"heroicKills":0,
"id":33288
},
{
"name":"Algalon the Observer",
"normalKills":0,
"heroicKills":0,
"id":65184
}
]
},
{
"name":"Onyxia's Lair",
"normal":2,
"heroic":0,
"id":2159,
"bosses":[
{
"name":"Onyxia",
"normalKills":4,
"heroicKills":0,
"id":10184
}
]
},
{
"name":"Trial of the Crusader",
"normal":2,
"heroic":1,
"id":4722,
"bosses":[
{
"name":"Icehowl",
"normalKills":6,
"heroicKills":3,
"id":34797
},
{
"name":"Lord Jaraxxus",
"normalKills":6,
"heroicKills":3,
"id":34780
},
{
"name":"Defeat the Faction Champions",
"normalKills":5,
"heroicKills":1,
"id":68184
},
{
"name":"Eydis Darkbane",
"normalKills":5,
"heroicKills":1,
"id":34496
},
{
"name":"Anub'arak",
"normalKills":5,
"heroicKills":0,
"id":34564
}
]
},
{
"name":"Icecrown Citadel",
"normal":2,
"heroic":0,
"id":4812,
"bosses":[
{
"name":"Lord Marrowgar",
"normalKills":18,
"heroicKills":0,
"id":36612
},
{
"name":"Lady Deathwhisper",
"normalKills":18,
"heroicKills":0,
"id":36855
},
{
"name":"Claim victory in the Gunship Battle",
"normalKills":18,
"heroicKills":0,
"id":72959
},
{
"name":"The Deathbringer",
"normalKills":16,
"heroicKills":0,
"id":72928
},
{
"name":"Festergut",
"normalKills":13,
"heroicKills":0,
"id":36626
},
{
"name":"Rotface",
"normalKills":11,
"heroicKills":0,
"id":36627
},
{
"name":"Professor Putricide",
"normalKills":6,
"heroicKills":0,
"id":36678
},
{
"name":"Prince Valanar",
"normalKills":9,
"heroicKills":0,
"id":37970
},
{
"name":"Blood-Queen Lana'thel",
"normalKills":5,
"heroicKills":0,
"id":37955
},
{
"name":"Rescue Valithria Dreamwalker",
"normalKills":4,
"heroicKills":0,
"id":72706
},
{
"name":"Sindragosa",
"normalKills":2,
"heroicKills":0,
"id":36853
},
{
"name":"The Lich King",
"normalKills":1,
"heroicKills":0,
"id":36597
}
]
},
{
"name":"The Ruby Sanctum",
"normal":0,
"heroic":0,
"id":4987,
"bosses":[
{
"name":"Halion",
"normalKills":0,
"heroicKills":0,
"id":39863
}
]
},
{
"name":"Baradin Hold",
"normal":0,
"heroic":0,
"id":5600,
"bosses":[
{
"name":"Argaloth",
"normalKills":0,
"heroicKills":0,
"id":47120
},
{
"name":"Occu'thar",
"normalKills":0,
"heroicKills":0,
"id":52363
}
]
},
{
"name":"Blackwing Descent",
"normal":0,
"heroic":0,
"id":5094,
"bosses":[
{
"name":"Magmaw",
"normalKills":0,
"heroicKills":0,
"id":41570
},
{
"name":"Toxitron",
"normalKills":0,
"heroicKills":0,
"id":42180
},
{
"name":"Maloriak",
"normalKills":0,
"heroicKills":0,
"id":41378
},
{
"name":"Atramedes",
"normalKills":0,
"heroicKills":0,
"id":41442
},
{
"name":"Chimaeron",
"normalKills":0,
"heroicKills":0,
"id":43296
},
{
"name":"Nefarian",
"normalKills":0,
"heroicKills":0,
"id":41376
}
]
},
{
"name":"The Bastion of Twilight",
"normal":0,
"heroic":0,
"id":5334,
"bosses":[
{
"name":"Halfus Wyrmbreaker",
"normalKills":0,
"heroicKills":0,
"id":44600
},
{
"name":"Valiona",
"normalKills":0,
"heroicKills":0,
"id":45992
},
{
"name":"Elementium Monstrosity",
"normalKills":0,
"heroicKills":0,
"id":43735
},
{
"name":"Cho'gall",
"normalKills":0,
"heroicKills":0,
"id":43324
},
{
"name":"Sinestra",
"normalKills":0,
"heroicKills":0,
"id":45213
}
]
},
{
"name":"Throne of the Four Winds",
"normal":0,
"heroic":0,
"id":5638,
"bosses":[
{
"name":"Conclave of Wind",
"normalKills":0,
"heroicKills":0,
"id":88835
},
{
"name":"Al'Akir",
"normalKills":0,
"heroicKills":0,
"id":46753
}
]
},
{
"name":"Firelands",
"normal":0,
"heroic":0,
"id":5723,
"bosses":[
{
"name":"Beth'tilac",
"normalKills":0,
"heroicKills":0,
"id":52498
},
{
"name":"Lord Rhyolith",
"normalKills":0,
"heroicKills":0,
"id":53772
},
{
"name":"Alysrazor",
"normalKills":0,
"heroicKills":0,
"id":52530
},
{
"name":"Shannox",
"normalKills":0,
"heroicKills":0,
"id":53691
},
{
"name":"Baleroc",
"normalKills":0,
"heroicKills":0,
"id":53494
},
{
"name":"Majordomo Staghelm",
"normalKills":0,
"heroicKills":0,
"id":52571
},
{
"name":"Ragnaros",
"normalKills":0,
"heroicKills":0,
"id":102237
},
{
"name":"Ragnaros",
"normalKills":0,
"heroicKills":0,
"id":52409
}
]
}
]
}
}
Example 2.16. An example pvp field
"pvp":{
"ratedBattlegrounds":{
"personalRating": 3100,
"battlegrounds":[
{
"name":"Arathi Basin",
"played":98745,
"won":98744
},
{
"name":"The Battle for Gilneas",
"played":0,
"won":0
},
{
"name":"Eye of the Storm",
"played":0,
"won":0
},
{
"name":"Strand of the Ancients",
"played":0,
"won":0
},
{
"name":"Twin Peaks",
"played":0,
"won":0
},
{
"name":"Warsong Gulch",
"played":0,
"won":0
}
]
},
"arenaTeams":[
{
"name":"Lordaeron's Defense",
"personalRating":2700,
"teamRating":2700,
"size":"5v5"
}
],
"totalHonorableKills":98475
}
Guild APIs currently provide guild profile information.
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 = <proper realm name> | <normalized realm name>
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.18. An example Guild Profile request and response.
GET /api/wow/guild/Medivh/Knights%20of%20the%20Silver%20Hand Host: us.battle.net
HTTP/1.1 200 OK
<http headers>
{ "name":"Knights of the Silver Hand", "level":25, "side":"alliance", "achievementPoints":800 }
The core dataset returned includes the guild's name, level, faction and achievement points.
This section contains a list of the optional fields that can be requested.
A list of characters that are a member of the guild
A set of data structures that describe the achievements earned by the guild.
Example 2.19. An example Guild Profile request with several addtional fields.
GET /api/wow/guild/Medivh/Knights%20of%20the%20Silver%20Hand?fields=achievements,members Host: us.battle.net
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.20. 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
}
]
When requesting achievement data, several sets of data will be returned.
A list of achievement ids.
A list of timestamps whose places correspond to the achievement ids in the "achievementsCompleted" list. The value of each timestamp indicates when the related achievement was earned by the guild.
A list of criteria ids that can be used to determine the partial completedness of guild achievements.
A list of values associated with a given achievement criteria. The position of a value corresponds to the position of a given achivement criteria.
A list of timestamps where the value represents when the criteria was considered complete. The position of a value corresponds to the position of a given achivement criteria.
A list of timestamps where the value represents when the criteria was considered started. The position of a value corresponds to the position of a given achivement criteria.
Example 2.21. 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 APIs currently provide realm status information.
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.22. An example Realm Status request and response
GET /api/wow/realm/status?realms=Medivh,Lightbringer HTTP/1.1 Host: us.battle.net <http headers>
HTTP/1.1 200 OK
<http headers>
{
"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"
}
]
}
Auction APIs currently provide rolling batches of data about current auctions. Fetching auction dumps is a two step process that involves checking a per-realm index file to determine if a recent dump has been generated and then fetching the most recently generated dump file if necessary.
This API resource provides a per-realm list of recently generated auction house data dumps.
URL = Host + "/api/wow/auction/data/" + realm
There are no required query string parameters when accessing this resource.
Example 2.23. An example Current Auctions request and response
GET /api/wow/auction/data/medivh HTTP/1.1 Host: us.battle.net <http headers>
HTTP/1.1 200 OK
<http headers>
{
"files":[
{
"url":"http://us.battle.net/auction-data/medivh/auctions-1311362443895.json.gz",
"lastModified":1311362443895
}
]
}
The current auctions data is represented as JSON structures containing auction data for the tree auctions houses available on each realm.
{
"realm": {
"name": "Medivh",
"slug": "medivh"
},
"alliance": {
"auctions": [
{
"auc": 500,
"item": 49284,
"owner": "Uther",
"bid": 150000,
"buyout": 450000,
"quantity": 11
}
]
},
"horde": {
"auctions": [
{
"auc": 501,
"item": 44575,
"owner": "Thrall",
"bid": 26751,
"buyout": 57665,
"quantity": 1
}
]
},
"neutral": {
"auctions": [
{
"auc": 502,
"item": 63271,
"owner": "Arthas",
"bid": 20000,
"buyout": 50000,
"quantity": 1
}
]
}
}
Item APIs currently provide item information.
The item API provides detailed item information.
URL = Host + "/api/wow/item/" + ItemId
Example 2.24. An example Item API request and response
GET /api/wow//item/38268 HTTP/1.1 Host: us.battle.net <http headers>
HTTP/1.1 200 OK
<http headers>
{
"id":38268,
"disenchantingSkillRank":-1,
"description":"Give to a Friend",
"name":"Spare Hand",
"stackable":1,
"itemBind": 0,
"bonusStats":[],
"itemSpells":[],
"buyPrice":12,
"itemClass": 2,
"itemSubClass": 14,
"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
}
PVP APIs currently provide arena team and ladder information.
The Arena Team API provides detailed arena team information.
TeamSize = "2v2" | "3v3" | "5v5" URL = Host + "/api/wow/arena/" + Realm + "/" + TeamSize + "/" + TeamName
Example 2.25. An example Arena Team API request and response
GET /api/wow/arena/bonechewer/2v2/Samurai%20Jack HTTP/1.1 Host: us.battle.net <http headers>
HTTP/1.1 200 OK
<http headers>
{
"realm": "Bonechewer",
"ranking":3,
"rating":2407,
"teamsize":2,
"created":"2010-12-14",
"name":"Samurai Jack",
"gamesPlayed":0,
"gamesWon":0,
"gamesLost":0,
"sessionGamesPlayed":84,
"sessionGamesWon":65,
"sessionGamesLost":19,
"lastSessionRanking":49,
"side":"horde",
"currentWeekRanking":3,
"members":[
{
"character":{
"name":"Enzi",
"realm":"Bonechewer",
"class":5,
"race":5,
"gender":0,
"level":85,
"achievementPoints":7825,
"thumbnail":"bonechewer/63/50019391-avatar.jpg"
},
"rank":1,
"gamesPlayed":0,
"gamesWon":0,
"gamesLost":0,
"sessionGamesPlayed":79,
"sessionGamesWon":61,
"sessionGamesLost":18,
"personalRating":2407
},
{
"character":{
"name":"Treeofapples",
"realm":"Bonechewer",
"class":11,
"race":6,
"gender":0,
"level":85,
"achievementPoints":4755,
"thumbnail":"bonechewer/31/56730399-avatar.jpg"
},
"rank":0,
"gamesPlayed":0,
"gamesWon":0,
"gamesLost":0,
"sessionGamesPlayed":84,
"sessionGamesWon":65,
"sessionGamesLost":19,
"personalRating":2407
}
]
}
The data APIs provide information that can compliment profile information to provide structure, definition and context.
The character races data API provides a list of character races.
URL = Host + "/api/wow/data/character/races"
The character classes data API provides a list of character classes.
URL = Host + "/api/wow/data/character/classes"
The guild rewards data API provides a list of all guild rewards.
URL = Host + "/api/wow/data/guild/rewards"
The guild perks data API provides a list of all guild perks.
URL = Host + "/api/wow/data/guild/perks"
The final policy document is being reviewed and will be published at a later date.