Jump to content
  • Sign Up

API updates - December 18 2019


Daniel Snider.6241

Recommended Posts

  • ArenaNet Staff

Hello all,

Build and equipment templates are now available on the API! I've also included some necessary data for decoding/encoding build chat links (I provide the format in this post).

Recent API Updates


First, here is the change in list format:

  • Added code and skills_by_palette to /v2/professions.
  • Added code to /v2/legends.
  • Added build_storage_slots to /v2/account.
  • Added build_tabs_unlocked, active_build_tab, and build_tabs to /v2/characters/:id.
  • Added equipment_tabs_unlocked, active_equipment_tab and equipment_tabs to /v2/characters/:id.
  • Added equipment.location and equipment.tabs to /v2/characters/:id.
  • Removed skills and specializations from /v2/characters/:id.

All of the above changes come with the latest schema version. Check out the full list of migrations in v2.json

Build Storage


You can store build templates in your account-wide "Build Storage". This data is available on the API at /v2/account/buildstorage?ids=all. This acts like a typical "bulk" endpoint so you can also make requests for specific slots.

Each build object contains the skills (terrestrial & aquatic), the specializations, the profession it applies to, the legends (terrestrial & aquatic), pets (terrestrial & aquatic), and the chosen name of the template. I've tried to keep the format as similar to the old skills & specializations objects.

In the response at /v2/account you'll also find the build_storage_slots, which tells you how many slots have been unlocked for this account.

Build Tabs


Each character has a number of build "tabs". This data is available on the API at /v2/characters/:id under the build_tabs field. In addition, there is a bulk endpoint that lets you access individual tabs at e.g. /v2/characters/:id/buildtabs?tabs=1,3. For convenience I've added the active build at /v2/characters/:id/buildtabs/active.

I've kept the format of the builds in these tabs exactly the same as in the build storage endpoints, so your parsing code can handle them both the same way.

In the response at /v2/characters/:id I've also added build_tabs_unlocked which tells you how many build tabs the character has unlocked, and active_build_tab which gives the index for the active tab for the character.

Equipment Tabs


Your character’s equipment, attributes, and upgrades (excluding gathering tools) are stored in equipment tabs. This data is available on the API at /v2/characters/:id under the equipment_tabs field. In addition, there is a bulk endpoint that lets you access individual tabs at e.g. /v2/characters/:id/equipmenttabs?tabs=1,3. For convenience I've added the active equipment at /v2/characters/:id/equipmenttabs/active.

In the response at /v2/characters/:id I've also added build_tabs_unlocked which tells you how many build tabs the character has unlocked, and active_build_tab which gives the index for the active tab for the character.

Equipment changes


Because of how the equipment tabs work, items linked to an inactive tab don't appear in your inventory. Also, items can appear multiple times in different tabs. If you only have equipment_tabs to look at, you may think a character owns more items than they really do. For example, I might use the same legendary weapon on 5 different tabs, but that doesn't mean I actually own 5 of that weapon.

Therefore, I have kept the equipment field in /v2/characters/:id and I have added all of the linked items to the list. Each item in the list has a location field with either Equipped or Armory. For convenience I also have a tabs field with an array of tab indices you can find that item in.

Build chat links


Build chat links are base64 encoded data surrounded by [& ].

The format of the encoded data is represented here by this C++ struct:

#include <cstdint>// PACKEDstruct BuildChatLink {    std::uint8_t magic = 0xd;    // Profession codes can be found in the `code` field at    // https://api.guildwars2.com/professions    std::uint8_t profession;    // Specializations can be found at    // https://api.guildwars2.com/specializations/:id    // To find a trait ID given a specialization, first find the `major_traits`    // array at https://api.guildwars2.com/v2/specializations/:id    // Then, reference this table to find the trait ID:    //        field        | value |    trait ID    // ====================+=======+=================    // traitAdeptN         |     0 | None    //                     |     1 | major_traits[0]    //                     |     2 | major_traits[1]    //                     |     3 | major_traits[2]    // traitMasterN        |     0 | None    //                     |     1 | major_traits[3]    //                     |     2 | major_traits[4]    //                     |     3 | major_traits[5]    // traitGrandmasterN   |     0 | None    //                     |     1 | major_traits[6]    //                     |     2 | major_traits[7]    //                     |     3 | major_traits[8]    // Traits themselves can be found at https://api.guildwars2.com/traits/:id    std::uint8_t specialization1;    std::uint8_t traitAdept1       : 2;    std::uint8_t traitMaster1      : 2;    std::uint8_t traitGrandmaster1 : 2;    std::uint8_t traitPadding1     : 2;    std::uint8_t specialization2;    std::uint8_t traitAdept2       : 2;    std::uint8_t traitMaster2      : 2;    std::uint8_t traitGrandmaster2 : 2;    std::uint8_t traitPadding2     : 2;    std::uint8_t specialization3;    std::uint8_t traitAdept3       : 2;    std::uint8_t traitMaster3      : 2;    std::uint8_t traitGrandmaster3 : 2;    std::uint8_t traitPadding3     : 2;    // To find a skill ID given a palette ID, first find the `skills_by_palette` array    // at https://api.guildwars2.com/v2/professions/:id for this build's profession.    // Then, find the pair with the palette ID and use the mapped value.    // For example, in javascript you might look it up like so:    //     new Map(skills_by_palette).get(paletteID)    // Skills themselves can be found at https://api.guildwars2.com/v2/skills/:id    std::uint16_t terrestrialHealingSkillPalette;    std::uint16_t aquaticHealingSkillPalette;    std::uint16_t terrestrialUtilitySkillPalette1;    std::uint16_t aquaticUtilitySkillPalette1;    std::uint16_t terrestrialUtilitySkillPalette2;    std::uint16_t aquaticUtilitySkillPalette2;    std::uint16_t terrestrialUtilitySkillPalette3;    std::uint16_t aquaticUtilitySkillPalette3;    std::uint16_t terrestrialEliteSkillPalette;    std::uint16_t aquaticEliteSkillPalette;    union {        struct {            // Pets can be found at            // https://api.guildwars2.com/v2/pets/:id            std::uint8_t terrestrialPet1;            std::uint8_t terrestrialPet2;            std::uint8_t aquaticPet1;            std::uint8_t aquaticPet2;        } ranger;        struct {            // Legend codes can be found in the `code` field at            // https://api.guildwars2.com/v2/legends/:id            std::uint8_t activeTerriestralLegend;            std::uint8_t inactiveTerrestrialLegend;            std::uint8_t activeAquaticLegend;            std::uint8_t inactiveAquaticLegend;            std::uint16_t inactiveTerrestrialLegendUtilitySkillPalette1;            std::uint16_t inactiveTerrestrialLegendUtilitySkillPalette2;            std::uint16_t inactiveTerrestrialLegendUtilitySkillPalette3;            std::uint16_t inactiveAquaticLegendUtilitySkillPalette1;            std::uint16_t inactiveAquaticLegendUtilitySkillPalette2;            std::uint16_t inactiveAquaticLegendUtilitySkillPalette3;        } revenant;    };};

As mentioned in the comments above, I've added skills_by_palette under each profession in /v2/professions/:id.

I've also included a code field under /v2/professions/:id and a code field under /v2/legends/:id.


This was a very big change that touched a lot of API code, so please report any bugs here. That includes any mistakes I made with old schema versions; I don't want to break existing applications if possible.

Finally, I want to apologize for the delay in deploying these changes, I was on leave during the release of the build templates feature.

Thanks!Snider

Link to comment
Share on other sites

@Daniel Snider.6241 said:Build chat links are base64 encoded data surrounded by [& ].

The format of the encoded data is represented here by this C++ struct:

#include <cstdint>// PACKEDstruct BuildChatLink {  std::uint8_t magic = 0xd;  // Profession codes can be found in the `code` field at  // https://api.guildwars2.com/professions  std::uint8_t profession;  // Specializations can be found at  // https://api.guildwars2.com/specializations/:id  // To find a trait ID given a specialization, first find the `major_traits`  // array at https://api.guildwars2.com/v2/specializations/:id  // Then, reference this table to find the trait ID:  //        field        | value |    trait ID  // ====================+=======+=================  // traitAdeptN         |     0 | None  //                     |     1 | major_traits[0]  //                     |     2 | major_traits[1]  //                     |     3 | major_traits[2]  // traitMasterN        |     0 | None  //                     |     1 | major_traits[3]  //                     |     2 | major_traits[4]  //                     |     3 | major_traits[5]  // traitGrandmasterN   |     0 | None  //                     |     1 | major_traits[6]  //                     |     2 | major_traits[7]  //                     |     3 | major_traits[8]  // Traits themselves can be found at https://api.guildwars2.com/traits/:id  std::uint8_t specialization1;  std::uint8_t traitAdept1       : 2;  std::uint8_t traitMaster1      : 2;  std::uint8_t traitGrandmaster1 : 2;  std::uint8_t traitPadding1     : 2;  std::uint8_t specialization2;  std::uint8_t traitAdept2       : 2;  std::uint8_t traitMaster2      : 2;  std::uint8_t traitGrandmaster2 : 2;  std::uint8_t traitPadding2     : 2;  std::uint8_t specialization3;  std::uint8_t traitAdept3       : 2;  std::uint8_t traitMaster3      : 2;  std::uint8_t traitGrandmaster3 : 2;  std::uint8_t traitPadding3     : 2;  // To find a skill ID given a palette ID, first find the `skills_by_palette` array  // at https://api.guildwars2.com/v2/professions/:id for this build's profession.  // Then, find the pair with the palette ID and use the mapped value.  // For example, in javascript you might look it up like so:  //     new Map(skills_by_palette).get(paletteID)  // Skills themselves can be found at https://api.guildwars2.com/v2/skills/:id  std::uint16_t terrestrialHealingSkillPalette;  std::uint16_t aquaticHealingSkillPalette;  std::uint16_t terrestrialUtilitySkillPalette1;  std::uint16_t aquaticUtilitySkillPalette1;  std::uint16_t terrestrialUtilitySkillPalette2;  std::uint16_t aquaticUtilitySkillPalette2;  std::uint16_t terrestrialUtilitySkillPalette3;  std::uint16_t aquaticUtilitySkillPalette3;  std::uint16_t terrestrialEliteSkillPalette;  std::uint16_t aquaticEliteSkillPalette;  union {      struct {          // Pets can be found at          // https://api.guildwars2.com/v2/pets/:id          std::uint8_t terrestrialPet1;          std::uint8_t terrestrialPet2;          std::uint8_t aquaticPet1;          std::uint8_t aquaticPet2;      } ranger;      struct {          // Legend codes can be found in the `code` field at          // https://api.guildwars2.com/v2/legends/:id          std::uint8_t activeTerriestralLegend;          std::uint8_t inactiveTerrestrialLegend;          std::uint8_t activeAquaticLegend;          std::uint8_t inactiveAquaticLegend;          std::uint16_t inactiveTerrestrialLegendUtilitySkillPalette1;          std::uint16_t inactiveTerrestrialLegendUtilitySkillPalette2;          std::uint16_t inactiveTerrestrialLegendUtilitySkillPalette3;          std::uint16_t inactiveAquaticLegendUtilitySkillPalette1;          std::uint16_t inactiveAquaticLegendUtilitySkillPalette2;          std::uint16_t inactiveAquaticLegendUtilitySkillPalette3;      } revenant;  };

Really appreciate the going into detail here, thank you so much. That's the kind of info I love.

Link to comment
Share on other sites

  • ArenaNet Staff

@"UnknownFreak.2805" said:Nice, but how to actually use the codeand skills_by_palette in v2/professions?if I just get guardian https://api.guildwars2.com/v2/professions/Guardianno codefield nor skills_by_palette field in the data returned. (ctrl + f palette gives no results)Unless I'm missing something obvious...

Try this:https://api.guildwars2.com/v2/professions/Guardian?v=2019-12-19T00:00:00Z

You need to view the document at the latest schema version to get the new fields. There is documentation about schema versions here: https://wiki.guildwars2.com/wiki/API:Main#Schema_Versionsand you can find my original post introducing the feature here: https://en-forum.guildwars2.com/discussion/72091/api-updates-march-22-2019

Link to comment
Share on other sites

  • 8 months later...

As it stands right now, we can do /v2/characters?ids=all to get all characters' information of an account in one shot. Is it possible to include the equipment tabs too?So we don't have to circle back and parse them again by the individual character. That will save us time tremendously.
Before I could read all 5 accounts in about one minute and 30 seconds. After I added the equipment tabs implementation, It read 10 times as long.Parsing the infos was not the problem. The issue was send/receive the request. It took a lot longer to do /v2/characters/character name/equipmenttabs?tabs=all for some reason.

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...