Distance

Description

The distance operation is performed on a geometry service resource. It reports the 2D Euclidean or geodesic distance between the two geometries.

At 10.1 and later, this operation calls simplify on the input geometry1 and geometry2 when the parameter geodesic is true.

You can provide arguments to the distance operation as query parameters defined in the following parameters table:

Request parameters

Parameter

Details

f

Description:  (Optional) The response format. The default response format is html.
Values:   html | json

geometry1

Description: The geometry from which the distance is to be measured. The structure of the geometry is same as the structure of the JSON geometry objects returned by the ArcGIS REST API. The use of simple syntax is not supported.

JSON structures:

Syntax:

{"geometryType" : "<esriGeometryPoint | esriGeometryPolyline | esriGeometryEnvelope | esriGeometryPolygon | esriGeometryMultipoint>","geometry" : <geometry1> }

Example:

{
  "geometryType" : "esriGeometryPoint",
  "geometry" : 
  {
    "x" : -118.15, "y" : 33.80
  }
}

geometry2

Description: The geometry to which the distance is to be measured. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. The use of simple syntax is not supported.

JSON structures

Syntax:

{"geometryType" : "<esriGeometryPoint | esriGeometryPolyline | esriGeometryEnvelope | esriGeometryPolygon | esriGeometryMultipoint>","geometry" : <geometry1> }

Example:

{
  "geometryType" : "esriGeometryPoint",
  "geometry" : 
  {
    "x" : -95.23, "y" : 31.71;
  }
}

sr

Description: The well-known ID or a spatial reference JSON object for input geometries. The spatial reference can be either a PCS or a GCS. For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.

distanceUnit

Description: (Optional) Specifies the units for measuring distance between the geometry1 and geometry2 geometries. For a list of valid units, see esriSRUnitType constants and esriSRUnit2Type constants.

For planar distance:

If distanceUnit is not specified, the distance is in the units of the given spatial reference. If distanceUnit is specified, the unit must be compatible with the given spatial reference. That is, if sr is a PCS, then distanceUnit must be linear. If sr is a GCS, then distanceUnit must be angular.

For geodesic distance:

If distanceUnit is not specified, the distance is measured in meters. If distanceUnit is specified, the unit must be linear.

geodesic

Description: (Optional) If geodesic is set to true, then the geodesic distance between the geometry1 and geometry2 geometries is returned. Geodesic distance is the shortest path between two points along the ellipsoid of the earth. If geodesic is set to false or not specified, the planar distance is returned. The default value is false.

Example usage

In this example, the geodesic distance in meters is computed between a polygon and a point.

http://sampleserver6.arcgisonline.com/arcgis/rest/services/Utilities/Geometry/GeometryServer/distance?sr=4326&geometry1={"geometryType":"esriGeometryPolygon","geometry":{"rings":[[[-117,34],[-117,35],[-116,35],[-116,34],[-117,34]]]}}&geometry2={"geometryType":"esriGeometryPoint","geometry":{"x":-115,"y":36}}&geodesic=true

JSON response syntax

{"distance" : <distance>}

JSON response example

{"distance": 143321.57818195896}