coordinateFormatter | References | ArcGIS Maps SDK for JavaScript

import { isLoaded, isSupported, load, fromLatitudeLongitude, fromMgrs } from "@arcgis/core/geometry/coordinateFormatter.js";

Since: ArcGIS Maps SDK 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

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 Point.spatialReference to be a geographic coordinate system.

Example

// Assign a latitude/longitude string to a const.
const latlon = "55 56 39.123N 003 09 43.034W";

// Load dependencies.
await coordinateFormatter.load();

// Use the `fromLatitudeLongitude` method to convert the latitude/longitude string to a point geometry.
const point = coordinateFormatter.fromLatitudeLongitude(latlon);

Type definitions

MgrsConversionMode

Type definition

Type: "automatic" | "new-180-in-zone-01" | "new-180-in-zone-60" | "old-180-in-zone-01" | "old-180-in-zone-60"

UtmConversionMode

Type definition

Type: "latitude-band-indicators" | "north-south-indicators"

Functions

Name	Return Type	Object
`MgrsConversionMode`
`UtmConversionMode`
`isLoaded`	`boolean`
`isSupported`	`boolean`
`load`	`Promise<void>`
`fromLatitudeLongitude`	`Point \| null \| undefined`
`fromMgrs`	`Point \| null \| undefined`
`fromUsng`	`Point \| null \| undefined`
`fromUtm`	`Point \| null \| undefined`
`toLatitudeLongitude`	`string \| null \| undefined`
`toMgrs`	`string \| null \| undefined`
`toUsng`	`string \| null \| undefined`
`toUtm`	`string \| null \| undefined`

isLoaded

Function

Indicates if all dependencies of this module have been loaded.

Signature: isLoaded (): boolean

Returns: boolean
Returns true if this module's dependencies have been loaded.

isSupported

Function

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

Signature: isSupported (): boolean

Returns: boolean
Returns true if this module is supported in the current browser.

load

Function

Load this module's dependencies.

See also

isLoaded()

Signature: load (): Promise<void>

Returns: Promise<void>
Resolves when the dependencies have been loaded.

fromLatitudeLongitude

Function

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

Symbol	Character	Name	Unicode number	HTML code
Degree	*	Asterisk	U+002A	*
	^	Circumflex Accent	U+005E	^
	~	Tilde	U+007E	~
	°	Degree Sign	U+00B0	°
	º	Masculine Ordinal Indicator	U+00BA	º
Minute	'	Apostrophe	U+0027	'
	′	Prime	U+2032	′
Second	"	Quotation Mark	U+0022	"
	″	Double prime	U+2033	″

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′39″N 3°09′43″W
55~~56.65205', -003~~09.71723'
55.9442008* | -3.1619539*

Signature: fromLatitudeLongitude (coordinates: string, spatialReference?: SpatialReference | null): Point | null | undefined

Parameters

Parameter	Type	Description	Required
coordinates	`string`	The latitude/longitude notation string for the coordinates.
spatialReference	`SpatialReference \| null`	A spatial reference object representing a geographic coordinate system. If `null`, WGS84 will be used.

Returns: Point | null | undefined
Returns a point with the location from the coordinates string in the spatial reference provided.

fromMgrs

Function

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

Signature: fromMgrs (coordinates: string, spatialReference: SpatialReference | null | undefined, conversionMode: MgrsConversionMode): Point | null | undefined

Parameters

Parameter	Type	Description
coordinates	`string`	The MGRS notation string for the coordinates.
spatialReference	`SpatialReference \| null \| undefined`	A spatial reference object representing a geographic coordinate system referenced by the MGRS coordinates. If `null`, WGS84 will be used.
conversionMode	`MgrsConversionMode`	The mode used by the given MGRS coordinates.

Returns: Point | null | undefined
Returns a point with the location from the MGRS string in the spatial reference provided.

fromUsng

Function

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

Signature: fromUsng (coordinates: string, spatialReference?: SpatialReference | null): Point | null | undefined

Parameters

Parameter	Type	Description	Required
coordinates	`string`	The USNG notation string for the coordinates.
spatialReference	`SpatialReference \| null`	A spatial reference object representing a geographic coordinate system that the USNG coordinates are in. If `null`, WGS84 will be used.

Returns: Point | null | undefined
Returns a point with the location from the USNG string in the spatial reference provided.

fromUtm

Function

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)

Signature: fromUtm (coordinates: string, spatialReference: SpatialReference | null | undefined, conversionMode: UtmConversionMode): Point | null | undefined

Parameters

Parameter	Type	Description
coordinates	`string`	The UTM notation string for the coordinates.
spatialReference	`SpatialReference \| null \| undefined`	A spatial reference object representing a geographic coordinate system that the UTM coordinates are in. If `null`, WGS84 will be used.
conversionMode	`UtmConversionMode`	The latitude notation scheme used by the given UTM coordinates, either a latitudinal band, or a hemisphere designator.

Returns: Point | null | undefined
Returns a point with the location from the UTM string in the spatial reference provided.

toLatitudeLongitude

Function

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' or '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 places	Format	Example output	Angular precision	Linear precision
0	dd	56N 003W	1°	~100km
1	dd	55.9N 003.2W	0.1°	~10km
2	dd	55.94N 003.16W	0.01°	~1km
3	dd	55.944N 003.162W	0.001°	~100m
0	ddm	55 57N 003 10W	1'	~2km
1	ddm	55 56.7N 003 09.7W	0.1'	~200m
2	ddm	55 56.65N 003 09.72W	0.01'	~20m
3	ddm	55 56.650N 003 09.717W	0.001'	~2m
0	dms	55 56 39N 003 09 43W	1"	~30m
1	dms	55 56 39.1N 003 09 43.0W	0.1"	~3m
2	dms	55 56 39.12N 003 09 43.03W	0.01"	~300mm
3	dms	55 56 39.123N 003 09 43.034W	0.001"	~30mm

Signature: toLatitudeLongitude (point: Point, format: LatitudeLongitudeFormat, decimalPlaces?: number): string | null | undefined

Parameters

Parameter	Type	Description
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	`LatitudeLongitudeFormat`	The mode to use when formatting the latitude/longitude string.
decimalPlaces	`number`	The number of decimal places to use, it should be an integer from 0 to 16.

Returns: string | null | undefined
Returns a string representing the latitude/longitude of the given point.

toMgrs

Function

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	add_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

Signature: toMgrs (point: Point, conversionMode: MgrsConversionMode, precision?: number, addSpaces?: boolean): string | null | undefined

Parameters

Parameter	Type	Description
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	`MgrsConversionMode`	The mode to use for the returned MGRS notation string.
precision	`number`	The precision with which to represent the coordinates, it should be an integer from 0 to 8.
addSpaces	`boolean`	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: string | null | undefined
Returns a MGRS notation string representing the position of the given point.

toUsng

Function

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:

precision	add_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

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

Signature: toUsng (point: Point, precision?: number, addSpaces?: boolean): string | null | undefined

Parameters

Parameter	Type	Description
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`	The precision with which to represent the coordinates, it should be an integer from 0 to 8.
addSpaces	`boolean`	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: string | null | undefined
Returns a USNG notation string representing the position of the given point.

toUtm

Function

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

Example output for a point in the southern hemisphere:

conversionMode	add_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

Signature: toUtm (point: Point, conversionMode: UtmConversionMode, addSpaces?: boolean): string | null | undefined

Parameters

Parameter	Type	Description
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	`UtmConversionMode`	The latitude notation scheme to use in the returned UTM notation string, either a latitudinal band, or a hemisphere designator.
addSpaces	`boolean`	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: string | null | undefined
Returns a UTM notation string representing the position of the given point.