Diablo 3 API Preview

With the release of Diablo 3, we are working hard to make career and hero profiles available to the community. With career and hero profiles, we are excited to also release a set of API resources specific to Diablo 3 for community fansites and developers to consume. I’d like to take this opportunity to give a preview of the progress we’ve made to the community and open up discussions around what data will be available.

Please keep in mind that this is an early preview and there will likely be many changes to the D3 API by the time it is released. Also note that we haven’t finalized several key pieces of information including artisan recipes, hero and follower spells and powers and achievements.

Career Profile

The career profile API provides top level (account) career information. This API resource is meant to provide a way to discover the heroes associated with an account as well as the artisan and game progression information for the account. To use the career profile API resource, a URL containing a battletag is crafted and a request is made. An example request for the Battletag “Straton#1” would be:

/api/d3/account/Straton/1

The following data structure is then returned:

http://blizzard.github.com/d3-api-docs/#career-profile/career-profile-example

As you can see, there are several account specific data points to reference. The heroes attribute contains a list of all of the active heroes for the account. This list does not include fallen heroes. The artisans dataset includes a list of the artisans and the id, label, level and progression of each. Next are several progression attributes that can be used to determine the highest difficulty boss for each act. Last are several stats on the number of monsters and elites killed.

Hero Profile API

Hero profile API resources provide hero specific information including basic information like the name, class, gender and level as well as more complex information like follower information, hero statistics, active skills/powers and items. Unlike the career profile API resource, a hero id is used to craft a URL instead of a battletag. An example for hero 182 would be:

/api/d3/hero/1

The following data structure is then returned:

http://blizzard.github.com/d3-api-docs/#hero-profile/hero-profile-example

The first set of information provided includes the name, level and class information. Following that is a list of the hirelings the hero has unlocked. Lastly, a block of statistics is returned that includes stats, resistances and kills.

FAQ

Q: Will the AH have API access in a similar manner to WoW?

A: There are no plans to create an AH API (even read-only) for gold, hardcore gold or real money.

Q: What about achievements?

A: We do plan on providing all achievement information much like we do with the WoW API. The difference being that achievements are account bound.

Q: How will the request limits work? Is the "~3000" requests per day going to be shared between the D3 API and the WoW API?

A: The same as with the WoW API. The requests per-day limits will be shared between the APIs as most fansites and applications are game specific (with a few exceptions).

Q: Will you be implementing an API that is similar to the realm status API for WoW?

A: Yes. We will have an API resource that provides the status data as we do on http://us.battle.net/d3/en/status .

Q: Any plans for a search API? Any way we could crawl for accounts to do aggregate statistics?

A: We haven't really come up with a good way to provide an index that doesn't compromise privacy or data that we don't want to expose. This is something we are thinking about though.

Q: Any plans for giving us information about quest completion? Like how long it took them to clear a quest, perhaps including historical data if they've done a quest multiple times, and including party members involved in the kill?

A: I believe that some of this information will or should be available with achievement data and statistics. I don't believe that we have the ability to support multiple data sets like how many times you've completed a given quest or how long it took. It is something we can look into further, but will be lower in priority.

Q: What about events like "Killed Belial (Inferno) on <timestamp>"?

A: This data will also likely be made available with achievement data and statistics. Again, the information that I believe we can provide is the first instance of said kills.

Q: Will account id references be included with the hero API?

A: I don't believe that we are planning on doing that. That would lead to a degree of data-mining that we are not comfortable with.

Q: ... would it be possible to get time played for each character instead of having it be a ratio? possibly when doing a request to the hero api?

A: That isn't something we are planning on supporting at this time.

Q: There are no timestamps for progression. Can you please provide timestamps for each milestone in progression?

A: We aren't able to provide that information at this time.

Q: Did I miss anything about image renders of Diablo characters?

A: No, we aren't able to support character renders at this time. Sorry.

Q: Also please consider adding official talent calculator hash in the hero API skills so we can link to the official talent calculator for builds.

A: This is something that we plan on providing.

Q: Is the career profile API the only source for the hero ids or will it be possible to get the id via battle.net Armory or even ingame?

A: Right now, the only way to get hero ids will be through the career API resource. As far as I can tell, there are no ids provided in-game or through any other battle.net services.

Q: Could you please add the icon for runes and the id for skills and runes?

A: If this wasn't included in the original preview data structure then it was a simple oversight.

Q: If both APIs share the same request limit, am I correct if I assume that they also share the same error handling?

A: That is correct.

Q: While we're on the subject of this, what format is this timestamp in? Milliseconds since the epoch?

A: Seconds since epoch. Handling of timezones is TBD.

It is late on a Sunday night, you work too hard!

Will the AH have API access in a similar manner to WoW?

There are no plans to create an AH API (even read-only) for gold, hardcore gold or real money.

05/20/2012 10:31 PMPosted by Antumbra

Please consider providing read-only Auction House access, at least for normal mode gold. Right now your filtering and tooltips are so completely broken that it is a nightmare to try to buy anything without wasting your money. Read only access would at least allow people to make informed purchasing decisions when spending gold.

Building D3 AH APIs is not something that we will be dedicating resources to at this time.

05/20/2012 10:36 PMPosted by Chaud

How will the request limits work? Is the "~3000" requests per day going to be shared between the D3 API and the WoW API?

The same as with the WoW API. The requests per-day limits will be shared between the APIs as most fansites and applications are game specific (with a few exceptions).

Any chance for heros names in profile informations? Something like:
"heroes": [182, 183, 184, 185, 186],
"heroesNames": ['Yharr', 'Hero2', 'Hero3', 'Hero4', 'Hero5'],
Then I would have a list of heroes associated with account without sending five consecutive requests.

Yeah, we could do something along those lines. I'd probably lean more toward something like:


"heroes": [{
"id": 182, "name": "Yharr", "level": 26, "class": "barbarian", "hardcore": true
}, ...]


Since hero names aren't unique, I'd rather not have a list/set map to ids. Will think about this more though.

05/21/2012 07:00 AMPosted by Elimine

@Straton: Will you be implementing an API that is similar to the realm status API for WoW? While there are no "realms", per say, the game servers and AH statuses would be nice to reveal.

Yes. We will have an API resource that provides the status data as we do on http://us.battle.net/d3/en/status .

Nice! :)

Do you consider adding data resources for rolled items, unrolled items and properties?

To explain:

- A rolled item is an item that has been generated and who's stats are final.

- An unrolled item is a raw template that defines the core data, the predefined properties (and their possible ranges) and the possible number of additional random properties.

- A property is a affix or suffix like +strength. This data resource could define on what item type and item level it may appear and what range it has.

This would enable us to do some really cool stuff! :-)

Items and how they will be represented is still on the drawing board. When we make more progress and have a rough prototype, I'll be sure to update the community.

05/21/2012 11:56 AMPosted by Droodix

Any plans for a search API? Any way we could crawl for accounts to do aggregate statistics?

We haven't really come up with a good way to provide an index that doesn't compromise privacy or data that we don't want to expose. This is something we are thinking about though.

05/21/2012 11:56 AMPosted by Droodix

Any plans for giving us information about quest completion? Like how long it took them to clear a quest, perhaps including historical data if they've done a quest multiple times, and including party members involved in the kill?

I believe that this information will or should be available with achievement data and statistics.

What about events like "Killed Belial (Inferno) on <timestamp>"?

This data will also likely be made available with achievement data and statistics.

It seems as if thus far, we'll have the following: Career Profile API, Hero Profile API, Achievement API, Realm Status API, possible Search API. What about an Item API, Quest API, and just generic Data API (for classes, followers, achievement structure, item classes, etc)?

Also, how come this wasn't posted on the D3 Forums at all? I understand this is just a preview, but there are Diablo III fan-devs out there that cannot comment on this thread, :(.

A lot of the data APIs are still being worked out, but we are confident that we can provide some basic API resources for quests, classes, artisans, recipes, achievements and skills.

As for why this is on the WoW developer forum, that was just timing. I'm hesitant to create an entire forum and rev up that machine before the D3 API is actually ready for release. When we get closer to launch, I'll create a forum and update public documentation.

Exposing raw time played to the world at large makes me uncomfortable personally.

If it's a percentage of total time played split amongst classes as Delritha is suggesting, it would not bother me though.

Could we get a clarification on which it is?

What part of the API example or previous questions and responses is confusing? I'm not sure what your question actually is.

05/22/2012 12:06 PMPosted by Delritha

I suggested that it was percent based time played (1.0 = 100%, .6 = 60%, etc), but some people are thinking it's actual time played.

Yes, to confirm what Delritha is saying, we are not planning on exposing raw play time information, but rather percentages to allow websites to determine what class is played the most.

05/22/2012 11:35 PMPosted by Xtek

It would be great if the Hero API included the Player ID in it so you could reference it back.

That would lead to a degree of data-mining that I am not comfortable with.

05/23/2012 01:20 PMPosted by Chaud

That would lead to a degree of data-mining that I am not comfortable with.

Somewhat off topic, but what does that mean for linking characters to a player's BattleTag via the WoW API when support is added? It would be amazing to be able to filter out alts in data.

We'll cross that bridge when we get there.

05/24/2012 08:22 AMPosted by Chirip

Could we get a percentage of total time played for each hero in the Hero API? I could see wanting to know that I have played my barbarian the most, but that I have played one of the two barbarians I have more then the other.

Although it may be available somewhere, the only information we currently have readily available to use is the aggregate class information. For what it is worth, adding hero play time is something we'd like to do.

05/23/2012 03:53 PMPosted by Megalithe

Are there any plans to allow battle.net Chat to an external client?

Chaud is correct, we have no plans to provide API resources that require authentication or request scope.

05/25/2012 08:23 AMPosted by Elimine

@Straton: Is it possible to keep the server status page up to date? I have an Android app sc*##!*% that page until an API is available and I'm finding that the server status page is very often out of date. Its especially frustrating to have users one starring my app and leaving bad reviews because of this. The users don't realize its an issue on your end and blame the messenger. Can you offer any insight as to why that page is often not correct? My app aside that page should be accurate anyway or there is no point to its existence.

Sc%#!##@ the HTML of the D3 server status page is strictly prohibited.

Hey,

with regards to the item API I'd really love to have access to:
- equipped items
- items in inventory
- items in storage

Don't know if it makes sense to add this information to the hero/career API since that would be quite some overhead and not everyone is looking for that information. I'd prefer to have 3 separate calls where you pass the hero/account id.

Would love to hear your feedback!

We are not planning on exposing the items in your account stash or inventory.

05/25/2012 01:53 PMPosted by Earldthree

TL;DR: It was a great hassle to give my feedback on this topic. Please post it on the D3 forums.

We aren't ready to spin up an entire developer community forum on the D3 game site quite yet. Creating a preview thread here, where it has been requested and discussed before, made the most sense.

... would it be possible to get time played for each character instead of having it be a ratio? possibly when doing a request to the hero api?

That isn't something we are planning on supporting at this time.

There are no timestamps for progression. Can you please provide timestamps for each milestone in progression?

We aren't able to provide that information at this time.

05/28/2012 10:55 PMPosted by Ryrok

Did I miss anything about image renders of Diablo characters?

No, we aren't able to support character renders at this time. Sorry.

05/29/2012 06:07 PMPosted by Zen

Also please consider adding official talent calculator hash in the hero API skills so we can link to the official talent calculator for builds.

This is something that we plan on providing.

05/30/2012 08:04 AMPosted by Coss

Is the career profile API the only source for the hero ids or will it be possible to get the id via battle.net Armory or even ingame?

Right now, the only way to get hero ids will be through the career API resource. As far as I can tell, there are no ids provided in-game or through any other battle.net services.

05/30/2012 08:04 AMPosted by Coss

Could you please add the icon for runes and the id for skills and runes?

If this wasn't included in the original preview data structure then it was a simple oversight.

05/30/2012 08:04 AMPosted by Coss

It is nice to get the (localized?) artisan slug, but what's about the id?

We are in the process of evaluating localized data vs non-localized data. We will expose what makes the most sense.

05/30/2012 08:04 AMPosted by Coss

If the icon will contain the full URL, would you mind to update the icon values for the WoW API?

I believe this is already on the backlog, although I have no idea when it'll get resourced. Maybe around MoP.

05/30/2012 08:04 AMPosted by Coss

The returned array keys are not consistent. For the WoW API you used lower camel case and now you use a mix of dashes and underscores to join words. Example: "last_modified" should be "lastModified".

We are in the process of switching to a more consistant naming scheme for the attributes in our data structures. And again, this is very early in the process so attribute names haven't been scrubbed or cleaned up.

if both APIs share the same request limit, am I correct if I assume that they also share the same error handling?

That is correct.

I could go more into the larger API changes that we'd like to make, but perhaps in another post.

05/31/2012 06:34 AMPosted by Xeddicus

No item information from the stash or inventory? That was the most useful thing possible with this in my opinion, D3 is all about items after all. Sad to hear it's not even on the table for consideration.

How could the items in your inventory or stash be less useful than the items your heroes are wearing and wielding?

05/31/2012 11:24 AMPosted by Xeddicus

They're just as important, not less...did you mean AS useful, perhaps? Not sure how "less" got communicated in that. Like Delritha said, there are a lot of items sitting in the inventory and stash, much more than what we're currently wearing.

Yeah, it wa a typo.

I just would find being able to see them very useful. As an example: I generally know what I'm wearing and have an idea on what my friends are. But maybe they have a sword they plan on using next level and I don't need to hang onto one I found I think may be an upgrade for them, but turns out it isn't.

Or maybe they have something just taking up space I want.

Or for that matter just being able to see my stash/inventory of my own characters out of game would be awesome.

I'll make a note to bring it up with the team and have a discussion around it. Generally, things that are "private" in-game are also private on the web. I can inspect your hero in-game, thus we justify having profile pages outside of the game. I can't look in your stash or inventory, or see the amount of gold you have, thus we generally don't make that available through the website or API.

If there is a good argument for changing that, then it is something we can look at doing. With that said, I don't think there are any compelling reasons to change the visibility of that data.

05/31/2012 12:19 PMPosted by Xeddicus

Well, that's kind of an arbitrary cut off point.

I don't think arbitrary means what you think it means. We decided to display what can be seen in-game, a decision that has been consistent and carefully thought out.

05/31/2012 04:23 PMPosted by Xeddicus

I did say "kind of" :P Semantics (and my poor word choice...) aside, the point of that was showing the items is just as valid as not. The carefully thought out result could have been to make the stash optionally viewable to all and things would be ok (outside of possible technical issue I guess). Again, thanks for reading.

Yeah, all silliness aside, I'm going to make sure this is discussed. We generally don't include things like personal inventory and gold, but I'm going to revisit the subject internally with the team.

Easier to trade outside of the game. People can link to their profile and verify to potential buyers their inventory/stash for trading. This certainly defeats taking screenshots of your inventory and posting them to the trading forums. (Note - if you're wondering why people trade outside of the AH, it's to either beat the tax or sell more than 10 items a day)

Just putting this out there, but you list this as a "PRO", however this is a major reason for us not to do it.

Realistically, exposing inventory and stash data isn't something we would support with the release of the API. We'll discuss it, think about it, sleep on it, but it won't be any time soon.

06/01/2012 04:37 AMPosted by Thortok

You're considering showing items in your stash and inventory (or plan to consider it) but you're not considering showing items in the actual Auction House?

Take comfort in knowing that if we did expose inventory information, it would probably be way behind exposing at least read-only AH information on the list of things to do.

06/01/2012 05:13 PMPosted by Strac

time played should not be exposed in game either.

Which is totally and completely outside of my realm of influence.

In the Diablo3 Armory preview screenshots we saw progress bar with progression both on hero and account pages. In the API preview there is only very poor info about progression.

I think the API should fully reflect information from HTML pages.

Thank you good sir, it was an oversight. Hero progression will be included in the hero API resource.

While we're on the subject of this, what format is this timestamp in? Milliseconds since the epoch?

That's right, milliseconds since epoch UTC.

06/04/2012 04:51 PMPosted by Thuli

Some of the Wow api's look like ms since the epoc, but '1666805944000' is "2022-10-26 @ 07:10:04 CEST" but Straton could have just used some random data there for the example. Perhaps he will clarify this for us?

Yes, I made up some of the values for that timestamp example.

I've updated the account/career example JSON in the head post.

06/06/2012 06:27 PMPosted by Thuli

Would hardcore elites be listed under elites or separately? If a user has 0 for kills will it show up as 0 or not at all?

Ha, one would think. Unfortunately, we don't specifically have hardcore elite kill data. We are looking at why and how to resolve that.

06/06/2012 06:27 PMPosted by Thuli

For fallen heroes could this use the same structure as heroes? Or merge the two and add "fallen": True ?

I don't think so. The data associated with a fallen hero is different than a non-fallen one and I believe that it makes sense both internally and externally to represent them as two separate things.

06/06/2012 06:27 PMPosted by Thuli

If a hero is deleted by a user they will be removed from the api correct? will the hero id be recycled?

If a hero is deleted then it is effectively gone from the API. I don't believe that we have access to heroes that have been deleted. As far as hero ids are concerned, I don't believe that they are recycled, but I'd have to double check with the game team.

06/06/2012 06:27 PMPosted by Thuli

Do hero Id's increment normally (1, 2, 3, 4, etc?) If so what's to stop someone from just going through and crawling all of the /hero/### to something like uint64 and starting over (other than the resource limit?)

Yes and no. I don't believe that there are any guarantees that the sequence won't skip values. So you could see a jump from 5 to 11, for example. As far as crawling sequential ids, that isn't something that we are encouraging but understand that it will happen. We would rather have people scan the D3 API as opposed to crawling the website.

I'm curious about the value of "tooltipParams". Do I have to expect some kind of base64-ish value or is it just for the example?

No item ids for the fallen-heroes?

Items is still very rough. Better and more detailed item examples will be available soon.

06/07/2012 06:26 AMPosted by Northey

any idea when this will be going live? (approximate month or something)

We are planning on releasing the career and hero APIs along with the career and hero site profiles.

I've updated the hero profile example JSON to point to the documentation on GitHub in the head post.

06/07/2012 06:08 PMPosted by Northey

the career and hero examples are currently the same, copy paste error?

Yeah, figures.

06/07/2012 11:14 PMPosted by Wanttowrite

I hope release version will contain full list of hero stats (such as Attacks per Second, etc).

06/08/2012 06:05 AMPosted by Kieble

I noticed MF and GF have been removed in the Github, these numbers no longer being pushed?

We are still working through some of the stats and attributes. We will update the documentation as things progress.

Gah, looks like someone stole my thunder.

So we've made a lot of progress with the data APIs and I've updated the documentation to include the item data resource. I plan on creating a few additional example json files for different item types, so stay tuned for that update as well.

06/24/2012 06:10 PMPosted by Zen

Will hero banners be viewable from the upcoming Diablo 3 character profile website? In the previews from a couple months ago there were no banners.

Sadly no. If banners are squeezed in, it'll be through a front-end image layering feature (if that is possible). I didn't have the time to build the banner renderer as we had hoped.

06/24/2012 06:10 PMPosted by Zen

Will hero banners be available in the Hero API? Either the path to the cached image file or the banner image embedded as a Data URL (data:image/png;base64 ...) would work.

I do believe that we plan on providing the base banner detail information (ie the flags to indicate what is displayed and in what colors), but it may be useless until we get the chance to properly explain how to reverse engineer the data.

06/22/2012 08:50 AMPosted by Dîa

Is the BattleTag a fixed format? Like the number will be always 4 digits? Or are there really BattleTags like the one in the example 'straton#1'?

The example of "Straton#1" was just an example. The format of a battletag is as follows:


name ::= <region specific characters>
code ::= <integer greater than 1000>
battletag ::= <name> '#' <code>


The code will almost always be greater than 100, but it should be treated as an integer.

06/27/2012 12:54 PMPosted by Kieble

For getting information like someones IAS, Total Plus Min/Max Damage, Critical Damage, will we have to pull all items and add them up, or will that eventually be totalled up in the hero sheet?

That information is already calculated and totaled with the stats on the hero.

Is it intended that the precise salvage chances are exposed by this API? I noticed that we get much more precision on the chances of Firey Brimstone salvaging.

Also, are there any plans for a 'lite' option for the api that provides just the relevant data, rather than all the fancy (localized!) string flavor text?

The decision to expose the disenchant info was deliberate. The Diablo game team could swoop in and request that we change it, but with what we've shown them recently I don't think that will happen.

There aren't any plans to support a 'lite' version at this time. It is something that I can talk to the team about, but it won't likely be done any time soon.

Pulling items one by one involves many requests.
It would be good if we would be able to get all items of a hero in one request.

Well, the items of a hero are provided when requesting a single hero through the API. It is the "item details" that are specific to the item generator that requires additional calls. That same data is also available to use with the tooltip JS provided on the D3 game site, if you don't want to store all of that information.

We could entertain the idea of providing that additional item data with the hero API resource, but I'm leaning heavily against it because the amount of data returned is already very large as is.

If so I guess i'm surprised that this information won't be shown. We won't be able to even hand calculate DPS without IAS, min/max, crit dmg. Yes I know it's shown for us in Damage field but alot of the ideas people had in mind revolve around seeing how items would affect a player, and that will be impossible without pulling all other items and totalling them up manually.

That isn't the sort of information we want the community to have.

J/K

It was an oversight, those stats will be added and the documentation updated.

06/30/2012 02:33 AMPosted by Kiwibrown

What exactly does that describe, +1007% damage, + 10.07 damage, or...

I'll have to double check that.

06/30/2012 12:39 PMPosted by Zen

What about timestamps on hero/career progression?

NOPE. When we make achievement data available, you'll be able to use that.

07/02/2012 07:16 AMPosted by Chupisko

Will the returned data from api support multi language? If yes, how it will be managed?

The same way the WoW API supports multiple languages.

07/02/2012 07:16 AMPosted by Chupisko

It is possible to show itens that a acc are selling in AH? For ex. some1 could just link a page with all the itens he are selling. It would be awesome! (But i rly don't think it would be possible...)

Before I ask you to rephrase the question using big-boy words, I suggest you go back and read this thread in its entirety as it has been covered already.

Simmer down. Lets keep this thread on point so I don't have to lock it.

Are account profiles bound to regional hosts?
Can we request european-based profiles from us.battle.net?
If yes:
Would it be possible to add "region" field in career profiles so we could know primary region of the player?

Requests made to a given region only return information specific to that region.

I'm assuming the D3 API falls under the same Terms & Conditions as the WoW API

Yes, that is correct.

I'll post the status of profiles and the D3 web APIs on Monday. I've been out on vacation.

Hi everyone! Today we released D3 Game site profiles and will be releasing the D3 web APIs very shortly. As a result, I'll be locking this thread and creating a new D3 specific developer community forum on the D3 game site.

I'm so grateful to have answered your questions and gotten feedback on the D3 API. I'm very excited to have it launch soon and see what awesome things the community can create with it.

More at: http://us.battle.net/d3/en/blog/6821782/Character_Profiles_Now_Available-8_6_2012