Calculate Distance

• URL:https://<rasteranalysistools-url>/CalculateDistance
  
• Version Introduced:10.6

Description

The CalculateDistance task calculates the Euclidean distance, direction, and allocation from a single source or set of sources.

Tip:

The Distance Accumulation or Distance Allocation tasks provide enhanced functionality or performance.

Example applications include the following:

• What is the distance to the closest town?
• What is the distance to the closest road?
• What is the distance to the closest water source?

Request parameters

Parameter	Details
inputSource (Required)	The layer that defines the sources to calculate the distance to. The layer can be raster or feature. To use a raster input, it must be of type integer. Syntax: This parameter can have either a raster input or a feature input. For raster input, this parameter can be specified as a portal item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset. For feature input, this parameter can be specified as either a URL to a feature service layer or a feature collection. Raster input examples: //Portal item as input raster "inputSourceRasterOrFeatures":"itemID": <portal item id>} //URL as input raster "inputSourceRasterOrFeatures":{"url": <image service layer url>} //Cloud raster as input raster "inputSourceRasterOrFeatures": {"uri": <cloud raster dataset uri>} Feature input examples: //Feature layer URL "inputSourceRasterOrFeatures":{"url": <feature service layer url>} //Feature collection "inputSourceRasterOrFeatures":{"layerDefinition": {}, "featureSet": {}}
outputDistanceName (Required)	The output distance image service name that will be created. This calculates, for each cell, the Euclidean distance to the closest source. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter. Syntax: A JSON object describes the name of the output or the output raster. Output name example: "outputDistanceName": {"serviceProperties":{"name":"testrasteranalysis"}} Output raster examples: //Output portal item "outputDistanceName":{"itemId": <portal item id>} //Output URL "outputDistanceName":{"url": <image service url>} //Output raster layer service "outputDistanceName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff743b","folderId":""sdfwerfbd3ec25584d0d8f4"} }
maximumDistance	Defines the threshold that the accumulative distance values cannot exceed. If an accumulative Euclidean distance value exceeds this value, the output value for the cell location will be NoData. The default distance is to the edge of the output raster. Syntax: A linear unit specifying the distance and units. Supported units: Meters | Kilometers | Feet | Miles | FeetInt | MilesInt Example: "maximumDistance": {"distance":"60","units":"Meters"}
outputCellSize	Specifies the cell size to use for the output raster. Supported units: Meters | Kilometers | Feet | Miles | FeetInt | MilesInt The default value for this parameter is the same as the analysis environment. Example: "outputCellSize": {"distance":"60","units":"Meters"}
outputDirectionName	The output image service name that will be created. The output direction raster is in degrees and indicates the direction to return to the closest source from each cell center. The values on the direction raster are based on compass directions, with 0 degrees reserved for the source cells. Thus, a value of 90 means 90 degrees to the east, 180 is to the south, 270 is to the west, and 360 is to the north. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter. Syntax: A JSON object describes the name of the output or the output raster. Output name example: "outputDirectionName":{"serviceProperties":{"name":"testrasteranalysis"}} Output raster examples: //Output portal item "outputDirectionName":{"itemId": <portal item id>} //Output url "outputDirectionName":{"url": <image service url} //Output raster layer service "outputDirectionName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"} }
outputAllocationName	The output allocation image service name that will be created. This parameter calculates, for each cell, the nearest source based on Euclidean distance. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter. Syntax: A JSON object describes the name of the output or the output raster. Output name example: "outputAllocationName":{"serviceProperties":{"name":"testrasteranalysis"}} Output raster examples: //Output portal item "outputAllocationName":{"itemId": <portal item id>} //Output url "outputAllocationName":{"url": <image service url>} //Output raster layer service "outputAllocationName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ec255840d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"} }
allocationField	A field on the inputSourceRasterOrFeatures layer that holds the values that defines each source. It can be an integer or a string field of the source dataset. The default for this parameter is Value. Example: "allocationField": Boundary1
distanceMethod	Determines whether to calculate the distance using a planar (flat earth) or a geodesic (ellipsoid) method. Planar: The calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default method. Geodesic: Distances are calculated on the ellipsoid. Therefore, regardless of input or output projection, the results do not change. Example: "distanceMethod": "GEODESIC"
inputBarrierRasterOrFeatures	The layer that defines the barriers to calculate the back direction around. The layer can be raster or feature. Syntax: This parameter can have either a raster input or a feature input. For raster input, this parameter can be specified as a portal item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset. For feature input, this parameter can be specified as either a URL to a feature service layer or a feature collection. Raster input examples: //Portal item as input raster "inputBarrierRasterOrFeatures":"itemID": <portal item id>} //URL as input raster "inputBarrierRasterOrFeatures":{"url": <image service layer url>} //Cloud raster as input raster "inputBarrierRasterOrFeatures": {"uri": <cloud raster dataset uri>} Feature input examples: //Feature layer URL "inputBarrierRasterOrFeatures":{"url": <feature service layer url>} //Feature collection "inputBarrierRasterOrFeatures":{"layerDefinition": {}, "featureSet": {}}
outputBackDirectionName	The output back direction image service name that will be created. This parameter calculates, for each cell, the direction back to the source around barriers, if barriers are provided as input. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter. Syntax: A JSON object describes the name of the output or the output raster. Output name example: "outputBackDirectionName":{"serviceProperties":{"name":"testrasteranalysis"}} Output raster examples: //Output portal item "outputBackDirectionName":{"itemId": <portal item id>} //Output url "outputBackDirectionName":{"url": <image service url>} //Output raster layer service "outputBackDirectionName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ec255840d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"} }
context	Contains additional settings that affect task execution. This task has the following settings: Extent (extent): A bounding box that defines the analysis area. Output Spatial Reference (outSR): The output raster will be projected into the output spatial reference. Snap Raster (snapRaster): The output raster will have its cells aligned with the specified snap raster. Cell Size (cellSize): The output raster will have the resolution specified by cell size. Mask (mask): Only cells that fall within the analysis mask will be considered in the operation.
f	The response format. The default response format is html. Values: html | json | pjson

Response

When you submit a request, the task assigns a unique job ID for the transaction.

{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

After the initial request is submitted, you can use the jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, you use the jobId to retrieve the results. To track the status, you can make a request of the following form:

https://<raster analysis tools url>/CalculateDistance/jobs/<jobId>

When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form:

https://<raster analysis tools url>/CalculateDistance/jobs/<jobId>/results/<output parameter>

Example usage

Below is a sample request URL for CalculateDistance.

https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/CalculateDistance/submitJob

JSON Response syntax

The response returns the outputDistanceRaster, outputDirectionRaster, and outputAllocationRaster output parameters, which have properties for parameter name, data type, and value. The content of value is always the itemId of the output raster dataset and the image service URL.

{
  "paramName": <parameter name>,
  "dataType": "GPString",
  "value": {
    "itemId": <item Id>,
    "url": <URL>
  }
}

JSON Response example

{
  "paramName": "outputDistanceRaster",
  "dataType": "GPString",
  "value": {
    "itemId": "f121390b85ef419790479fc75b493efd",
    "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
  }
}