- URL:https://<rasteranalysistools-url>/CostPathAsPolyline
- Version Introduced:10.7.1
Description
The CostPathAsPolyline task calculates the least-cost path from a source to a destination.
Tip:
The Optimal Path As Line task provides enhanced functionality or performance.
Example applications include the following:
- Finding the least-cost route for a new road
- Routing drones around restricted air space
- Finding the downstream trace from a location
Request parameters
Parameter | Details |
---|---|
inputDestinationRasterOrFeatures (Required) | A raster or feature dataset that identifies those cells from which the least-cost path is determined to the least costly source. If the input is an image service, it must consist of cells that have valid values (zero is a valid value) for the destinations, and the remaining cells must be assigned NoData. 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:
|
inputCostDistanceRaster (Required) | The cost distance raster is used to determine the least-cost path from the sources to the destinations when you use a cost backlink raster for the direction input. The Euclidean distance raster is used to determine the path from the sources to the destinations when you use a Euclidean back direction raster for the direction input. Syntax: 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. Examples:
|
inputCostBacklinkRaster (Required) | The cost backlink raster is used to determine the path to return to a source via the least-cost path or the shortest path. For each cell in the backlink, back direction, or flow direction raster, a value identifies the neighbor that is the next cell on the path from the cell to a source cell. Syntax: 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. Raster input examples:
|
outputPolylineName (Required) | The task will create a feature service of the results. You can define the name of the service. Output feature service examples:
|
pathType | A string describing the path type, which can be either BEST_SINGLE, EACH_CELL, or EACH_ZONE.
Example:
|
destinationField | The field used to obtain values for the destination locations. The input feature service must contain at least one valid integer field. Example:
|
context | Contains additional settings that affect task execution.
|
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>/CostPathAsPolyline/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>/CostPathsAsPolyline/jobs/<jobId>/results/outputPolylineFeatures
Example usage
Below is a sample request URL for CostPathAsPolyline.
https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/CostPathAsPolyline/submitJob
JSON response example
The response returns the outputPolylineFeatures output parameter, which has properties for parameter name, data type, and value. The content of value depends on the outputPolylineName parameter being provided in the initial request. If outputPolylineName was provided, value contains the URL for the feature service layer. If outputPolylineName was not provided, value contains a feature collection.
outputPolylineName is provided in request:
{
"paramName": "outputPolylineFeatures",
"dataType": "GPString",
"value": {"url":"<hosted feature service layer url>"}
}
outputPolylineName is not provided in request:
{
"paramName":"outputPolylineFeatures",
"dataType":"GPString",
"value":{"layerDefinition": {}, "featureSet": {}}
}