API:Maps

This page serves to provide some basic help on using the map system provided by the API. In a nutshell, map tiles are rendered using the tile service, and the map is then populated with data points from /v2/maps

Definitions

The map structure hierarchy is as follows:

1. continent - There are two available continents. These are Tyria (continent 1), and The Mists (continent 2).
2. floor - Each continent has several floors. Floors appear ingame via the page up/down controls on the world map. They effectively provide a z-axis.
3. region - Each floor may have many regions. For example, Kryta and the Maguuma Jungle are both regions within floor 1 of Tyria.
4. map - Each region contains different maps. For example, Kryta contains maps such as Queensdale and Kessex Hills.
5. marker types - These are the different icons and labels that appear for each map, such as waypoints, vistas or text labels.
6. coordinate - A coordinate is an [X,Y] position within a map.

A tile is a square 256 x 256 pixel image that forms part of the world map. When requesting tiles from the tile service, the continent_id, floor_id, x, y and zoom values are required.

The zoom level, which varies from 0-8 for Tyria and 0-6 in The Mists, determines how many tiles it takes to display the entire map. Increasing the zoom level by one doubles the number of tiles in each X and Y direction.

The continent dimensions, currently [81920, 114688] for Tyria and [16384, 16384] for The Mists, are specified in the top level of the continents endpoint along with the maximum and minimum zoom levels. They use the same units as the coordinate pairs.

Combining the zoom level with the continent dimensions allows you to calculate the scale of the visible map tiles (i.e. the number of coordinate-units per map-tile-pixel), and hence be able to position markers at any [X, Y] coordinate pair on the map.

Note

• Events (and Mumble, after first converting meters to inches) use a different coordinate system, referred to as "event coordinates" within the wiki API documentation. In order to convert "event coordinates" to "continent coordinates", the value of the "map_rect" array from the maps endpoint is required. A calculation example is provided here.

Continent coordinates

In the format [X,Y], map coordinates range from the northwest [0,0] point to the southeast [continent_xmax,continent_ymax] point. The continent size is provided by the response from /v2/continents. The current dimensions are [81920, 114688] for Tyria, and [16384, 16384] for The Mists.

Tyria

[0, 0]
Northwest

[81920, 0]
Northeast

Southwest
[0, 114688]

Southeast
[81920, 114688]

The Mists

[0, 0]
Northwest

[16384, 0]
Northwest

Southwest
[0, 16384]

Southeast
[16384, 16384]

Annotated example code

The following example uses the Leaflet JavaScript library.

JSFiddle using the code below

HTML

<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.0.0-rc.1/leaflet.js"></script>
<div id="mapdiv" style="width: 700px; height: 700px; background-color: red;"></div>

CSS

.leaflet-container { background: #000; }

Javascript

// Including the leaflet js library provides the variable L with various map tools, see "http://leafletjs.com/reference-1.0.0.html" for documentation

// Add leaflet css stylesheet (used for layer controls, marker styles and attribution)
$('<link>').appendTo('head').attr({type: 'text/css', rel: 'stylesheet', href: "https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.0.0-rc.1/leaflet.css" });

// This could be called anything, just bear in mind if you rename this then you need to rename anything with the prefix "map."
var map;

// Helper function to convert GW2 coordinates into Leaflet coordinates
//  GW2 coordinates: Northwest = [0,0], Southeast = [continent_xmax,continent_ymax];
//  Leaflet: Northwest = [0,0], Southeast = [-256, 256]
function unproject(coord) {
    return map.unproject(coord, map.getMaxZoom() );
}

// Helper function to print clicked coordinates to the log
function onMapClick(e) {
    console.log("You clicked the map at " + map.project(e.latlng,map.getMaxZoom()));
}

// Main map function
function createMap() {

    // Adds the leaflet map within the specified element, in this case a div with id="mapdiv"
    //  Additionally we set the zoom levels to match the tilelayers, and set the coordinate reference system (simple)
    //  In this case we're using the maximum zoom from Tyria as 8. It would be 6 for The Mists.
    map = L.map("mapdiv", {
        minZoom: 2,
        maxZoom: 8,
        crs: L.CRS.Simple
    });

    // Restrict the area which can be panned to
    //  In this case we're using the coordinates for the continent of tyria from "https://api.guildwars2.com/v2/continents/1"
    var continent_dims = [81920,114688];
    var mapbounds = new L.LatLngBounds(unproject([0,0]), unproject(continent_dims)); // northwest, southeast
    map.setMaxBounds(mapbounds);

    // Set the default viewport position (in this case the midpoint) and zoom (in this case zoom level 1)
    map.setView(unproject([(continent_dims[0] / 2),(continent_dims[1] / 2)]), 1);

    // Add a function to return clicked coordinates to the javascript console
    map.on("click", onMapClick);

    // Add a tile layer
    map.addLayer( L.tileLayer("https://tiles.guildwars2.com/1/1/{z}/{x}/{y}.jpg", { minZoom: 0, maxZoom: 7, continuousWorld: true, subdomains: [1,2,3,4], bounds: mapbounds }) );

    // Add some points to different marker groups
    L.marker(unproject([45136, 29864]), { title: "Temple of the Ages" }).addTo(map);
    L.marker(unproject([38714, 37092]), { title: "Arcane Council" }).addTo(map);
    L.marker(unproject([49704, 39984]), { title: "Fort Trinity Vista" }).addTo(map);

}
createMap();

Examples

• On the wiki:
  • Widget:Zone map v3
• External sites:
  • http://gw2timer.com/

Notes

• The size of continent 1 (Tyria) was updated with the release of Guild Wars 2: End of Dragons, from [49152, 49152] to [81920, 114688]. The [0, 0] northwest origin was moved at this time by 32768 units west and 16384 units north. Therefore, to correct from coordinates recorded prior to the End of Dragons release, add 32768 to x-coordinates and add 16384 to y-coordinates.

Trivia

• The ingame unit of measurement for distance is an inch. This means that a "1200 range skill" has a range of 1200 inches, or 100 feet.
• One coordinate unit is equivalent to a distance of 24 inches, or 2 feet. For example, this means that moving 1200 inches west ingame would change your position by 50 coordinate units.
  • Using a width for Tyria of 49152 coordinate units, the continent appears to be 18.6 miles (about 30 km) from east to west.