Getting started with the WoW API

Hello everyone.

I have decided to write this post to help new developers getting started with the Blizzard APIs. I’m focusing first on the most common questions here in the forums and over the Community Discord Server.

1. The basics

1.1. Gaining access to the API

To gain access to the API visit https://develop.battle.net/access and follow the instructions.

When creating your first client credentials use http://localhost and check the option I do not have a service URL for this client if you still don’t know exactly how you are gonna use it (you can edit later).

:bangbang: It can take up to 15 minutes for your new credentials start working.

1.2. Testing the API

If you want to play around the API and see what data is available, you can use your new credentials on the official API documentation.

1.3. Libraries and resources

This is the official post for searching community created libraries and other resources. I’ll replicate here only available libraries and its status*. Make sure to check out the official post.

:white_check_mark: : Up to date
:ballot_box_with_check: : Missing lastest update
:no_entry_sign: Missing many updates

Language Repository Package manager Last updated Up to date* Support
Ruby Gitlab Rubygems 2020-10-23T00:00:00Z :white_check_mark: ALL
PHP Gitlab N/A 2020-09-07T00:00:00Z :no_entry_sign: WoW
NodeJS Github NPM 2020-10-12T00:00:00Z :ballot_box_with_check: ALL
Python Github Pypi 2020-11-13T00:00:00Z :ballot_box_with_check: WoW
Go Github Go get 2020-11-01T00:00:00Z :ballot_box_with_check: ALL
C# Github NuGet 2020-09-10T00:00:00Z :no_entry_sign: WoW

*Last API update: 2020-11-17T00:00:00Z WoW Shadowlands API Update - Covenants, Soulbinds & More

1.4. Open source applications using the API

:key: Using the client credentials flow
:busts_in_silhouette: Using the authorization code flow.

Language Repository Features Auth type
Ruby Gitlab Complete proxy to endpoints :key: :busts_in_silhouette:
Ruby on Rails Gitlab Character profile :key:
Ruby on Rails Gitlab Sign in with bnet :busts_in_silhouette:
PHP Gitlab Character profile :key:
Go Github Relational databases :key:
Go Github Save AH data to files :key:
NodeJS Github Forum signature generator :key:
NodeJS Github Login with bnet :busts_in_silhouette:

Since the forum doesn’t allow everyone to edit link, leave a comment if you want to add something to this list.

2. Types of endpoints

There are many types of endpoints available, each type is meant to be used in a different way, I’ll try to explain the most common usage for each type.

2.1. Game data

This is the most common endpoint, they are used to provide static and dynamic data (see Namespaces for details). Those endpoints will provide data not bound to a specific profile.

An example of static data is World of Warcraft Items, they don’t change unless a new patch comes out. That means you should cache their data in your own database to reduce API consumption.

An example of dynamic data is World of Warcraft Auctions, while they do change it is timed, so you can update them using scheduled jobs.

:bangbang: Those endpoints are usually there to support other endpoints. Items for instance do not return all items in-game, just the ones referenced by other endpoints like character equipment or auction data. Same goes for spells.

2.2. Profile or Community data

The new profile and some old community data represents data bound or created by a player. Those endpoints require an special attention and must be implemented in a way to comply to the Data protection policy.

In addition to that the data will update in irregular intervals. World of Warcraft character data updates when a character logs out of the game.

Important: Some profile endpoints require a special access_token obtained by the Authorization code flow, otherwise you’ll get a 401 or 403 error.

2.3. Media endpoints

Those endpoints are used to fetch image URLs for other endpoint, such as creatures, items, spells, etc

See also: Character renders

2.4. Search endpoints

Some endpoints like World of Warcraft Items and Spells have too many records and don’t have an index endpoint. Most of them provide a search endpoint instead. See Search endpoints for more information.

3. Frequently Asked Questions

Q. I’m getting a 401 response, what am I doing wrong ?

A: 401 means you don’t have the required permission to access the data, usually you are using an access_token created with the client credentials flow instead of the authorization code flow.

Q. I’m getting a 403/404 response, what am I doing wrong ?

A: There are a few possibilities:

  • 404 might have many causes, most common is a typo in your uri or you are not using slugs.
  • 404 and 403 can also mean the data you are trying to access is invalid due to API updates. That happens when a character never went online after a major API update.
  • You are using the wrong region or namespace

Q. Where can I find the Overwatch/HotS api ?

A: They don’t exist. :frowning_face:

Q. Can I access WoW Classic Profiles ?

A: No, the only APIs available for classic are the ones listed here

Q. Where can I find a list of bonus ids for WoW Items ?

A: Unfortunately the API does not support this yet but there are some workarounds.

7 Likes

This post is great! Some small suggestions/feedback:

  • Add a section for “demo” apps/codebases that are open-sourced.
  • Always reference WoW Class by its full name to avoid confusion. IE: “Can I access classic profiles?” -> “Can I access WoW Classic profiles?”.
  • Specify which game a FAQ question references when its game-specific. IE: " Where can I find a list of bonus ids for the items?" -> “Where can I find a list of bonus ids for WoW items?”.
2 Likes

Nice suggestion, I modified the endpoint names. However I’m not sure how to add the demo sections, I mean, it will be hard to track which ones are still up to date.
I’ll edit it later to add a reference to Showcase Your App!

EDIT: I added the ones I know about. Let me know if there is any other missing.

Unfortunately I don’t think non MVP can contribute to this wiki because of the way Discourse treat trust level and links, it is a shame.

Hello I really enjoyed your post. I’m am a new developer and currently working with scala. My Question is I have been able to access the API through my application . However I keep getting back a JSON string instead of a JSON object which makes it very difficult to parse through using iteration. Am I doing something wrong or can you enlighten me on how to get the information out that I am meeting

I can’t say specific for Scala, but most languages are shipped with native JSON encoders/decoders. Try searching the web for “how to parse json in scala” for more information.