ArcGIS Coordinates and Projection

Use this skill for coordinate conversion, projection transformations, and spatial reference handling.

Important: The projection module is deprecated as of version 4.32 and geodesicUtils is deprecated as of version 4.33. Use the projectOperator and geometry operators instead. See the Deprecation Notice section for migration guidance.

Coordinate Conversion Component

Basic Coordinate Conversion

<arcgis-map basemap="topo-vector" center="-117.049, 34.485" zoom="12">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
</arcgis-map>

Coordinate Conversion Widget (Core API)

import CoordinateConversion from "@arcgis/core/widgets/CoordinateConversion.js";

const ccWidget = new CoordinateConversion({
  view: view
});

view.ui.add(ccWidget, "bottom-left");

Custom Coordinate Formats

import CoordinateConversion from "@arcgis/core/widgets/CoordinateConversion.js";
import Format from "@arcgis/core/widgets/CoordinateConversion/support/Format.js";

// Create custom format
const customFormat = new Format({
  name: "Custom XY",
  conversionInfo: {
    spatialReference: { wkid: 4326 },
    reverseConvert: (string) => {
      const parts = string.split(",");
      return [parseFloat(parts[0]), parseFloat(parts[1])];
    }
  },
  coordinateSegments: [
    { alias: "Lon", description: "Longitude", searchPattern: "X" },
    { alias: "Lat", description: "Latitude", searchPattern: "Y" }
  ],
  defaultPattern: "X°, Y°"
});

const ccWidget = new CoordinateConversion({
  view: view,
  formats: [customFormat]
});

Spatial Reference

Create Spatial Reference

import SpatialReference from "@arcgis/core/geometry/SpatialReference.js";

// By WKID
const wgs84 = new SpatialReference({ wkid: 4326 });
const webMercator = new SpatialReference({ wkid: 102100 });

// By WKT
const customSR = new SpatialReference({
  wkt: 'PROJCS["NAD_1983_StatePlane_California_VI_FIPS_0406_Feet"...'
});

Common Spatial References

// WGS 84 (Geographic)
const wgs84 = { wkid: 4326 };

// Web Mercator (Projected)
const webMercator = { wkid: 102100 };  // or 3857

// UTM Zone 11N
const utm11n = { wkid: 32611 };

// State Plane (example)
const statePlane = { wkid: 2230 };

Modern Projection Operator

Use the projectOperator for client-side coordinate projection (recommended).

Project Geometry

import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";

// Load projection engine (required before use)
await projectOperator.load();

// Project geometry to WGS84
const projectedGeometry = projectOperator.execute(geometry, {
  outSpatialReference: { wkid: 4326 }
});

Project with Geographic Transformation

import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";

await projectOperator.load();

// Project with specific transformation (e.g., NAD83 to WGS84)
const projectedGeometry = projectOperator.execute(geometry, {
  outSpatialReference: { wkid: 4326 },
  geographicTransformation: {
    steps: [{ wkid: 108190 }]  // NAD_1983_To_WGS_1984_5
  }
});

Check Available Transformations

import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";

await projectOperator.load();

// Get available transformations between spatial references
const transformations = projectOperator.getTransformations(
  { wkid: 4269 },  // NAD83
  { wkid: 4326 }   // WGS84
);

console.log("Available transformations:", transformations);

Modern Geometry Operators

Use geometry operators for geodesic calculations (recommended).

Geodesic Distance

import geodesicDistance from "@arcgis/core/geometry/operators/geodesicDistanceOperator.js";

// Calculate geodesic distance between two points
const distance = geodesicDistance.execute(point1, point2, {
  unit: "kilometers"
});

Geodesic Area

import geodesicArea from "@arcgis/core/geometry/operators/geodesicAreaOperator.js";

const area = geodesicArea.execute(polygon, {
  unit: "square-kilometers"
});

Geodesic Length

import geodesicLength from "@arcgis/core/geometry/operators/geodesicLengthOperator.js";

const length = geodesicLength.execute(polyline, {
  unit: "kilometers"
});

Geodesic Buffer

import geodesicBuffer from "@arcgis/core/geometry/operators/geodesicBufferOperator.js";

const buffer = geodesicBuffer.execute(point, {
  distance: 100,
  unit: "kilometers"
});

Geodesic Densify

import geodesicDensify from "@arcgis/core/geometry/operators/geodesicDensifyOperator.js";

const densifiedLine = geodesicDensify.execute(polyline, {
  maxSegmentLength: 10000,  // meters
  unit: "meters"
});

Geometry Service Projection

Server-Side Projection

import geometryService from "@arcgis/core/rest/geometryService.js";
import ProjectParameters from "@arcgis/core/rest/support/ProjectParameters.js";

const gsUrl = "https://utility.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer";

const params = new ProjectParameters({
  geometries: [geometry],
  outSpatialReference: { wkid: 4326 }
});

const results = await geometryService.project(gsUrl, params);
const projectedGeometry = results[0];

Coordinate Conversion Utilities

Convert Coordinates

import webMercatorUtils from "@arcgis/core/geometry/support/webMercatorUtils.js";

// Web Mercator to Geographic
const geographicPoint = webMercatorUtils.webMercatorToGeographic(webMercatorPoint);

// Geographic to Web Mercator
const webMercatorPoint = webMercatorUtils.geographicToWebMercator(geographicPoint);

// Check if can project
const canProject = webMercatorUtils.canProject(fromSR, toSR);

Display Coordinates

Show Mouse Coordinates

view.on("pointer-move", (event) => {
  const mapPoint = view.toMap({ x: event.x, y: event.y });

  if (mapPoint) {
    document.getElementById("coords").textContent =
      `Lat: ${mapPoint.latitude.toFixed(6)}, Lon: ${mapPoint.longitude.toFixed(6)}`;
  }
});

Format Coordinates

import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

await coordinateFormatter.load();

// To Degrees Minutes Seconds
const dms = coordinateFormatter.toLatitudeLongitude(
  point,
  "dms",  // or "dm", "dd"
  3       // decimal places
);
// Output: "34°29'06.000\"N 117°02'56.400\"W"

// To MGRS
const mgrs = coordinateFormatter.toMgrs(
  point,
  "automatic",  // conversion mode
  5,            // precision
  false         // add spaces
);
// Output: "11SNU1234567890"

// To UTM
const utm = coordinateFormatter.toUtm(
  point,
  "north-south-indicators",
  true  // add spaces
);
// Output: "11S 500000 3800000"

// From string to point
const pointFromDMS = coordinateFormatter.fromLatitudeLongitude(
  "34°29'06\"N 117°02'56\"W"
);

USNG and MGRS

USNG Conversion

import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

await coordinateFormatter.load();

// To USNG
const usng = coordinateFormatter.toUsng(point, 5, false);

// From USNG
const point = coordinateFormatter.fromUsng("11SNU1234567890");

Complete Example

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
  <script src="https://js.arcgis.com/4.34/"></script>
  <script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>
  <style>
    html, body { height: 100%; margin: 0; }
    #coordsPanel {
      position: absolute;
      bottom: 50px;
      right: 10px;
      background: white;
      padding: 10px;
    }
  </style>
</head>
<body>
  <arcgis-map basemap="topo-vector" center="-117.049, 34.485" zoom="12">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
    <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
  </arcgis-map>

  <div id="coordsPanel" class="esri-widget">
    <div id="latlon">Move mouse to see coordinates</div>
    <div id="utm"></div>
    <div id="mgrs"></div>
  </div>

  <script type="module">
    import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

    await coordinateFormatter.load();

    const viewElement = document.querySelector("arcgis-map");
    await viewElement.viewOnReady();

    viewElement.addEventListener("arcgisViewPointerMove", (event) => {
      const point = viewElement.view.toMap({
        x: event.detail.x,
        y: event.detail.y
      });

      if (point) {
        document.getElementById("latlon").textContent =
          `Lat/Lon: ${point.latitude.toFixed(6)}, ${point.longitude.toFixed(6)}`;

        document.getElementById("utm").textContent =
          `UTM: ${coordinateFormatter.toUtm(point, "north-south-indicators", true)}`;

        document.getElementById("mgrs").textContent =
          `MGRS: ${coordinateFormatter.toMgrs(point, "automatic", 5, true)}`;
      }
    });
  </script>
</body>
</html>

Common Pitfalls

1. Load projection engine: Must call projectOperator.load() before using

2. Coordinate order: Geographic is (lon, lat), not (lat, lon)

3. WKID vs WKT: Use WKID when available, WKT for custom projections

4. Datum transformations: May be needed for accurate results between datums

5. Client vs server: Use client-side for speed, server for complex transformations

Deprecated APIs

DEPRECATED: The APIs below are deprecated. Use the modern alternatives shown above.

Migration Guide

Legacy projection Module (Deprecated since 4.32)

// DEPRECATED - Use projectOperator instead
import projection from "@arcgis/core/geometry/projection.js";

await projection.load();

const projectedGeometry = projection.project(
  geometry,
  new SpatialReference({ wkid: 4326 })
);

Legacy geodesicUtils (Deprecated since 4.33)

// DEPRECATED - Use geodesicDistanceOperator instead
import geodesicUtils from "@arcgis/core/geometry/support/geodesicUtils.js";

const distance = geodesicUtils.geodesicDistance(
  point1,
  point2,
  "kilometers"
);