API updates - December 18 2019

[Daniel Snider.6241]

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](https://api.guildwars2.com/v2.json?v=latest)

 

# 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

 

// 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

[knite.1542]

Thank you!

[Atomix.7053]

Thanks for the changelog !

[bluri.2653]

new leaderboard api when?

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

[wickwire.1493]

Amazing work, thank you!

[YtseJam.9784]

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?)

[Linus The One.7432]

> @"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

>

> // 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.

[Chrome.5362]

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

[UnknownFreak.2805]

Nice, but how to actually use the `code `and `skills_by_palette` in v2/professions?

if I just get guardian https://api.guildwars2.com/v2/professions/Guardian

no `code `field nor `skills_by_palette` field in the data returned. (ctrl + f palette gives no results)

Unless I'm missing something obvious...

[Daniel Snider.6241]

> @"UnknownFreak.2805" said:

> Nice, but how to actually use the `code `and `skills_by_palette` in v2/professions?

> if I just get guardian https://api.guildwars2.com/v2/professions/Guardian

> no `code `field 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.2805]

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

[NullValue.4956]

Glad to see you back in action Daniel!!

[andrewfam.5980]

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.