Optimal Path As Line

URL:: https://<root>/<serviceName>/RasterAnalysisTools/GPServer/OptimalPathAsLine
Methods:: GET
Version Introduced:: 10.8.1

Description

The OptimalPathAsLine task calculates the optimal path from a source to a destination as a feature.

To create paths that cross the edge of the projection, the rasters used as inputs for the Input Distance Accumulation Raster and Input Back Direction Raster parameters must have been created at the full global extent, in either a cylindrical projection or a geographic output coordinate system, while using the Geodesic option for the Distance Method parameter.

Example applications include the following:

Finding the optimal route for a new road
Finding the downstream trace from a location

Request parameters

Parameter Details

Parameter	Details
`inputDestinationRasterOrFeatures` (Required)	A raster or feature dataset that identifies the cells from which the optimal path is determined to the least costly source. If the input is a raster, 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: Use dark colors for code blocksCopy `1 2 3 4 5 //Portal item as input raster "inputDestinationRasterOrFeatures":{"itemId": <portal item Id>} //URL as input raster "inputDestinationRasterOrFeatures":{"url": <image service layer url>}` Feature input examples: Use dark colors for code blocksCopy `1 2 3 4 5 //Feature layer URL "inputDestinationRasterOrFeatures":{"url": <feature service layer url>} //Feature collection "inputDestinationRasterOrFeatures":{"layerDefinition": {}, "featureSet": {}}`
`inputDistanceAccumulationRaster` (Required)	Determines the optimal path from the sources to the destinations when a cost back direction raster is used 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: Use dark colors for code blocksCopy `1 2 3 4 5 //Portal item as input raster "inputDistanceAccumulationRaster":{"itemId": <portal item id>} //URL as input raster "inputDistanceAccumulationRaster":{"url": <image service layer url>}`
`inputBackDirectionRaster` (Required)	Determines the path to return to a source via the least-cost path or the optimal path. For each cell in the 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: Use dark colors for code blocksCopy `1 2 3 4 5 //Portal item as input raster "inputBackDirectionRaster":{"itemId": <portal item id>} //URL as input raster "inputBackDirectionRaster":{"url": <image service layer url>}`
`outputPolylineName` (Required)	The name of the output feature service that will contain the optimal path. The task will create a feature service of the results. You can define the name of the service. Output feature service examples: Use dark colors for code blocksCopy `1 2 3 4 5 //REST web example myOutput //REST scripting example "outputPolylineName" : "myOutput1"`
`destinationField`	The field used to obtain values for the destination locations. The input feature service must contain at least one valid integer field. Example: Use dark colors for code blocksCopy `1 "destinationField": destinationValue`
`pathType`	A string describing the path type, which can be `EACH_ZONE` , `BEST_SINGLE` , or `EACH_CELL` . `EACH_ZONE` —For each zone on the input destination data, an optimal path is determined and saved on the output raster. The optimal path for each zone begins at the cell with the lowest cost distance weighting in the zone. This is the default. `BEST_SINGLE` —For all cells on the input destination data, the optimal path is derived from the cell with the minimum of the least-cost paths to source cells. `EACH_CELL` —For each cell with valid values on the input destination data, an optimal path is determined and saved on the output raster. Each cell of the input destination data is treated separately, and a least-cost path is determined for each cell. Example: Use dark colors for code blocksCopy `1 "pathType": "EACH_ZONE"`
`createNetworkPaths`	Specifies whether complete, and possibly overlapping, paths from the destinations to the sources are calculated or if nonoverlapping network paths are created. Syntax: A Boolean value as either `true` or `false` . A value of `false` specifies complete paths from the destinations to the sources are calculated, which can be overlapping. This is the default. A value of `true` specifies nonoverlapping network paths are calculated. Example: Use dark colors for code blocksCopy `1 "createNetworkPaths": false`
`context`	Contains additional settings that affect task execution. Output Spatial Reference (`outSR` )—The output raster will be projected into the output spatial reference.
`f`	The response format. The default response format is `html` . Values: `html \| json \| pjson`

inputDestinationRasterOrFeatures

(Required)

A raster or feature dataset that identifies the cells from which the optimal path is determined to the least costly source.

If the input is a raster, 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:

Use dark colors for code blocksCopy
//Portal item as input raster
"inputDestinationRasterOrFeatures":{"itemId": <portal item Id>}

//URL as input raster
"inputDestinationRasterOrFeatures":{"url": <image service layer url>}

Feature input examples:

Use dark colors for code blocksCopy
//Feature layer URL
"inputDestinationRasterOrFeatures":{"url": <feature service layer url>}

//Feature collection
"inputDestinationRasterOrFeatures":{"layerDefinition": {}, "featureSet": {}}

inputDistanceAccumulationRaster

(Required)

Determines the optimal path from the sources to the destinations when a cost back direction raster is used 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:

Use dark colors for code blocksCopy
//Portal item as input raster
"inputDistanceAccumulationRaster":{"itemId": <portal item id>}

//URL as input raster
"inputDistanceAccumulationRaster":{"url": <image service layer url>}

inputBackDirectionRaster

(Required)

Determines the path to return to a source via the least-cost path or the optimal path.

For each cell in the 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:

Use dark colors for code blocksCopy
//Portal item as input raster
"inputBackDirectionRaster":{"itemId": <portal item id>}

//URL as input raster
"inputBackDirectionRaster":{"url": <image service layer url>}

outputPolylineName

(Required)

The name of the output feature service that will contain the optimal path.

The task will create a feature service of the results. You can define the name of the service.

Output feature service examples:

Use dark colors for code blocksCopy
//REST web example
myOutput

//REST scripting example
"outputPolylineName" : "myOutput1"

destinationField

The field used to obtain values for the destination locations.

The input feature service must contain at least one valid integer field.

Example:

Use dark colors for code blocksCopy
"destinationField": destinationValue

pathType

A string describing the path type, which can be EACH_ZONE , BEST_SINGLE , or EACH_CELL .

EACH_ZONE —For each zone on the input destination data, an optimal path is determined and saved on the output raster. The optimal path for each zone begins at the cell with the lowest cost distance weighting in the zone. This is the default.
BEST_SINGLE —For all cells on the input destination data, the optimal path is derived from the cell with the minimum of the least-cost paths to source cells.
EACH_CELL —For each cell with valid values on the input destination data, an optimal path is determined and saved on the output raster. Each cell of the input destination data is treated separately, and a least-cost path is determined for each cell.

Example:

Use dark colors for code blocksCopy
"pathType": "EACH_ZONE"

createNetworkPaths

Specifies whether complete, and possibly overlapping, paths from the destinations to the sources are calculated or if nonoverlapping network paths are created.

Syntax: A Boolean value as either true or false .

A value of false specifies complete paths from the destinations to the sources are calculated, which can be overlapping. This is the default.
A value of true specifies nonoverlapping network paths are calculated.

Example:

Use dark colors for code blocksCopy
"createNetworkPaths": false

context

Contains additional settings that affect task execution.

Output Spatial Reference (outSR )—The output raster will be projected into the output spatial reference.

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.

Use dark colors for code blocksCopy
{
  "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:

Use dark colors for code blocksCopy
https://<raster analysis tools url>/OptimalPathAsLine/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:

Use dark colors for code blocksCopy
https://<raster analysis tools url>/OptimalPathAsLine/jobs/<jobId>/results/outputOptimalPathAsLine

Example usage

Below is a sample request URL for OptimalPathAsLine .

Use dark colors for code blocksCopy
https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/OptimalPathAsLine/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 the following request:

Use dark colors for code blocksCopy
{
  "paramName":"outputPolylineFeatures",
  "dataType":"GPString",
  "value":{"url":"<hosted feature service layer url>"}
}

outputPolylineName is not provided in the following request:

Use dark colors for code blocksCopy
{
  "paramName":"outputPolylineFeatures",
  "dataType":"GPString",
  "value":{"layerDefinition": {}, "featureSet": {}}
}