Character Achievements API: When is an achievement "completed"?

API Discussion
1

We received a question in the Community Discord Server over the weekend from user Charodey:

Achievements are very complicated in WoW, and the API reflects all of the nuances. Unfortunately, it might not reflect it as clearly as we would like!

Before we start: I’d like to briefly go over “achievement criteria” or just “criteria”. Achievement criteria are the checkpoints required by the achievement in order to gain that achievement. Sometimes there’s one criterion. Other times there’s many. Sometimes there’s an operator that affects the criteria. All of this information can be gathered from the /data/wow/achievement/{id} endpoint.

Now, not all achievements may be shown in the API the way you expect them to. Achievements respect the “Display Only Character Achievements To Others” in-game option, found in-game at Game Menu | Interface | Social | Display Only Character Achievements To Others. Data returned from the /profile/wow/character/{realm}/{character}/achievements endpoint will reflect achievements as viewed in-game when inspecting another character. The in-game option changes this view.

This last point is important: it will not appear as your achievements appear in your personal achievements pane when playing the character. It will instead show as another character sees you when you are inspected.

In WoW, there are a two different types of achievements: account achievements and character achievements. This distinction is made by the is_account_wide flag returned from the /data/wow/achievement/{id} endpoint. For now, let’s assume we’re in the most common case: “Display Only Character Achievements To Others” is disabled.

For account achievements:

  • The achievement criteria completion, criteria.is_completed, is true when the conditions for the criteria have been met for any character across the account.
  • The child criteria, criteria.child_criteria, are tracked across the account. If any character has fulfilled a particular criterion, criteria.child_criteria[].is_completed will be true for all characters on the account.
  • The completion timestamp, completed_timestamp, appears when the achievement has been completed by the account.
  • An example of an account achievement is ID 12807.

Because of this, account achievements look the same for all characters across the account, provided the “Display Only Character Achievements To Others” flag is disabled. When criteria.is_completed is true, completed_timestamp will be available. If completed_timestamp is not available, criteria.is_completed should be false.

This is how you would expect all achievements to work. However, this is not how character achievements work.

For character achievements:

  • The achievement criteria completion, criteria.is_completed, is only tracked for the character that you requested, and will only be true when the conditions for the criteria has been met for that character.
  • The child criteria, criteria.child_criteria, are only tracked for the character that you requested, and is_completed will only be true if the specified character has completed the criterion.
  • The completion timestamp, completed_timestamp, appears when the achievement has been completed by any character on the account.
  • An example of a character achievement is ID 32.

Therefore, provided the “Display Only Character Achievements To Others” flag is disabled, a character achievement with criteria.is_completed as false but with a completed_timestamp appearing means that the achievement was completed by another character on the account.

For both account and character achievements, this behavior changes if “Display Only Character Achievements To Others” is enabled:

  • The achievement criteria completion, criteria.is_completed, is only tracked for the character that you requested, and will only be true when the conditions for the criteria has been met for that character.
  • The child criteria, criteria.child_criteria, are only tracked for the character that you requested, and is_completed will only be true if the specified character has completed the criterion.
  • The completion timestamp, completed_timestamp, appears when the achievement has been completed by the requested character.

Effectively, enabling the in-game option removes all links to your other characters for both achievement types, only showing that one character’s progress. For data protection reasons, we do not explicitly expose whether or not a character has the in-game option enabled or disabled.

In all situations, this should reflect how achievements are displayed in-game when your character is inspected.

You can actually verify some of this without finding someone to inspect you. For example, achievements that you gained on other characters will be visible via the achievements pane in-game and show as acquired even if your current character has not yet completed the achievement. The criteria for the achievement, however, will reflect your current character’s progress.

ANYWAYS! I’ve spoken enough. I hope that answers the question! If there are any other questions, let us know. :smiley:

4 Likes
2

Thank you for this clear explanation!

If I’ve understood it correctly, I believe I’m seeing some API responses that do not follow this spec. For example, my character blades-edge/brialap has “Display Only Character Achievements To Others” enabled, but I’m seeing character achievements where criteria->is_completed is false while a completed_timestamp is present, which I believe should be impossible according to the 5th to last paragraph.

Request: US profile/wow/character/blades-edge/brialap/achievements
Response includes:
…

{
“id”: 13389,
“achievement”: {
“key”: {
“href”: “…link not allowed…13389?namespace=static-8.3.7_35114-us”
},
“name”: “Jorundall”,
“id”: 13389
},
“criteria”: {
“id”: 72418,
“is_completed”: false
},
“completed_timestamp”: 1545123240000
},

Is this a bug? Or have I misunderstood? I can provide many other similar examples if it will help.

In trying to think what might have caused this, I realized that I do have other characters with this achievement that have NOT elected DOCATO, and also that at the time I earned this achievement on another character, this character may have not yet elected DOCATO. I don’t believe either should be relevant according to your spec, but perhaps there is a bug where it unintentionally is?

Sorry if I’m missing something obvious…

1 Like