World of Warcraft API Update - Visions of N'zoth

API Discussion
1

Hey y’all,

We are excited to announce that we have released an update to the World of Warcraft Game Data and Profile APIs that includes several new endpoints. These endpoints are currently available for World of Warcraft; they are not available for World of Warcraft Classic.

With this update, nearly all of the endpoints required to migrate from the Community API to the Game Data and Profile APIs are available. For more information on the migration, see the Community API Migration Status page and the associated forum post.

To explore these endpoints further, check out our official API Reference documentation on the Developer Portal, located here: WoW Game Data API Reference and WoW Profile API Reference.

Game Data API

The namespace for the following Game Data API endpoints is static-{region}. See the World of Warcraft Namespaces Documentation for more information.

Item Sets

  • /data/wow/item-set/index
  • /data/wow/item-set/{id}

Journal

  • /data/wow/journal-expansion/index
  • /data/wow/journal-expansion/{id}
  • /data/wow/journal-instance/index
  • /data/wow/journal-instance/{id}
  • /data/wow/journal-encounter/index
  • /data/wow/journal-encounter/{id}

Quests

  • /data/wow/quest/index
  • /data/wow/quest/{id}
  • /data/wow/quest/category/index
  • /data/wow/quest/category/{id}
  • /data/wow/quest/area/index
  • /data/wow/quest/area/{id}
  • /data/wow/quest/type/index
  • /data/wow/quest/type/{id}

Spells

  • /data/wow/spell/{id}
  • /data/wow/media/spell/{id}

Talents

  • /data/wow/talent/index
  • /data/wow/talent/{id}
  • /data/wow/pvp-talent/index
  • /data/wow/pvp-talent/{id}

Auction House

Auction house data updates at a set interval. The value was initially set at 1 hour; however, it might change over time without notice. Depending on the number of active auctions on the specified connected realm, the response from this endpoint may be rather large, sometimes exceeding 10 MB.

The namespace for this endpoint is dynamic-{region}. See the World of Warcraft Namespaces Documentation for more information.

  • /data/wow/connected-realm/{id}/auctions

Profile API

Data for the Profile API endpoints below is only available for characters that have logged out of World of Warcraft after this week’s weekly reset.

The namespace for these Profile API endpoints is profile-{region}. See the World of Warcraft Namespaces Documentation for more information.

Achievement Statistics

  • /profile/wow/character/{realm-slug}/{character-name}/achievements/statistics

Quests

  • /profile/wow/character/{realm-slug}/{character-name}/quests
  • /profile/wow/character/{realm-slug}/{character-name}/quests/completed

Guild Activity

Guild Activity is the Profile API analog of Guild News from the Community API. Currently, Guild Activity only returns Character Achievement activity. We will be adding Encounter activity in the near future. We do not have plans to add other types of activity.

This endpoint returns guild activity for the last 7 days, updating soon after the activity happens.

Note that, although the Guild Activity endpoint is in the Profile API, it is located at the /data path prefix.

  • /data/wow/guild/{realm-slug}/{guild-name}/activity

Account Profile

Account Profile is the Profile API analog of User Characters from the Community API. Just like with User Characters, in order to access these Account Profile endpoints, you must first obtain the user’s permission by authenticating the user with Battle.net to access their data. For more information on authenticating with Battle.net using OAuth 2.0, check out the Authorization Code Flow documentation.

These endpoints require an access token acquired via the OAuth 2.0 Authorization Code Flow that has the wow.profile scope.

  • /profile/user/wow
  • /profile/user/wow/protected-character/{realm-id}-{character-id}
  • /profile/user/wow/collections
  • /profile/user/wow/collections/pets
  • /profile/user/wow/collections/mounts

If you have any questions or feedback, please let us know!

Cheers!

6 Likes
3

Regarding the AH API:
What is the reasoning behind having both unit_price and buyout?
Why not just unit_price or buyout?

1 Like
4

I am unsure why there is such little information provided by the /profile/user/wow endpoint.

There is often little use for characters not relatively close to the level cap of recent years. Unfortunately, this endpoint doesn’t provide the level of characters used. My account has 105 characters on it, only a very slim few of them I’d be interested in keeping on my website, but I have to make requests for each character to determine their levels.

2 Likes
6

This post is the summary of a discussion over the Community Discord Server

The new endpoint to retrieve a user’s character list /profile/user/wow is returning a very different set of data. With this change comes new challenges for a sign on process. Most apps will show the user a list of their characters after the OAuth2 process is completed to allow them to pick one or a few relevant characters.

The old community endpoint /wow/user/characters returns important data for each char like: level, gender, playable_class_id, playable_race_id and so on.

This allowed us to build character selection interfaces like the one below without having to fetch any other data for each character.

Since the new profile endpoint /profile/user/wow return only an index of user’s characters without any character specific information, it is necessary to call at least one more request per character before rendering the character selection list.

The new logic would be:

  1. Authenticate the user using OAuth2 Authorization Code Flow
  2. Retrieve a list of characters by calling /profile/user/wow
  3. For each returned character call /profile/wow/character/{realmSlug}/{characterName}

It is technically possible to fetch many requests asynchronously given the programming language you are using offer such feature. However there are some considerations for a few use cases:

  1. The API allows up to 100 req/s for each pair of credentials.
  2. It is a bit more complex to manage those limits in a real concurrent environment so it can present a challenge for average programmers.
  3. A lot of people use the API to create simple guild pages/application forms for raid groups. And a lot of those apps run on shared hosts, where the number of concurrent requests are very limited.
  4. The “refresh” process must be done every time a user comes back so their character’s level (and possibly other data) are always up-to-date.
  5. If you don’t fetch character data concurrently it may take almost a second per character depending on server’s location. Which means almost a minute for loading data for an account with 50 characters.

If the new endpoint could return at least the following additional data per character it would be really nice:

  • level
  • playable_class_id
  • playable_race_id
2 Likes
7

Is it normal that I’m getting 403 forbidden when trying the new /profile/user/wow endpoint?

I’m using this URL with my access token which works for every other endpoint:
https://us.api.blizzard.com/profile/user/wow?namespace=profile-us&locale=en_US&access_token=TOKEN

8

Have you signed in and out of wow after the API update ?

9

Oh I see… I didn’t take that into account. my bad!

10

The Character Completed Quest Profile API doesn’t list completion for the Weekly Island Expeditions quest Azerite for the Alliance - Quest - World of Warcraft which shows up correctly in the old Community API

11

For the auction data API, can we assume the Last-Modified value returned in the headers is somewhat accurate and serves the same purpose as the “lastModified” field from the community API:

cache-control: public, max-age=86400
content-type: application/json;charset=UTF-8
last-modified: Thu, 13 Feb 2020 23:11:24 GMT

{“files”:[{“url”:"…",“lastModified”:1581643309000}]}

This was useful in that we could wait until an update was expected, rather than constantly using resources to the hit the API for each realm to check for new data.

Thanks!

1 Like
12

In the absence of any alternative, that’s what I’m using.

13

I hope you can reconsider and add character level to the profile endpoint.

14

Thanks. 2 things:

  • Returns 403 in TW and KR regions. See hxxp://does.theapi.work/
  • The old API would spread out updates across the hour. This new API appears to update most (all?) realms in a region pretty much in the same minute. This could cause you some bandwidth stampeding issues (and make it harder for those of us who survey all realms to do so in a timely fashion) but whatev.
15

Internally, there is a distinction between commodities and “regular” items via unit_price versus buyout. We decided to keep this distinction in the API. While it may feel unnecessary currently (because the unit price is effectively a buyout price), this distinction:

  1. Signals whether or not an item is a commodity without bloating every returned item with an item type field. (We’re concerned with adding more fields than necessary to the Auctions endpoint because of how large auction dumps may become for high population realms.)

  2. Insulates the API from changes to commodity functionality that may occur.

We really appreciate the detailed feedback here, and we’re discussing this internally.

Thanks for the report!

You are correct. Every endpoint in the Game Data and Profile APIs returns a Last-Modified response header indicating when the document was last updated. This is particularly useful to determine the last updated time for profile and dynamic data (namespaced via profile-{region} or dynamic-{region} respectively) or when checking against static data that has been cached on your end (namespaced via static-{region}).

The Game Data and Profile APIs also support the If-Modified-Since request header, allowing you to avoid the download overhead if the document has been unmodified since the specified date. This is particularly useful when interacting with the Auction House API because response sizes may be rather large. See this reference for more information on the header.

We’re seeing a couple of issues in KR and TW, and we’re working on a fix:

  1. New Visions of N’zoth endpoints listed in the original announcement post returning a 403 Forbidden.
  2. Character profiles not updating properly on logout.

We’re aware of this and monitoring usage. If you notice any issues, please let us know!

16

These issues have been resolved.

17

Seconding this. My use case is extremely similar, providing a list of the users characters for them to select the one that should be linked to the account and used as a main.
Having the requested 3 data points level, class and race back in the character list would make things a lot easier for my end users (because I’m definitely not going to make individual calls for each of their characters)

1 Like
18

+1 this

Being able to show at a high level the list of characters available (Name, Realm, lvl, race, class, thumbnail) and having this data to allow users to select which characters they wish to share is very important both for performance reasons and privacy reasons

19

Feedback about Journal API

Old Endpoint for Zones:
/wow/zone/209
New Endpoint for Instances:
/data/wow/journal-instance/64?namespace=static-eu

  • Zone/Instance ID do not match: 209 ≠ 64
  • Missing urlSlug (Usefull for zone thumbnail from render-eu.worldofwarcraft. com/zones/{urlSlug}-small.jpg)
  • Old Boss ID do not match with new Encounter ID and there is no reference to it
20

Are we going to get a definitive awnser for the /profile/user/wow endpoint on whether more information will be added for specific characters (race, level, gender, class) or should I start to change my code?

March 16 is coming fast and it would be great to know if I should start making changes right now or wait for an update so I don’t have to do the work twice.

Thank you.

1 Like
21

Based on the feedback in this thread, we are evaluating adding the following additional fields to the account profile:

  • level
  • playable_class
  • playable_race
  • faction
  • gender

We do not yet have a date as to when these will be available. Therefore, please plan to pull this character information from the character endpoint by March 16th.

This solution unfortunately will not support a link to the avatar image.

In the long run we envision better ways to aggregate data across different endpoints instead of duplicating data throughout the API. We’re discussing how to handle these situations. But for now, we’re working on adding the above fields in the Account Profile endpoint to solve your use cases.

Thanks again for all your feedback!

3 Likes
22

These fields are now available for accounts that log out after this week’s weekly reset in each region.

Users will need to perform an account logout for this data to update. An account logout involves either quitting the game (via closing the WoW executable) or logging out of the WoW client (e.g. via the “Back” button on the character select screen) from all WoW accounts on a Battle.net account. Logging out of your character to character select or realm select does not suffice. You must be logged out of all WoW accounts at the same time to trigger the event.

3 Likes