- 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:
Feature input examples: |
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:
Output raster examples:
|
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:
|
outputCellSize | The cell size that will be used 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:
|
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:
Output raster examples:
|
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:
Output raster examples:
|
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:
|
distanceMethod | Determines whether to calculate the distance using a planar (flat earth) or a geodesic (ellipsoid) method.
Example:
|
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:
Feature input examples:
|
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:
Output raster examples:
|
context | Contains additional settings that affect task processing. This task has the following settings:
|
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"
}
}