Showing Highly Rated Posts By Cliff Spradlin.3512:

API Development Plans

in API Development

Posted by: Cliff Spradlin.3512

Cliff Spradlin.3512

Lead Programmer


First of all, I’m really happy to see all of your support for our new API system! We’re thrilled with how quickly you have adopted the APIs and created a huge variety of applications in an equally huge number of languages. Thank you so much for your support.

I wanted to give you an overview of our future development for the APIs. I hope that this information helps guide our conversations about potential new APIs. The currently released APIs are just the first step towards a much broader spectrum of API support.

We intentionally don’t have a roadmap for exactly which APIs we will create. Our plan is to use feedback and input from the community to help us choose which specific APIs to make. That said, we do have a longer term schedule that consists of technologies that will make more types of APIs possible.

We’re working on implementing OAuth2, a safe authentication system that will allow websites and applications to talk to our API on behalf of players without giving those apps your game password. For developers, this will involve signing up for an API key, getting a quota of API calls, etc. For users, there will be a new login flow where they authorize apps to take certain actions on their behalf.

OAuth2 support will enable many more personalized APIs to be created. Guild, Chat, Character, and other APIs are all possible. We don’t currently have a planned release date for OAuth2, but we’re actively working on implementing it.

So, when we’re talking about new APIs, keep this division in mind. If we talk about APIs that require authentication, those will need to wait until OAuth2 is ready. We can still talk about them, just keep the requirements for them in mind.

On the other hand, there are plenty of other unauthenticated APIs we can create now, and we should definitely talk about those!

Our immediate focus is on supporting the APIs that we just released — that means monitoring the servers, helping developers integrate with our API, improving our documentation, and fixing blocking bugs as quickly as possible.

At the same time, we’re listening to your suggestions and feedback, and we’re already at work on new APIs. I’m not ready to talk about them just yet, but we’re already working on some of the things you’ve been asking for.

PS. A suggestion about making suggestions — let’s try this. For each type of API (Guild, Items, etc.), let’s have one thread. Having multiple APIs discussed in one thread is pretty confusing on our forum, and will lead to very long threads that no-one will want to read. And conversely, if we have threads for each idea for an API, it would be too difficult to keep track of all of them. Maybe this will be a good middle ground.

(edited by Cliff Spradlin.3512)

API Documentation

in API Development

Posted by: Cliff Spradlin.3512

Cliff Spradlin.3512

Lead Programmer


Welcome to the API Development forum!

We’re really excited to share these APIs with you. There are already some amazing community apps and websites out there, and we hope that these APIs enhance them and enable new ones to be created.

This thread documents the currently available APIs for use. These APIs are in beta, so don’t be surprised if the interfaces change, but we will try to warn you if we have to make any breaking changes.

All currently available APIs are accessed using simple REST-style HTTP URLs.

API Terms:

These API’s are wholly owned by ArenaNet, LLC (“ArenaNet”). Any use of the API’s must comply with the Website Terms of Use and Content Terms of Use , however you may use the API’s to make commercial products so long as they are otherwise compliant and do not compete with ArenaNet. ArenaNet may revoke your right to use the API’s at any time. In addition, ArenaNet may create and/or amend any terms or conditions applicable to the API’s or their use at any time and from time to time. You understand and agree that ArenaNet is in the process of developing a full license agreement for these API’s and ArenaNet will publish it when it is complete. Your continued use of the API’s constitutes acceptance of the full license agreement and any related terms or conditions when they are posted.

Dynamic Events API – BETA

Optional parameters: world_id, map_id, event_id

This API returns an object with an “events” array. Each element contains the world_id, map_id, event_id, and state of an event. The ids can be translated to strings using the APIs listed below. The optional parameters can be used to filter the results to a desired scope of events.

The possible event states are:

  • Active – The event is running now
  • Inactive – The event is not running now
  • Success – The event has succeeded
  • Fail – The event has failed
  • Warmup – The event is waiting for certain criteria to be met before activating
  • Preparation – The criteria for the event to start have been met, but certain activities (such as an NPC dialogue) have not completed yet. After the activites have been completed, the event will become Active.

Optional parameters: lang

Each of these APIs takes an optional querystring parameter “lang”. So for example, if you go to /v1/world_names.json?lang=de the results will be returned in german.

Currently supported languages: en, fr, de, es

These APIs return a JSON array of ids to strings. The ids correspond to ids returned in the events.json API.

The region a world is in can be determined by its world_id:
1xxx – North America
2xxx – Europe

Optional parameters: event_id, lang

Returns detailed information about events. This includes their static starting location in the world. This location is not updated dynamically, so it’s only accurate for events that don’t move.


Returns the currently running WvW matches, and the world ids in each match. The match_id can be used with match_details.json API documented below.

Required parameter: match_id

Returns details about a match. This information includes the scores on each of the maps, and which team owns each objective. If an objective is held by a guild, the guild_id is also provided.

Optional parameter: lang

These APIs return a JSON array of ids to strings. The ids correspond to ids returned in the events.json API.

Item and Recipe Database API – BETA

Returns a list of all items discovered by players in the game.

Required parameter: item_id
Optional parameter: lang

This API takes an item_id and returns details about the item it represents. The format of the item details returned depends on the type of item represented. Some aspects of the item details will be present for all types of items, and some will be specific to specific item types.

Returns a list of all recipes discovered by players in the game.

Required parameter: recipe_id

This API takes an recipe_id and returns details about the recipe it represents.

Guild API – BETA

Required parameter: guild_id or guild_name

This API takes a guild_name or guild_id. It returns public data about a guild, including its name, tag, and emblem.

The emblem data is currently only the text metadata that can be used to compose the emblem. In the future, we may be able to provide the emblem as an image through this API, but that’s not currently possible.

The colors in emblem data are color IDs that represent an color value. The color IDs can be translated using the color API detailed below. Emblems use the ‘cloth’ material value in the color. We do not currently have an API to resolve foreground_id or background_id to more useful information about the images they represent.


Optional parameter: lang

Returns a list of continents, and information about each continent. This information is meant to be used in conjunction with the world map tile service, and with the map floor API.

Optional parameters: lang, map_id

Returns summary about one or all maps in the game. The summary contains information like the floors that a map is on, and translation data that can be used to translate world coordinates to map coordinates.

Required parameters: continent_id, floor
Optional parameter: lang

Returns detailed information about a map floor. This data can be used to populate a world map. Any coordinates provided have already been translated to map coordinates, which can be used in conjunction with the world map tile service.

The data provided currently only contains static content. Dynamic content, such as vendors, is not currently available.

Miscellaneous APIs – BETA

No parameters.

Returns the current build ID. This can be useful for a number of purposes, such as resetting event timers due to server restarts.

Optional parameter: lang

Returns all of the colors / dyes in the game, and their color component information.

Colors are represented in their original color shifting form (HSL + contrast/brightness) as well as in RGB form. An example of how to interpret the original form is here:

The exact color applied to an item depends on its material. The different color/material combinations are enumerated in the API for each color.

No parameters.

Returns a set of commonly requested in-game assets. These assets can be used to enhance API-derived applications. The results returned this API can be used to fetch assets from the Render service.

(edited by Cliff Spradlin.3512)