ArcGIS REST API

Determine Optimum Travel Cost Network

Determine Optimum Travel Cost Network diagram

The Determine Optimum Travel Cost Network task calculates the optimum cost network from a set of input regions.

Example applications include the following:

  • From a suitability model, you have identified 10 of the best habitat patches for bobcat. You want the bobcats to move between the patches through the most effective network of wildlife corridors to maintain genetic diversity within the metapopulation.
  • In a timber harvest, you want to create the most cost-efficient network of logging roads from which to extract the lumber.
  • In a military peacekeeping deployment, you have identified 5 areas to position troops and personnel. You want to develop the best network of supply routes between the bases.

The focus of the Determine Optimum Travel Network service is to define the optimum network of least-cost paths between regions. On the resulting network, the phenomenon can move from one region to any other region using the paths (possibly traveling through other regions).

The input to Determine Optimum Travel Network must be regions. A region is a connected series of cells (adjacent) with the same value. If you have disconnected cells with the same value, they are zones. Using zones as input to this task is not recommended. Determine Optimum Travel Network connects every region to every other region, so all regions, and all cells in the regions, can be reached through the resulting network.

Request URL

https://<raster analysis url>/DetermineOptimumTravelCostNetwork/submitJob

Request Parameters

The following table lists the parameters with syntax and details for each.

ParameterDescription

inputRegionsRasterOrFeatures

(Required)

The input regions that are to be connected by the least-cost network. Regions can be defined by either an image service or a feature service.

Raster input

Syntax: This parameter can be specified as a Portal Item ID, a URL to a raster image service layer, or a cloud raster dataset.

Domain: Integer raster

Examples:

  • "inputRegionsRasterOrFeatures":{"itemID": <portal item id>}
  • "inputRegionsRasterOrFeatures":{"url": <image service layer url>}

Feature input

Syntax: This parameter can be specified as one of the following:

  • A URL to a feature service layer
  • A feature collection

Examples:

  • "inputRegionsRasterOrFeatures":{"url": <feature service layer url>}
  • "inputRegionsRasterOrFeatures":{"layerDefinition": {}, "featureSet": {}}

inputCostRaster

(Required)

A raster defining the impedance or cost to move planimetrically through each cell.

The value at each cell location represents the cost-per-unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution while also compensating for diagonal movement to obtain the total cost of passing through the cell.

Syntax: This parameter can be specified as a Portal Item ID, a URL to a raster image service layer, or a cloud raster dataset.

Examples:

  • "inputCostRaster": {"itemId": <portal item id>}
  • "inputCostRaster": {"url": <image service layer url>}

outputOptimumNetworkName

(Required)

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

REST web example: myOutput

REST scripting example: "outputOptimumNetworkName" : "myOutput1"

outputNeighborNetworkName

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

REST web example: myOutput

REST scripting example: "outputNeighborNetworkName" : "myOutput2"

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 features will be projected into the output spatial reference.
  • Snap Raster (snapRaster)—The raster to which the cells of the input rasters will be aligned.
  • Cell Size (cellSize)—The cell size to which input feature regions will be rasterized, and what the input raster regions and cost surface will be resampled to.
  • Mask (mask)—Only input locations 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

Response

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

Syntax:

{
"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 url>/DetermineOptimumTravelCostNetwork/jobs/<jobId>

Accessing results

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 url>/jobs/<jobId>/results/featureLayer?token=<your token>&f=json

ParameterDescription

outputOptimumNetworkFeatures

The output optimum network feature item ID and URL.

Example:

{"url": 
"https://<analysis url>/DetermineOptimumTravelCostNetwork/jobs/<jobId>/results/outputDistanceRaster"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputOptimumNetworkName parameter provided in the initial request.

  • If outputOptimumNetworkName was provided, value contains the URL to the feature service layer.

    {
    "paramName":"resultLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputOptimumNetworkName was not provided, value contains a feature collection.

    {
    "paramName":"resultLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}}
    }

outputNeighborNetworkFeatures

The output neighbor network feature item ID and URL.

Example:

{"url": 
"https://<analysis url>/DetermineOptimumTravelCostNetwork/jobs/<jobId>/results/outputDistanceRaster"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputNeighborNetworkFeatures parameter provided in the initial request.

  • If outputNeighborNetworkFeatures was provided, value contains the URL to the feature service layer.

    {
    "paramName":"resultLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputNeighborNetworkFeatures was not provided, value contains a feature collection.

    {
    "paramName":"resultLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}}
    }