Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/opsdashboard
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Object: esri/geometry/coordinateFormatter
[ AMD Module Require | Legacy Module Require ]
require(["esri/geometry/coordinateFormatter"], function(coordinateFormatter) { /* code goes here */ });
Description
(Added at v3.24)
This module converts between points and formatted coordinate notation strings such as:
- decimal degrees
- degrees, minutes, and seconds
- U.S. National Grid (USNG)
- Military Grid Reference System (MGRS).
Known Limitations
- The browser must support WebAssembly for this module to work.
- The methods that convert formatted strings to points expect the spatial reference parameter to be a geographic coordinate system.
- The methods that convert points to formatted strings expect the point's spatialReference to be a geographic coordinate system.
To use the conversion methods, the load() method must be called first if isLoaded() is
false.
coordinateFormatter.load().then(function(){
var point = coordinateFormatter.fromLatitudeLongitude("55 56 39.123N 003 09 43.034W");
});Samples
Search for samples that use this class.Methods
| Name | Return type | Summary | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| fromLatitudeLongitude(coordinates, spatialReference?) | Point | Parses coordinates in latitude/longitude notation, and returns a Point representing that location. | |||||||||||||||
| fromMgrs(coordinates, spatialReference, conversionMode) | Point | Parses coordinates in Military Grid Reference System (MGRS) notation, and returns a Point representing that location. | |||||||||||||||
| fromUsng(coordinates, spatialReference?) | Point | Parses coordinates in United States National Grid (USNG) notation, and returns a Point representing that location. The spatial reference provided must be a geographic coordinate system match the spatial reference used by the source of the USNG string. | |||||||||||||||
| fromUtm(coordinates, spatialReference, conversionMode) | Point | Parses coordinates in Universal Transverse Mercator (UTM) notation, and returns a Point representing that location. | |||||||||||||||
| isLoaded() | Boolean | Indicates if all dependencies of this module have been loaded. | |||||||||||||||
| isSupported() | Boolean | Indicates if this module is supported in the current browser. | |||||||||||||||
| load() | Promise | Loads this module's dependencies. | |||||||||||||||
| toLatitudeLongitude(point, format, decimalPlaces?) | String | 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. | |||||||||||||||
| toMgrs(point, conversionMode, precision?, addSpaces?) | String | 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. | |||||||||||||||
| toUsng(point, precision?, addSpaces?) | String | Returns formatted coordinates in United States National Grid (USNG) notation representing the given point's location. | |||||||||||||||
| toUtm(point, conversionMode, addSpaces?) | String | Returns formatted coordinates in Universal Transverse Mercator (UTM) notation representing the given point's location.
Example output for a point in the southern hemisphere:
|
Method Details
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 referenced as WGS84.
| Symbol | Character | Name | Unicode number | HTML code |
|---|---|---|---|---|
| Degree | * | Asterisk | U+002A | * |
| ^ | Circumflex Accent | U+005E | ^ | |
| ~ | Tilde | U+007E | ~ | |
| ° | Degree Sign | U+00B0 | ° | |
| Minute | ' | Apostrophe | U+0027 | ' |
| ′ | Prime | U+2032 | ′ | |
| Second | " | Quotation Mark | U+0022 | " |
The latitude/longitude string may contain leading and trailing whitespace, and may 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*
Return type:
PointParameters:
< |
Required | The latitude/longitude notation string for the coordinates. |
< |
Optional | A spatial reference for a geographic coordinate system that defines the datum and ellipsoid referenced by the latitude-longitude coordinates. If it is null, WGS84 will be used. |
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 that of 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
Return type:
PointParameters:
< |
Required | The MGRS notation string for the coordinates. |
< |
Required | A spatial reference for a geographic coordinate system that defines the datum and ellipsoid referenced by the MGRS coordinates. If it is null, WGS84 will be used. |
< |
Required | The mode used by the given MGRS coordinates. Known values: automatic | new-180-in-zone-01 | new-180-in-zone-60 | old-180-in-zone-01 | old-180-in-zone-60 |
Parses coordinates in United States National Grid (USNG) notation, and returns a Point representing that location.
The spatial reference provided must be a geographic coordinate system match the spatial reference 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
Return type:
PointParameters:
< |
Required | The USNG notation string for the coordinates. |
< |
Optional | A spatial reference for a geographic coordinate system that defines the datum and ellipsoid referenced by the USNG coordinates. |
Parses coordinates in Universal Transverse Mercator (UTM) notation, and returns a Point representing that location. The spatial reference provided must be a geographic coordinate system matching a spatial reference used by the source of the UTM string. If no spatial reference is provided, it is assumed the UTM string uses WGS84 spatial reference. 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)
Return type:
PointParameters:
< |
Required | The UTM notation string for the coordinates. |
< |
Required | A spatial reference for a geographic coordinate system that defines the datum and ellipsoid referenced by the UTM coordinates. If it is null, WGS84 will be used. |
< |
Required | The latitude notation scheme used by the given UTM coordinates, either a latitudinal band, or a hemisphere designator. Known values: latitude-band-indicators | north-south-indicators |
Indicates if this module is supported in the current browser. The browser must support WebAssembly.
Return type:
BooleanReturns 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, such as degrees, minutes, and seconds of each value. The precision of the output is controlled by both the
format and decimalPlaces parameters.
For example:
| Decimal places | Format | Example output | Angular precision | Approximate precision |
|---|---|---|---|---|
| 0 | dd | 056N 0003W | 1deg | 100km |
| 1 | dd | 55.9N 003.2W | 0.1deg | 10km |
| 2 | dd | 55.94N 003.16W | 0.01deg | 1km |
| 3 | dd | 55.944N 003.162W | 0.001deg | 100m |
| 0 | ddm | 55 057N 003 010W | 1min | 2km |
| 1 | ddm | 55 56.7N 003 09.7W | 0.1min | 200m |
| 3 | ddm | 55 56.650N 003 09.717W | 0.001min | 2m |
| 0 | dms | 55 56 039N 003 09 043W | 1 sec | 30m |
| 1 | dms | 55 56 39.1N 003 09 43.0W | 0.1sec | 3m |
| 2 | dms | 55 56 39.12N 003 09 43.03W | 0.01sec | 300mm |
| 3 | dms | 55 56 39.123N 003 09 43.034W | 0.001sec | 30mm |
Return type:
StringParameters:
< |
Required | The location to be represented as a formatted latitude/longitude string. The point's spatial reference should either be WGS84 or an another geographic coordinate system. |
< |
Required | The mode to use when formatting the latitude/longitude string. Known values: dd | ddm | dms |
< |
Optional | The number of decimal places to use, it should be an integer from 0 to 16. |
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:
| Precision | Added spaces | Example output | Approximate precision |
|---|---|---|---|
| 0 | false | 30UVG | 100km |
| 1 | false | 30UVG89 | 10km |
| 2 | false | 30UVG8999 | 1km |
| 3 | false | 30UVG898998 | 100m |
| 4 | false | 30UVG89889988 | 10m |
| 5 | false | 30UVG8988499881 | 1m |
| 0 | true | 30U VG | 100km |
| 1 | true | 30U VG 8 9 | 10m |
| 2 | true | 30U VG 89 99 | 1km |
| 3 | true | 30U VG 898 998 | 100m |
| 4 | true | 30U VG 8988 9988 | 10m |
| 5 | true | 30U VG 89884 99881 | 1m |
Return type:
StringParameters:
< |
Required | The location to be represented in MGRS notation. The point's spatial reference should either be WGS84 or an another geographic coordinate system. |
< |
Required | The mode to use for the returned MGRS notation string. Known values: automatic | new-180-in-zone-01 | new-180-in-zone-60 | old-180-in-zone-01 | old-180-in-zone-60 |
< |
Optional | The precision with which to represent the coordinates. It should be an integer from 0 to 8. |
< |
Optional | Indicates whether the generated strings contain no spaces. If false, the generated string has no spaces. If true, a space separates the grid zone designer, the 100km square identifier, and the numerical easting and northing values. |
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:
* When the point's spatial reference is based on NAD 27.
| Precision | Added spaces | Example output | Approximate precision |
|---|---|---|---|
| 0 | false | 13TFJ | 100km |
| 1 | false | 13TFJ25 | 10km |
| 2 | false | 13TFJ2359 | 1km |
| 3 | false | 13TFJ237595 | 100m |
| 4 | false | 13TFJ23745951 | 10m |
| 5 | false | 13TFJ2374359512 | 1m |
| 0 | true | 13T FJ | 100km |
| 1 | true | 13T FJ 2 5 | 10m |
| 2 | true | 13T FJ 23 59 | 1km |
| 3 | true | 13T FJ 237 595 | 100m |
| 4 | true | 13T FJ 2374 5951 | 10m |
| 5 | true | 13T FJ 23743 59512 | 1m |
| 4* | false | 13TFJ23795929 (NAD 27) | 10m |
| 2* | true | 13T FJ 23 59 (NAD 27) | 1km |
Return type:
StringParameters:
< |
Required | The location to be represented in USNG notation. The point's spatial reference should either be WGS84 or an another geographic coordinate system. |
< |
Optional | The precision with which to represent the coordinates. It should be an integer from 0 to 8. |
< |
Optional | Indicates whether the generated strings contain no spaces. If false, the generated string has no spaces. If true, a space separates the grid zone designer, the 100km square identifier, and the numerical easting and northing values. |
Returns formatted coordinates in Universal Transverse Mercator (UTM) notation representing the given point's location.
Example output for a point in the southern hemisphere:
| UTM conversion mode | Added spaces | Example output |
|---|---|---|
| latitude-band-indicators | false | 30U4898846199881 |
| latitude-band-indicators | true | 30U 489884 6199881 |
| north-south-indicators | false | 30N4898846199881 |
| north-south-indicators | true | 30N 489884 6199881 |
Return type:
StringParameters:
< |
Required | The location to be represented in UTM notation. The point's spatial reference should either be WGS84 or an another geographic coordinate system. |
< |
Required | The latitude notation scheme to use in the returned UTM notation string, either a latitudinal band, or a hemisphere designator. Known values: latitude-band-indicators | north-south-indicators |
< |
Optional | Indicates whether the generated strings contain no spaces. If false, the generated string has no spaces. If true, a space separates the UTM zone and latitude designator and each numerical easting and northing value. |