Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Object: esri/geometry/webMercatorUtils

require(["esri/geometry/webMercatorUtils"], function(webMercatorUtils) { /* code goes here */ });

Description

(Added at v3.8)
Convert Web Mercator coordinates to geographic and vice versa.

When coding legacy (non-AMD) style, there is no need to require the module. All methods and properties are available in the namespace. For example, esri.geometry.geographicToWebMercator().

Samples

Search for samples that use this class.

Methods

NameReturn typeSummary
canProject(source, target)BooleanReturns true if the 'source' can be projected to 'target' by the project() function, or if the 'source' and 'target' is the same spatialReference.
geographicToWebMercator(geometry)GeometryConverts geometry from geographic units to Web Mercator units.
lngLatToXY(long, lat)Number[]Translates the given latitude and longitude values to Web Mercator.
project(geometry, target)ObjectProject the geometry clientside (if possible).
webMercatorToGeographic(geometry, isLinear?)GeometryConverts geometry from Web Mercator units to geographic units.
xyToLngLat(x, y)Number[]Translates the given Web Mercator coordinates to Longitude and Latitude.
Method Details

canProject(source, target)

Returns true if the 'source' can be projected to 'target' by the project() function, or if the 'source' and 'target' is the same spatialReference. (Added at v3.11)
Return type: Boolean
Parameters:
<SpatialReference | Object> source Required An input of type SpatialReference or an object with spatialReference property such as Geometry or Map.
<SpatialReference | Object> target Required The target spatial reference, of type SpatialReference or an object with spatialReference property such as Map.
Sample:
var pt = Point(0, 0), // a geographic point.
    result;
if (webMercatorUtils.canProject(pt, map)) {
  result = webMercatorUtils.project(pt, map);
}

geographicToWebMercator(geometry)

Converts geometry from geographic units to Web Mercator units.
Return type: Geometry
Parameters:
<Geometry> geometry Required The geometry to convert.
Sample:
require([
  "esri/geometry/webMercatorUtils", ... 
], function(webMercatorUtils, ... ) {
  var geom = webMercatorUtils.geographicToWebMercator(candidate.location);
  ...
});

lngLatToXY(long, lat)

Translates the given latitude and longitude values to Web Mercator.
Return type: Number[]
Parameters:
<Number> long Required The longitude value to convert. 
<Number> lat Required The latitude value to convert. 
Sample:
require([
  "esri/geometry/webMercatorUtils", ... 
], function(webMercatorUtils, ... ) {
  webMercatorUtils.lngLatToXY(-120, 33);
  ...
});

project(geometry, target)

Project the geometry clientside (if possible). (Added at v3.11)
Return type: Object
Parameters:
<Geometry> geometry Required An input geometry.
<SpatialReference | Object> target Required The target spatial reference, of type SpatialReference or an object with spatialReference property such as Map.
Sample:
var pt = Point(0, 0), // a geographic point.
    result;
if (webMercatorUtils.canProject(pt, map)) {
  result = webMercatorUtils.project(pt, map);
}

webMercatorToGeographic(geometry, isLinear?)

Converts geometry from Web Mercator units to geographic units.
Return type: Geometry
Parameters:
<Geometry> geometry Required The geometry to convert.
<Boolean> isLinear Optional Indicates whether to work with linear values, i.e., do not normalize. By default, this conversion method normalizes xmin and xmax values. If this is not desired, specify this value as true. Default value is false.
Sample:
require([
  "esri/geometry/webMercatorUtils", ... 
], function(webMercatorUtils, ... ) {
  query.geometry = webMercatorUtils.webMercatorToGeographic(geometries[0]);
  ...
});

xyToLngLat(x, y)

Translates the given Web Mercator coordinates to Longitude and Latitude. By default the returned longitude is normalized so that it is within -180 and +180.
Return type: Number[]
Parameters:
<Number> x Required The x coordinate value to convert.
<Number> y Required The y coordinate value to convert.
Sample:
require([
  "esri/geometry/webMercatorUtils", ... 
], function(webMercatorUtils, ... ) {
  var normalizedVal = webMercatorUtils.xyToLngLat(42215329, 1321748);
  console.log(normalizedVal); //returns 19.226, 11.789

  var value = webMercatorUtils.xyToLngLat(42215329, 1321748, true);
  console.log(value); // returns 379.22, 11.78
  ...
});