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).
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.
: Up to date
: Missing lastest update
Missing many updates
|Language||Repository||Package manager||Last updated||Up to date*||Support|
*Last API update: 2020-11-17T00:00:00Z WoW Shadowlands API Update - Covenants, Soulbinds & More
1.4. Open source applications using the API
|Ruby||Gitlab||Complete proxy to endpoints|
|Ruby on Rails||Gitlab||Character profile|
|Ruby on Rails||Gitlab||Sign in with bnet|
|Go||Github||Save AH data to files|
|NodeJS||Github||Forum signature generator|
|NodeJS||Github||Login with bnet|
|NodeJS||Github||Login with bnet (Vanilla JS)|
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.
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 ?
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.
Q. Can I access WoW Classic Profiles ?
A: No, the only APIs available for classic are the ones listed here