Skip to content

API Version 2

Version 2 (v2) of the Guild Wars 2 API was introduced to offer more flexibility over the previous version and introduces a more unified and structured approach for accessing resources.

Query Types

Generally, API endpoints are structured in two different ways: There are "blob"-style which simply return all data and indexed endpoints which can be queried for indexed data points.

Indexed endpoints support different types of queries that differ in supported query parameters. The response of an indexed endpoint depends on the query type used in a request. Common query types are:

  • querying IDs to get a full list of available IDs (e.g. /v2/items),
  • querying by ID to get a single data point by ID (e.g. /v2/items?id={id}),
  • querying by IDs to get the data points by a set of IDs (e.g. /v2/items?ids={ids; ","-separated}), and
  • querying by page to get a page of data points (/v2/items?page={index}&page_size={size}).

Querying by IDs

Some endpoints support a special version of this query type that can be used to retrieve all data points at once. This is achieved by passing all as value for the ids query parameter (e.g. /v2/legends?ids=all).

The amount of data points that can be requested in one request is limited to 200.

Querying by Page

Some endpoints support querying data points by page. Data points in such an endpoint are ordered by some arbitrary but consistent comparison. A page of data points can be though of as an offset chunk of these ordered data points.

The maximum page size is limited to 200. (This is consistent with the maximum amount of data points that can be retrieved when querying by IDs.)

When querying by page, the response contains a few additional non-standard headers that provide additional information:

  • The value of X-Page-Size is equal to the requested amount of data points per page,
  • the value of X-Page-Total is the total number of available pages for the current page size,
  • the value of X-Result-Count is the number of data points returned by the response, and
  • the value of X-Result-Total is the total number of available data points.

Warning

If supported by the desired endpoint, it is generally recommended to query the IDs explicitly and to query by IDs afterward. This approach avoids inconsistencies that can potentially occur if the page bounds are changed in between requests. (This can happen if, for example, a data point is added.)

Authentication

Version 2 added support for endpoints that provide account-specific data. To query one of the available resources, an API key must be used to authenticate the request.

An API key can be provided using the Authorization header:

$ curl -H "Authorization: Bearer <API key>" https://api.guildwars2.com/v2/tokeninfo

Alternatively, it is possible to use the access_token query parameter instead:

$ curl https://api.guildwars2.com/v2/tokeninfo?access_token=<API key>

Note

Passing the API key via header is recommended to prevent the key from leaking. While URLs are encrypted when using HTTPS, they should still be considered public as logging or storage (e.g. in a browser history) could expose them.

Permissions

When creating an API key, it is possible to select a set of permissions for the key. Authenticated endpoints may require different permissions. This provides players with a mechanism to limit which resources an application can access.

Warning

Some endpoints may return additional data depending the permissions of the used API key. In this case, the permissions are not strictly required for the endpoint and using keys without them results in no error.

Schema Versions

A schema version can be provided using the X-Schema-Version header:

$ curl -H "X-Schema-Version: <Schema version>" https://api.guildwars2.com/v2/tokeninfo

Alternatively, it is possible to use the v query parameter instead:

$ curl https://api.guildwars2.com/v2/tokeninfo?v=<Schema version>

Note

Passing a schema version via query parameter is recommended to aid in debugging and to simplify sharing of URLs.

A list of available schema versions can be found in version 2's meta endpoint along with a short description of each change.

Note

Querying the latest schema version is possible by passing latest as value for the version. However, this should be avoided as this may lead to unexpected response format changes in future updates.