API updates - December 18 2019 — Guild Wars 2 Forums

API updates - December 18 2019

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[i].location and equipment[i].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>

// PACKED

struct 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

Tagged:

Comments

  • knite.1542knite.1542 Member ✭✭✭

    Thank you!

    Time gates = content

  • Thanks for the changelog !

  • bluri.2653bluri.2653 Member ✭✭✭✭

    new leaderboard api when?
    https://api.guildwars2.com/v2/pvp/seasons does not have current season :angry:

  • Amazing work, thank you!

  • YtseJam.9784YtseJam.9784 Member ✭✭✭
    edited December 19, 2019

    not sure if this is new, but just noticed that https://api.guildwars2.com/v2/account, commander doesn't return true if you only have the Catmander tag (I thought it did?)

  • @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>
    
    // PACKED
    
    struct 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.

  • Thank you. I'd been hoping these were on the way!

  • 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/Guardian
    no codefield nor skills_by_palette field in the data returned. (ctrl + f palette gives no results)
    Unless I'm missing something obvious...

    return 0xdeadbeaf

  • @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/Guardian
    no 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_Versions
    and you can find my original post introducing the feature here: https://en-forum.guildwars2.com/discussion/72091/api-updates-march-22-2019

  • UnknownFreak.2805UnknownFreak.2805 Member ✭✭
    edited December 20, 2019

    That works, but why not use accept headers, where the version is specified?
    Maybe there is a reason not to do that...

    Edit: Should probably read before asking question with the answer in the post you linked

    return 0xdeadbeaf

  • Glad to see you back in action Daniel!!