Guild Wars 2

The item API was updated with the following fixes and enhancements:

• Added bonus tiers for upgrade components
• Fixed ‘SoulBindOnUse’ flag for certain items

Does anyone have any of these items? If so, can you try transferring it to your bank, or mailing it? Once you do, I suspect it’ll appear in the discovered items list.

Dr Ishmael.9685:

Dr Ishmael.9685:

Moturdrn.2837:

The foreground and background IDs for this match the order on the wiki (http://wiki.guildwars2.com/wiki/Gallery_of_guild_emblems). Do you know if the IDs returned by the API will match these or will there be another order for them?

The numbers I assigned to them for the wiki are simply sequential based on their file ID order within Gw2.dat. I seem to remember that this matched the order that they appear within the in-game emblem designer, so it may very well match up to the in-game IDs (although I wouldn’t count on it).

Turns out that YES, the emblems are displayed at the Emblemer in the order of their internal ID, and since my numbering matched the display order, the numbers on the wiki match the internal IDs.

Unfortunately, when I numbered the backgrounds, I forgot to account for the “blank” background, so the numbers on the wiki are (ID – 1) instead of matching the ID exactly. Still, it’s a systematic difference.

I’ve zipped up the game textures (converted to PNG) with the correct IDs, and you can grab them over here (File->Download or Ctrl+S to download). Use in conjunction with colors.json to build guild emblem wizards!

Edit: had a sync error on my GDrive, link is fixed now

Nice! I’m glad that worked.

smiley.1438:

ERMAHGERD! You added RGB values and made all our efforts obsolete! Q.Q
(thanks, was fun to find out anyway )

You still need the more detailed information if you want to apply dyes against textures yourself, such as for guild emblem compositing.

The colors you were seeing invalid saturation values for were colors that had a different base_rgb than 128,26,26 (skin, hair, eye, etc. colors).

I just updated the API to show the base_rgb of colors. I also removed the non-dye colors to make it more uniform and reduce confusion (multiple “black” dyes, etc.).

I also created a javascript version of our internal color shifting algorithm here: http://jsfiddle.net/cliff/jQ8ga/ . This example code uses the sylvester javascript matrix library for math.

The way it works is pretty different than the processes previously described — it calculates a transformation matrix which is then applied to the color in one pass.

I also added pre-calculated RGB values to the color API for those who don’t need to deal with HSL transformations and just want an RGB value. It can also be used to test your color shifting algorithm against ours for correctness.

Dr Ishmael.9685:

Looking at smiley’s listing, it appears that colors 1222-1230 are the hair colors exclusive to the Self-Style Hair Kit, and colors 1231-1242 are the dyes from the Flame and Frost Dye Kits. The hair colors only have a default material, while the dyes all have cloth/leather/metal. This definitely supports Rhino’s hypothesis.

Yes, that’s right. I just updated the API to remove those colors for now, since you can’t really do much with them. So now it’ll only return dye colors. In the future, we could re-add those if there’s an interesting use-case, but I think for now it’s confusing.

The Color API was updated with the following changes:

• Added pre-calculated ‘RGB’ values for users who only want an RGB value and are not planning to apply the color to a texture mask.
• Added base_rgb value to each color returned
• Changed API to only return ‘dye’ colors. Previously the API showed skin, eye, hair, etc. colors in addition to dyes.

Blumoon.5437:

Let’s say I develop a web app that shows all of the dye colors accessible in the game. In the future when OAuth support is implemented, will a logged-in player be able to see their favorites and unlocked dye colors for each of their characters?

That’s the idea. Any references to colors in other APIs would be able to be resolved using this API.

Wow, who knew that a simple color API would turn out to be so complicated!

Thanks a lot for helping me reverse-engineer our color math, and Killer Rhino, thanks for writing a great guide!

I’m going to keep looking into it on my end and see if there’s a better way for us to provide the API for you. It seems like we’re at least 95% of the way there though.

Let’s switch over to the “how-to” thread for any more discussion about implementation issues. ( https://forum-en.gw2archive.eu/forum/community/api/How-To-Colors-API/first )

Think.8042:

How exactly are you supposed to do the HSL shift in step 4?
Say I have 0.75 Saturation after applying brightness and contrast, and the API says I need to shift by 0.41? What should the results be?

Just clarified and fixed the API values a bit. S and L are actually multipliers. If you have a 0.75 saturation, multiply that by the saturation value. Add the H value to the base H value (normally 0 if no brightness or contrast has been applied).

Cliff Spradlin.3512:

I believe the following information is correct, but I’m going to have to check with other people to be sure:

The data for each color in the API represents a color shift from a base color to a new color. The base color for many dyes, including all guild emblem dyes, is RGB 128,26,26.

For guild emblems themselves, there are a few color masks such as the one here that can be used to define where the color gets applied on the emblem, and slight variances in the color that gets applied (by varying the base color).

Brightness should be added to or subtracted from each component of the color
Contrast should used as a multiplier for each component of the color ((color – 128) * contrast + 128)

Hue is a value from 0-360 degrees. Saturation and Lightness are both multipliers of the original S & L values.

The order of operations is:
1) Take the base (RGB) color
2) Apply brightness and contrast
3) Convert color to HSL space
4) Apply HSL shift
5) Convert color back to RGB space (this is the final color value)

http://dragonwatch.net/fancyemblemexperiment/ does most of this math already, using pixastic. The only thing it’s missing is brightness/contrast, which seem to be something that pixastic also supports.

I’ll make another update tomorrow to the API to make the values in the API match the values in this post.

OK – the API has been updated so that their values match the ones in this guide.

The Color API has been updated again with potentially more useful color values. Also, the JSON types were corrected. The colors now also only include the materials that are actually defined for them.

smiley.1438:

Cliff Spradlin.3512:

Default is the default material. There is not necessarily a material-specific color defined for a dye. In this case, the default is used.

Does that also mean that the default color is not always specified? That would explain this:

126: {
  name: "Hot Pink",
    default: {
    brightness: "128",
    contrast: "128",
    hue: "0",
    saturation: "128",
    lightness: "128"
  },
...

…or did i get you completely wrong?

Yes, that’s right. I’m going to update the API to only show the materials that are actually defined.

smiley.1438:

I somehow get the feeling that “default” refers to the base color Cliff mentioned above since these are the same values for a lot of colors.

Default is the default material. There is not necessarily a material-specific color defined for a dye. In this case, the default is used.

In the quoted dye, the color is actually not black, only the actual material colors are black. I’m still working on more detailed information on how to convert the colors to RGB.

I believe the following information is correct, but I’m going to have to check with other people to be sure:

The data for each color in the API represents a color shift from a base color to a new color. The base color for many dyes, including all guild emblem dyes, is RGB 128,26,26.

For guild emblems themselves, there are a few color masks such as the one here that can be used to define where the color gets applied on the emblem, and slight variances in the color that gets applied (by varying the base color).

Brightness should be added to or subtracted from each component of the color
Contrast should used as a multiplier for each component of the color ((color – 128) * contrast + 128)

Hue is a value from 0-360 degrees. Saturation and Lightness are both multipliers of the original S & L values.

The order of operations is:
1) Take the base (RGB) color
2) Apply brightness and contrast
3) Convert color to HSL space
4) Apply HSL shift
5) Convert color back to RGB space (this is the final color value)

http://dragonwatch.net/fancyemblemexperiment/ does most of this math already, using pixastic. The only thing it’s missing is brightness/contrast, which seem to be something that pixastic also supports.

I’ll make another update tomorrow to the API to make the values in the API match the values in this post.

The guild API has been updated. Emblem information is now easier to parse.

Killer Rhino.6794:

Question #1: How should we be interpreting the color numbers (i.e., hue might be a value in degrees out of 360?)

Edit: I really, really tried to find this all out on the web, but the inconsistency with the number just didn’t make sense. thanks for any info you can provide.

Sorry about the confusion! The API was showing color values that had been partially transformed. I updated the API to show their original values. The colors are in HSL color space.

I also added localized text names so that it’s easier to identify colors.

Does this clear things up for you?

The Color API has been updated. The color values have been improved to be easier to use, and localized text names for the colors were added. The API Documentation was updated to reflect these changes.

We made the color API an associative array as a result of this thread: https://forum-en.gw2archive.eu/forum/community/api/API-Request-Results-as-map-id-details/first

What programming language do you have trouble accessing the keys? In javascript it should be as simple as “for(var key in obj) {}”

The APIs have been updated with the following changes:

• New Guild API (see API Documentation for details)
• Item discovery has been improved, so hopefully any missing item issues will be resolved
• Added recipe restrictions and flags to recipe_details.json.
• Added start_time and end_time to wvw/matches.json
• In item_details.json:
  • output has been improved so that null properties are more easily interpreted. See https://forum-en.gw2archive.eu/forum/community/api/Possible-issue-with-buff-property for details.
  • infusion slots now show the item_id of the infusion instead of the full item details.
• Added minor new APIs for getting the current build number and color / dye information. (see API Documentation for details)

In principle, we should version the API for breaking changes like the ones to item_details.json. For now we’re not doing that. We apologize for any inconvenience.

Terrasque.8735:

Yeah, I was wondering because I rarely see those in-game.

I tried to find out what triggered them, and it looks like the wiki have all of them flagged as bugged:

http://wiki.guildwars2.com/wiki/Prove_you_know_a_lot_about_Destiny%27s_Edge
http://wiki.guildwars2.com/wiki/Stop_the_bandit_thief_from_stealing_the_pumphouse_blueprints
http://wiki.guildwars2.com/wiki/Drive_the_rogue_bull_back_home,_and_fix_any_mayhem_on_the_way
http://wiki.guildwars2.com/wiki/Bandits_have_constructed_a_roadblock_to_stop_Shaemoor_traffic

The live response team checked up on this. One of the events listed has a bug, but the others just haven’t met required pre-conditions to start.

Thanks for the detailed report!

I talked to the item designers about this.

They agree with you that it’s strange, and they say it was a mistake made when designing the item. As you probably know, since guardians and warriors are the only ones who can use that item anyways, there’s no effective difference in how the item works.

Anyways, thanks for bringing this to our attention

NachoCheese.3084:

That way I can simply use the event_id to immediately find the details I need, rather than parse through the list to find an integer index, and use that for the rest of my process.

Yeah, I see why you’d want to do this. As you said, if we provide a complete event list it’s a problem to present the data in your proposed format since there are duplicate keys. I think that some people solve this problem by writing a search function, rather than by transforming the data.

For the ‘names’ APIs, we probably should have implemented them the way you said. I think I just expected people to basically load these into a table, rather than query the data directly.

We have a 3rd party app policy located here: https://forum-en.gw2archive.eu/forum/support/account/Policy-3rd-Party-Programs-Multi-Boxing-Macros/first.

This policy was written before we had APIs available, and needs to be updated to make it clear that we encourage app development and usage. We realize that in its current form it can be hard to figure out what is acceptable.

Our hope is that the new policy will make it very clear what is acceptable, so that you don’t have to worry about getting banned by using an app. The new policy is still being written, and we will update you when it’s ready.

It’s our intent to allow API-derived apps like GW2Stuff’s overlay to be used by players. From our perspective, having an overlay is just a different way of presenting content. We are not currently banning players simply for using overlays, and have no plans to do so.

I’m writing this in response to a lot of suggestions posted that have a similar theme.

Some examples:

• “The WvW match detail API should return guild names, not just guild IDs.”
• “The event names API should return map IDs”
• “The recipe API should return item names, not just item IDs”

I totally understand the desire to be able to make just one API call and have it return exactly what you want. I’m going to first explain why it’s not always feasible with the current API implementation, and after that talk about some possible solutions to the problem.

While the API servers seem like a single endpoint from an external developer’s perspective, they actually consist of many backend servers that service different parts of the API. Different information is on different servers.

Lets use the WvW / guild name feature request as an example. There is a WvW server, and a guild server. The WvW server holds all the WvW information, which includes references to guilds (guild IDs). The WvW server does not report any information about guilds, their names, emblems, etc. because it is not authoritative for that information — the guild server is.

At the scale of Guild Wars 2, no single server can hold all the information about the game. Instead, the information is distributed amongst many different servers. In fact, there is not just one guild server, there are many guild servers. And likewise there are many WvW servers. It’s very difficult to keep the same information in-sync between all these different servers reliably, so it’s much easier for the servers to hold references to the information, and then ask the authoritative server for details if details are needed.

So if we wanted to show guild names as part of the WvW match results, the WvW API server has to query the guild server for that information. Then we’d have to decide on a retention policy for that information — theoretically guild names can change. Should we send the query each time a WvW API request comes in, or should we try to cache the information on the WvW API server? Either way, it adds a significant amount of complexity to the WvW API server.

That leads to the next problem, which is deciding which information to include. First, there was a request for guild name and guild tag — but there’s also been a request for guild emblems to be included. So should we include those in the WvW match results too? What if somebody doesn’t want the guild emblems, they only want the guild name or guild ID because they already have downloaded information about the guild before? Should they be forced to waste bandwidth and time processing information they already got before?

By the way, objective names and details have the same problem — the WvW API server only knows about objective IDs, not objective names. The objective names are defined in our game localization files. We have another server that parses the localization files, called the Content server. When you ask for objective names, you’re actually querying the Content servers for that data.

Hopefully you can see the pattern here. The point is it’s much simpler (for us) to write API servers to return just the information they know, and for you to connect the information from the different APIs together. The simpler it is for us to write APIs, the more APIs we can create for you.

As I said before, I completely understand the desire to make a single API call and get everything you want. There are some attempts at solutions to this problem. YQL ( http://developer.yahoo.com/yql/ ) is an example. YQL is a SQL-like query language that can join and filter the results of different web APIs together. So you could write something like this in YQL:

“SELECT objective_id, match_id, guild_name FROM gw2_wvw JOIN gw2_guilds ON (gw2_wvw.guild_id = gw2_guilds.guild_id) WHERE gw2_wvw.world_id = 1001”

Facebook offers similar functionality to their data using a similar system called FQL.

I consider these types of interfaces to be a new layer on top of our existing API servers. They’re nice to have, but their only functional advantage is that they make the APIs easier to use and reduce the number of API calls made.

We’re currently focused on creating new APIs, because new APIs will enable new cool applications. Maybe once we have lots of cool APIs, we can spend some time on these nice API wrapper layers.

I hope this was helpful. Thanks for reading!

Terrasque.8735:

They have been in Preparation since (at least) 21:10, and time is 21:55 locally here. Is this intended behavior?

Maybe.

It’s up to the event designer how to use the preparation state.

Sometimes (usually?) it is a short period of time that automatically completes as a result of NPCs talking to each other or getting in position. Other times an event may be waiting for a player to come by and activate it, such as the events triggered by talking to an NPC that has an event icon over their head.

It’s completely up to the designer how to use it, so for some events some totally different criteria may need to be met for the event to advance to the ‘active’ state.

rodadams.5963:

Should we get in the habit then of interpreting these lists as “items/recipes/events found since the last server reset”, which then, for some relatively rare event chains, could be a day or so before some world discovers it, and I could foresee some being every other week/etc.

No, this is just a side-effect of how the event API works. All types of discovery are persistent; discovery doesn’t reset after a build. During a new patch, some of the APIs can temporarily show fewer results than normal while the new servers come online, but this should quickly resolve itself.

rodadams.5963:

I have a script which dumps all the items and recipes to a local store. When I rerun it, it will download the list of ID’s, and then fetch any objects it didn’t have in the last run. I see 6-10 new items per day in recent days. I’d expect this to be asymptocially zero on non-patch days.

This is a good caching behavior.

rodadams.5963:

Is there any way to list what World(s) the Guild plays on?

I think so. I’ll look into it. Like you said, it might get kind of bloated with stale information.

rodadams.5963:

Are you planning on having a “guild list” api, like you did for items and recipes, such that all guilds are discoverable, or are you only allowing them to be linked to?

Not at the moment. For now you’ll need to get guild IDs as a result of something like the WvW status API.

smiley.1438:

While updating my local items database i’ve found 5 IDs (43245-43249) which were added today and return a “reply not message” error. What does that mean?

https://api.guildwars2.com/v1/item_details.json?item_id=43249

It means that a backend server wasn’t properly deployed as part of the update this morning. The issue has been resolved and the example item link now works for me.

Thanks for the report!

OK, so for the first guild API release, this is what I’m considering:

/v1/guild_details.json?guild_id=xxxx

Would return name, tag, and emblem data.

The emblem would be in the form
“%i, %i, %i, %i, %i, %i”
background ID, foreground ID, flags, color 0, color 1, color 2
flags define things like flip image horizontally or vertically

like “1,62,0,114,114,93”

At some point we’d like to be able to render images on our servers so that you don’t have to, but that’s not available yet. I know there are some emblem creator websites and apps already — is this enough information to feed into those so that you can generate emblems?

Also, if you have any other ideas for public information that would be useful that could go into this API, let me know. Your ideas for authenticated/private APIs are good — this thread will be a useful reference for when we have the ability to implement them.

After a new patch, the events list has to re-populate. At the moment there’s a bug where the initial state of an event is not correctly recorded until the event has been initiated on that world at least once. For now, treat missing events as ‘inactive’.

Thanks for the detailed report. We’ve filed a bug on this issue.

This can happen during the process of distributing a new patch of the game. That’s what happened in this case — the world names should be ok now. Also, events should have stabilized. Any events not in the list should be considered ‘inactive’.

This bug is now fixed — events should be correctly displaying the preparation state. You may find it much easier to track the status of some events now.

Any event that does not appear should be assumed to be inactive.

Some of the events in your list do appear in the status API: https://api.guildwars2.com/v1/events.json?event_id=A02AF725-BBFD-4892-8A22-F3D28171752C

Could you explain what you mean by unresponsive?

Gilgamesh.2561:

Concerning authenticated API and potential features: GW2 does not have any kind of in-game inspection. You can’t see other characters’ traits or gear details. Is it safe to say if you can’t do something currently in-game, such as inspect other players, that it won’t become exposed in an API until it is in-game?

Yes, you won’t have any additional access beyond what your character can already do.

Are there any examples of recipe names that are not just “{item name} – {item rarity}”?

Zarenda Mal.1364:

Hi, I discovered that there are a number of ingredients that have item_id values that are not present in the items list.

You’re right — good catch. We’ll fix this in a future update. Thanks for the bug report!

Right, there are no recipe names, just the names of the items produced.

Hi,

I don’t have much experience using JSON libraries that map to strongly-typed objects. We didn’t really design the API in mind with that use-case, so I’m not surprised that there are places where it breaks or doesn’t make sense.

Is it possible for you to use a more dynamically typed parser? If so, that may save you a lot of pain in the long-term.

The buff is supposed to be ‘null’, not an empty string, but it’s getting automatically converted in a backend server to be an empty string. My goal in specifying those types of properties was to make items more self-describing, so that you didn’t have to hunt through every item to try to figure out all the possible fields.

Maybe instead, I’ll remove the ‘null’ properties from being returned at all, and instead have a list of example items that use all the possible properties, per item type. Then developers can examine that list to figure out the properties they need to support.

How does that sound?

You’re right, there’s no point having a lang parameter for that API.

I’ve removed the reference to it in the documentation.

Thanks for pointing it out!

Those are currently the supported languages.

I’ve updated the documentation to reflect this.

Gilgamesh.2561:

With properly cached responses JavaScript is fine, you just have to set the “If-Modified-Since” header to avoid the round-trip.

ArenaNet doesn’t cache the JSON response though.

> Cache-Control:no-cache

Yeah, maybe we can set longer cache periods for more static content like the event names or item ids. I started by playing it safe, since I’ve been seeing sporadic reports of events being out-of-date and I suspect that this might be one of the causes.

Hi,

Could you please update the wiki with the current license information and link to the API documentation thread as the official version of the license for now?

The wiki may well be the best home for the API documentation, but lets do that one step at a time.

The APIs have been updated to set a Cache-Control header for dynamic content. The header is:

Cache-Control: no-cache

Sorry – server deployment went bad. Should be fixed now.

smiley.1438

several item names contain double spaces like: https://api.guildwars2.com/v1/item_details.json?item_id=1794&lang=fr

I don’t see any double spaces in this example. If any exist, it’s likely an issue in the original item data too.

smiley.1438

Some other items have HTML-like markup in their descriptions like https://api.guildwars2.com/v1/item_details.json?item_id=29175
Any strip_tags function should remove it, but it doesn’t look good or may break code if it’s not removed.

That’s intentional, though it should probably be better documented in the future since it’s a completely custom markup. If your goal is to re-create an item’s information box to look like it does in the game, you’ll need those tags to show the right color or style for the text.

Having errors map to more specific HTTP status code is a good idea, but the reality is that we have many more complex error codes than we can map to HTTP statuses, and the errors may originate from backend servers that have no knowledge of HTTP.

Generally the way error handling should work is this:

result = get(/v1/events.json?event=123);
if (result != 200) {
    error = parseJson(resultBody);
    if (error)
        showErrorToUser(error);
    return;
}

Our error handling policy is to try to show the original error information to the user instead of hiding it. If a user reports a bug and includes the error code, there’s a good chance that we will be able to figure out the problem.

In other words, if you have a web server that talks to our API and returns results to a web browser, and you receive an error from us, try to send that error to the browser instead of swallowing it and generating your own error.

OK, on a separate topic this thread made me realize that error 500 was a bad choice. I propose changing the APIs to return error 400 instead.