API:Maps

From Guild Wars 2 Wiki
Jump to: navigation, search

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-7 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 [49152, 49152] 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 use a different coordinate system, known as event coordinates, which are relative to the position of the map within the continent. In order to use the v1/event details endpoint, it must be combined with information stored within the v1/maps endpoint. See here for an example.

Map 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 [49152, 49152] for Tyria, and [16384, 16384] for The Mists.

Tyria
[0,0]
Northwest
[49152,0]
Northwest
Southwest
[0,49152]
Southeast
[49152,49152]
The Mists
[0,0]
Northwest
[16384,0]
Northwest
Southwest
[0,16384]
Southeast
[16384,16384]

https://files.gitter.im/arenanet/api-cdi/WSPA/image.png

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 7. It would be 6 for The Mists.
    map = L.map("mapdiv", {
        minZoom: 2,
        maxZoom: 7,
        crs: L.CRS.Simple
    });

    // Add map tiles using the [[API:Tile service]]
    L.tileLayer("https://tiles.guildwars2.com/1/1/{z}/{x}/{y}.jpg").addTo(map);

    // 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 = [49152,49152];
    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([12368, 13480]), { title: "Temple of the Ages" }).addTo(map);
    L.marker(unproject([5946, 20708]), { title: "Arcane Council" }).addTo(map);
    L.marker(unproject([16936, 23600]), { title: "Fort Trinity Vista" }).addTo(map);

}
createMap();

Examples

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 32768 coordinate units, the continent appears to be 12.4 miles (about 20 km) from east to west.