coordinateFormatter

require(["esri/geometry/coordinateFormatter"], function(coordinateFormatter) { /* code goes here */ });
Object: esri/geometry/coordinateFormatter
Since: ArcGIS API for JavaScript 4.7

Converts between points and formatted coordinates notation strings such as:

  • decimal degrees
  • degrees, minutes, and seconds
  • U.S. National Grid (USNG)
  • Military Grid Reference System (MGRS).

To use the conversion methods, the load() method must be called first if isLoaded() is false.

Known Limitations

Example:
// The latitude/longitude string to be converted
var latlon = "55 56 39.123N 003 09 43.034W"

// Load dependencies of "coordinateFormatter" module
coordinateFormatter.load().then(function() {
  // Once the promise returned by load() is resolved,
  // use the fromLatitudeLongitude() method to convert
  // latitude/longitude string to a point geometry.
  var point = coordinateFormatter.fromLatitudeLongitude(latlon);
});

Method Overview

NameReturn TypeSummaryObject
Point

Parses coordinates in latitude/longitude notation, and returns a Point representing that location.

more details
more detailscoordinateFormatter
Point

Parses coordinates in Military Grid Reference System (MGRS) notation, and returns a Point representing that location.

more details
more detailscoordinateFormatter
Point

Parses coordinates in United States National Grid (USNG) notation, and returns a Point representing that location.

more details
more detailscoordinateFormatter
Point

Parses coordinates in Universal Transverse Mercator (UTM) notation, and returns a Point representing that location.

more details
more detailscoordinateFormatter
Boolean

Indicates if all dependencies of this module have been loaded.

more details
more detailscoordinateFormatter
Boolean

Indicates if this module is supported in the current browser.

more details
more detailscoordinateFormatter
Promise

Load this module's dependencies.

more details
more detailscoordinateFormatter
String

Returns formatted coordinates in latitude/longitude notation representing the given point's location.

more details
more detailscoordinateFormatter
String

Returns formatted coordinates in Military Grid Reference System (MGRS) notation representing the given point's location.

more details
more detailscoordinateFormatter
String

Returns formatted coordinates in United States National Grid (USNG) notation representing the given point's location.

more details
more detailscoordinateFormatter
String

Returns formatted coordinates in Universal Transverse Mercator (UTM) notation representing the given point's location.

more details
more detailscoordinateFormatter

Method Details

fromLatitudeLongitude(coordinates, spatialReference){Point}static

Parses coordinates in latitude/longitude notation, and returns a Point representing that location. The coordinates may use decimal degrees, degrees and decimal minutes, or degrees, minutes, and seconds format. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the latitude/longitude string. If no spatial reference is provided, it is assumed the latitude/longitude coordinates are in WGS84.

Supported characters

SymbolCharacterNameUnicode numberHTML code
Degree*AsteriskU+002A*
^Circumflex AccentU+005E^
~TildeU+007E~
°Degree SignU+00B0°
Minute'ApostropheU+0027'
PrimeU+2032′
Second"Quotation MarkU+0022"

The latitude/longitude string may contain leading and trailing whitespace, and may also contain a space, comma, or vertical bar symbol to separate the latitude from the longitude. It may also contain the characters 'N', 'S', 'E' and 'W', or use a minus (-) symbol to indicate the hemisphere of each value.

Latitude/longitude notation examples:

  • 55 56 39.123N 003 09 43.034W
  • 55°56′39″N 3°09′43″W
  • 55~56.65205', -003~09.71723'
  • 55.9442008* | -3.1619539*
Parameters:
coordinates String

The latitude/longitude notation string for the coordinates.

spatialReference SpatialReference
optional

A spatial reference object representing a geographic coordinate system. If null, WGS84 will be used.

Returns:
TypeDescription
PointReturns a point with the location from the coordinates string in the spatial reference provided.
fromMgrs(coordinates, spatialReference, conversionMode){Point}static

Parses coordinates in Military Grid Reference System (MGRS) notation, and returns a Point representing that location. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the MGRS string. If no spatial reference is provided, it is assumed the MGRS string is referenced to WGS84.

Note that the choice between zone 01 and 60 has no impact when reading from an MGRS notation string. The MGRS string can contain leading and trailing whitespace and can have whitespace between the grid zone designator, the 100km square identifier, and the numerical eastings and northings.

MGRS notation examples:

  • 30UVG898998
  • 30UVG 89885 99877
Parameters:
coordinates String

The MGRS notation string for the coordinates.

spatialReference SpatialReference

A spatial reference object representing a geographic coordinate system referenced by the MGRS coordinates. If null, WGS84 will be used.

conversionMode String

The mode used by the given MGRS coordinates.

Possible Values: automatic | new-180-in-zone-01 | new-180-in-zone-60 | old-180-in-zone-01 | old-180-in-zone-60

Returns:
TypeDescription
PointReturns a point with the location from the MGRS string in the spatial reference provided.
fromUsng(coordinates, spatialReference){Point}static

Parses coordinates in United States National Grid (USNG) notation, and returns a Point representing that location.

The spatial reference provided must have an ellipsoid and datum matching those used by the source of the USNG string. If no spatial reference is provided and the USNG string is suffixed with "(NAD 27)", it is assumed the USNG string is referenced to NAD 27. If no spatial reference is provided and no such suffix exists, it is assumed the USNG string is referenced to WGS84.

USNG notation examples:

  • 13TFJ 23 59
  • 13TFJ2374159574
Parameters:
coordinates String

The USNG notation string for the coordinates.

spatialReference SpatialReference
optional

A spatial reference object representing a geographic coordinate system that the USNG coordinates are in. If null, WGS84 will be used.

Returns:
TypeDescription
PointReturns a point with the location from the USNG string in the spatial reference provided.
fromUtm(coordinates, spatialReference, conversionMode){Point}static

Parses coordinates in Universal Transverse Mercator (UTM) notation, and returns a Point representing that location. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the UTM string. If no spatial reference is provided, it is assumed the UTM string is referenced to WGS84. The UTM string can contain leading and trailing whitespace and can have whitespace between the zone and latitude designator and the numerical eastings and northings.

UTM notation examples:

  • 30U 489885 6199877
  • 30U4898856199877
  • 30N 489885 6199877 (using N/S indicator)
Parameters:
coordinates String

The UTM notation string for the coordinates.

spatialReference SpatialReference

A spatial reference object representing a geographic coordinate system that the UTM coordinates are in. If null, WGS84 will be used.

conversionMode String

The latitude notation scheme used by the given UTM coordinates, either a latitudinal band, or a hemisphere designator.

Possible Values: latitude-band-indicators | north-south-indicators

Returns:
TypeDescription
PointReturns a point with the location from the UTM string in the spatial reference provided.
isLoaded(){Boolean}

Indicates if all dependencies of this module have been loaded.

Returns:
TypeDescription
BooleanReturns true if this module's dependencies have been loaded.
isSupported(){Boolean}

Indicates if this module is supported in the current browser. The browser must support WebAssembly.

Returns:
TypeDescription
BooleanReturns true if this module is supported in the current browser.
load(){Promise}

Load this module's dependencies.

Returns:
TypeDescription
PromiseResolves when the dependencies have been loaded.
See also:
toLatitudeLongitude(point, format, decimalPlaces){String}static

Returns formatted coordinates in latitude/longitude notation representing the given point's location.

The latitude/longitude string will contain a space separating the latitude from the longitude value, and the characters 'N' or 'S', and 'E' and 'W', to indicate the hemisphere of each value. The string will also contain spaces separating the components (degrees, minutes, seconds) of each value. The precision of the output is controlled by both the format and decimalPlaces parameters.

For example:

Decimal placesformatExample outputAngular precisionApproximate precision
0dd056N 0003W1deg100km
1dd55.9N 003.2W0.1deg10km
2dd55.94N 003.16W0.01deg1km
3dd55.944N 003.162W0.001deg100m
0ddm55 057N 003 010W1min2km
1ddm55 56.7N 003 09.7W0.1min200m
2ddm55 56.65N 003 09.72W0.01min20m
3ddm55 56.650N 003 09.717W0.001min2m
0dms55 56 039N 003 09 043W1sec30m
1dms55 56 39.1N 003 09 43.0W0.1sec3m
2dms55 56 39.12N 003 09 43.03W0.01sec300mm
3dms55 56 39.123N 003 09 43.034W0.001sec30mm
Parameters:
point Point

The location to be represented as a formatted latitude/longitude string. The point's spatial reference should either be WGS84 or another geographic coordinate system.

format String

The mode to use when formatting the latitude/longitude string.

Possible Values: dd | ddm | dms

decimalPlaces Number
optional

The number of decimal places to use, it should be an integer from 0 to 16.

Returns:
TypeDescription
StringReturns a string representing the latitude/longitude of the given point.
toMgrs(point, conversionMode, precision, addSpaces){String}static

Returns formatted coordinates in Military Grid Reference System (MGRS) notation representing the given point's location.

Note that the choice between zone 01 and 60 has an impact only when generating the MGRS notation string for a point with longitude of exactly 180deg. The precision value controls the number of digits used to represent each numerical easting and northing value within the MGRS string.

For example:

precisionadd_spacesExample outputApproximate precision
0false30UVG100km
1false30UVG8910km
2false30UVG89991km
3false30UVG898998100m
4false30UVG8988998810m
5false30UVG89884998811m
0true30U VG100km
1true30U VG 8 910m
2true30U VG 89 991km
3true30U VG 898 998100m
4true30U VG 8988 998810m
5true30U VG 89884 998811m
Parameters:
point Point

The location to be represented in MGRS notation. The point's spatial reference should either be WGS84 or another geographic coordinate system

conversionMode String

The mode to use for the returned MGRS notation string.

Possible Values: automatic | new-180-in-zone-01 | new-180-in-zone-60 | old-180-in-zone-01 | old-180-in-zone-60

precision Number
optional

The precision with which to represent the coordinates, it should be an integer from 0 to 8.

addSpaces Boolean
optional

If false, the generated string will contain no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values.

Returns:
TypeDescription
StringReturns a MGRS notation string representing the position of the given point.
toUsng(point, precision, addSpaces){String}static

Returns formatted coordinates in United States National Grid (USNG) notation representing the given point's location. The precision value controls the number of digits used to represent each numerical easting and northing value within the USNG string.

For example:

precisionadd_spacesExample outputApproximate precision
0false13TFJ100km
1false13TFJ2510km
2false13TFJ23591km
3false13TFJ237595100m
4false13TFJ2374595110m
5false13TFJ23743595121m
0true13T FJ100km
1true13T FJ 2 510m
2true13T FJ 23 591km
3true13T FJ 237 595100m
4true13T FJ 2374 595110m
5true13T FJ 23743 595121m
4*false13TFJ23795929 (NAD 27)10m
2*true13T FJ 23 59 (NAD 27)1km

* When the point's spatial reference is based on NAD 27.

Parameters:
point Point

The location to be represented in USNG notation. The point's spatial reference should either be WGS84 or another geographic coordinate system.

precision Number
optional

The precision with which to represent the coordinates, it should be an integer from 0 to 8.

addSpaces Boolean
optional

If false, the generated string will contain no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values.

Returns:
TypeDescription
StringReturns a USNG notation string representing the position of the given point.
toUtm(point, conversionMode, addSpaces){String}static

Returns formatted coordinates in Universal Transverse Mercator (UTM) notation representing the given point's location.

Example output for a point in the southern hemisphere:

conversionModeadd_spacesExample output
latitude-band-indicatorsfalse30U4898846199881
latitude-band-indicatorstrue30U 489884 6199881
north-south-indicatorsfalse30N4898846199881
north-south-indicatorstrue30N 489884 6199881
Parameters:
point Point

The location to be represented in UTM notation. The point's spatial reference should either be WGS84 or another geographic coordinate system

conversionMode String

The latitude notation scheme to use in the returned UTM notation string, either a latitudinal band, or a hemisphere designator.

Possible Values: latitude-band-indicators | north-south-indicators

addSpaces Boolean
optional

If false, the generated string will contain no spaces. If true, a space separates the UTM zone and latitude designator and each numerical easting and northing value.

Returns:
TypeDescription
StringReturns a UTM notation string representing the position of the given point.

API Reference search results

NameTypeModule
Loading...