Character/Guild/Arena Team APIs Preview

(Locked)

Web & Mobile Team
As previously announced, we are planning to expand the Community Platform API with feeds for the 3 different types of profiles currently available on the website: characters, guilds, and arena teams. We’d like to share our current plans (may change, not a promise) with all of you as we look forward to providing a robust API that meets the needs of the community.

Each of the feeds below will be accessed by using a realm and name. The feeds will always contain basic information by default, and will have optional fields that can be requested via a parameter – making it possible to retrieve all the data in a single request. A locale parameter will also be available for localized strings. In addition, the feeds will support the Last-Modified HTTP header to help with caching. Just like with the realm status feed, region will be specified using the subdomain (e.g. eu.battle.net/api/.. for European realms).

Character
  • URL: /api/wow/character/{realm}/{name}
  • Basic information: name, level, class, race, gender, faction, guild, achievement points
  • Optional fields: equipped items, stats, reputation, primary and secondary skills, achievements/statistics, talents, titles, collected mounts and companions, quests, profession recipes, Hunter pets, PvP information

Guild
  • URL: /api/wow/guild/{realm}/{name}
  • Basic information: name, level, achievement points
  • Optional fields: members (roster), achievements

Arena Team
  • URL: /api/wow/arena/{realm}/{size}/{name} (size being 2v2, 3v3 or 5v5)
  • Basic information: name, ranking, rating, weekly/season statistics
  • Optional fields: members (roster)

Optional fields would be requested using the ‘fields’ parameter, where you specify everything you need using a comma-separated list. e.g:
/api/wow/character/realm-name/grotako?fields=items,talents,mounts,titles
Sample feeds will soon be provided as we’d also like feedback on the data format. In the meantime, let us know what you think!

p.s: We’ll have more details on the Auction House and Arena Ladder APIs to share in the coming weeks.
Edited by Grotako on 5/14/2011 11:26 PM PDT
MVP
58 Blood Elf Death Knight
500
Pretty cool stuff, Grotako, thanks! I do have a question though, for example... Something like..
/api/wow/character/black-dragonflight/sixen

Would just show what you have listed as "basic information," it would not include all optional fields as well, unless we specify all optional fields?

And I have to say that I enjoyed seeing the Page not Found error, :P.
{"status":"nok", "reason": "When in doubt, blow it up. (page not found)"}
________________________________________________
The Chat Gem Lives!
Fansite Administrator: DiabloFans, SC2Mapster, SC2Replayed
Edited by Sixen on 5/10/2011 7:56 PM PDT
Guild news would be awesome: boss kills, loot claims. Guild raid progress all wrapped up neatly without needing to piece it together would be even more awesome. Something like:

{"Blackwing Descent": ["Magmaw", "Omnotron Defense System", "Chimaeron"]}
85 Draenei Mage
10630
I for one would like it so that the api for gear would be less of a garble mess on the back-end instead of working backwards on figuring out what each variable represents. For example Power Generator Hood, you have to work backwards in figuring out that the gem slot "g0" is the meta gem and "g1" is the non-meta gem. I'm just saying that some of the enchant/gemming information for gear is convoluted in trying to figure out. The one that gets me are the random enchants. It took me forever and a day to figure out what variable says what random enchant is associated. Even then, I've still have yet to match up all of the random enchants, with their associated number.

Would it be better in saying variable "g0" for Power Generator Hood be renamed to "meta_gem" or something along those lines?
Edited by Delritha on 5/10/2011 9:03 PM PDT
80 Blood Elf Death Knight
4175
I would like to see a sample output too, but as far as I see it seems pretty cool to me that you've used restful to do this kind of stuff not sure if it exists but maybe you can create one more service to get the items, like:

/api/wow/item/{itemId}

The optional fields for the already posted services is a cool option but maybe it will be cool that you can also do something like :
/api/wow/guild/{realm}/{name}/teams
/api/wow/guild/{realm}/{name}/talents
/api/wow/guild/{realm}/{name}/achievements
etc..
Just to have an alternative way to do the stuff...

Anyway the current proposal you guys are working on is great.
1 Troll Rogue
0
Looks great! Very glad to see mounts and pets added to the list as well. Thanks for sharing, can't wait to try it out!

I don't want to be a "give an inch and they'll take a mile" guy, so I offer this suggestion humbly with hat in hand: perhaps completed quest IDs, too? Maybe not right away, but I know many a budding loremaster who might want a web interface to see what they've missed.

Even if quests don't make it in, I'm very happy with how things are developing. You folks got the message.
85 Human Rogue
6285
Very awesome news! Can't wait to see the examples and see these rolled out to the supported API feeds. Can't wait to start playing around with all the new, shiny feeds. All I ask is to try and make the usage guidelines available at the same time so us devs don't have to backtrack through code to comply with guidelines that are set after we've already started coding. Thanks!
85 Dwarf Warrior
12115
Sounds very cool. Can't wait to get a look at the data.
Web & Mobile Team
05/10/2011 07:55 PMPosted by Sixen
And I have to say that I enjoyed seeing the Page not Found error, :P.


Haha, thanks!
Edited by Straton on 5/11/2011 9:17 AM PDT
Web & Mobile Team
Regarding quest ids, this is something we are very interested in doing. We are still working out the details of how and when, but we'd like to provide a general list of what quests have been completed.
Edited by Straton on 5/11/2011 9:18 AM PDT
Web & Mobile Team
Pretty cool stuff, Grotako, thanks! I do have a question though, for example... Something like..
/api/wow/character/black-dragonflight/sixen

Would just show what you have listed as "basic information," it would not include all optional fields as well, unless we specify all optional fields?


That's correct. Optional fields aren't returned unless requested.
Edited by Grotako on 5/11/2011 10:18 AM PDT
90 Blood Elf Paladin
11425
Fantastic! Thanks for the preview.

Will there be a published list of all the optional fields that we can query for?

Also please sticky this thread. :)
Edited by Darque on 5/11/2011 10:49 AM PDT
88 Blood Elf Paladin
12595
Hopefully the data will be provided as a JSON stream, instead of XML or something heavier.

90 Dwarf Hunter
14750
This sounds very promising- I can't wait to switch over my armory import to this (just the other day I had to make another fix to get around some html changes in glyph and profession formatting).

Will the talent list include both the primary and secondary talents? I assume glyphs are included?
MVP
58 Blood Elf Death Knight
500
Pretty cool stuff, Grotako, thanks! I do have a question though, for example... Something like..
/api/wow/character/black-dragonflight/sixen

Would just show what you have listed as "basic information," it would not include all optional fields as well, unless we specify all optional fields?


That's correct. Optional fields aren't returned unless requested.

On that note, would it possible to implement something like the following?
/api/wow/character/black-dragonflight/sixen?fields=all
________________________________________________
The Chat Gem Lives!
Fansite Administrator: DiabloFans, SC2Mapster, SC2Replayed
29 Blood Elf Mage
720

Character
  • URL: /api/wow/character/{realm}/{name}
  • Basic information: name, level, class, race, gender, faction, guild, achievement points
  • Optional fields: equipped items, stats, reputation, primary and secondary skills, achievements/statistics, talents, titles, collected mounts and companions, quests, profession recipes, Hunter pets, PvP information


Optional fields would be requested using the ‘fields’ parameter, where you specify everything you need using a comma-separated list. e.g:
/api/wow/character/realm-name/grotako?fields=items,talents,mounts,titles
Sample feeds will soon be provided as we’d also like feedback on the data format. In the meantime, let us know what you think!


This seems very likely to save everyone a lot of bandwidth and compute time, so nice work! I'm definitely looking forward to it.

I wrote a prototype converter that fetches characters from the armory (just the "advanced" page) and turns that into the basic information outlined above. If you are testing new JSON aware code for the Community Platform API please feel free to use it. As we get more details I'll try to keep it's output up to date with what we will eventually see from battle.net.

It's basically a one way XHTML->JSON proxy for us.battle.net hosted characters.
http://json-from-xml.appspot.com/

As you're interested in a character that's currently accessible on us.battle.net you should be able to see what their "basic" JSON would look like.

Take "Deathnerd @ Tichondrius" for example. The Armory URL for them is:
http://us.battle.net/wow/en/character/tichondrius/deathnerd/
so, the JSON view of them would be:
http://json-from-xml.appspot.com/api/wow/character/tichondrius/deathnerd

UPDATE May 12th, at 1:30 Eastern.
The JSON had an extra "," and was invalid, it's been fixed up. (thanks to http://www.jsonlint.com/)
A couple of keys had typos as well, and they have similarly been fixed.
Other than gender all of the basic information is in the response.
Is there some way to get gender from the existing XHTML pages?
Edited by Meed on 5/12/2011 10:29 AM PDT
7 Worgen Druid
0
How much precision will be supported when fetching small pieces of data?

If we only want to know one piece of statistics information, say the number of "Quests Completed" will we be able to specify that we only want that information and receive a response that is limited to the basic information and just that one data point?

or, will we be specifying ?fields=statistics and getting back *all* the character stats at which point we can pull out the "Quests Completed" stat that we're interested in?

There is no doubt a point of diminishing returns where it doesn't make sense for the API queries to return teensy tiny data elements that are more expensive for the server to find than they are to send but do you know yet where that point will be?

I'm curious about achievement data in particular as that is the vast, vast majority of data in a character. How specific can we get?

The difference in the amount of data returned by an "all" achievement data
?fields=achievements

versus a sub-section:
?fields=achievements-professions

or an individual achievement:
?fields=achievement-a735

could be quite significant in terms of volume of data returned.

This topic is locked.

Please report any Code of Conduct violations, including:

Threats of violence. We take these seriously and will alert the proper authorities.

Posts containing personal information about other players. This includes physical addresses, e-mail addresses, phone numbers, and inappropriate photos and/or videos.

Harassing or discriminatory language. This will not be tolerated.

Forums Code of Conduct

Report Post # written by

Reason
Explain (256 characters max)
Submit Cancel

Reported!

[Close]