ArcGIS REST API

Calculate Travel Cost

Calculate Travel Cost diagram

The Calculate Travel Cost task calculates the cost distance from a single source or set of sources, while accounting for surface distance and horizontal and vertical cost factors.

Example applications include the following:

  • Identify the least expensive route to construct a new road to a proposed school.
  • Connect the best habitat patches for bobcat with wildlife corridors to allow the species to move between the patches.
  • Calculate the actual cost and distance for a proposed road adjusting for the uphill and downhill changes in the landscape.

While the Calculate Distance task is the straight line—as the crow flies—distance between locations, the travel cost tools explore the movement of a traveler over a landscape. The Calculate Travel Cost task calculates the least accumulative cost distance for each cell to the source over a cost surface, while optionally accounting for the surface distance and the horizontal and vertical factors.

Request URL

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

Request Parameters

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

ParameterDescription

inputSourceRasterOrFeatures

(Required)

This is a raster or feature that identifies the cells or locations from or to which the least accumulated cost distance for every output cell location is calculated.

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:

  • "inputSourceRasterOrFeatures":{"itemID": <portal item id>}
  • "inputSourceRasterOrFeatures":{"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:

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

outputDistanceName

(Required)

The output distance image service name that will be created.

Syntax: A JSON object describes the name of the output or the output raster.

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.

Output name example:

"outputDistanceName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster examples:

"output
Name":{"itemId": <portal item id>}
"outputDistanceName":{"url": <image service url}
"outputDistanceName":{"serviceProperties": 
                         {"name":"testrasteranalysis",
                          "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, 
                          "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"}}

inputCostRaster

A raster defining the impedance or cost to move planimetrically through each 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>}

inputSurfaceRaster

A raster defining the elevation values at each cell location.

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:

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

maximumDistance

Defines the threshold that the accumulative cost values cannot exceed.

Syntax: A numerical value.

Example:

  • "maximimDistance": 10000

inputHorizontalRaster

A raster defining the horizontal direction at each 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:

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

horizontalFactor

Defines the relationship between the horizontal cost factor and the horizontal relative moving angle.

There are several factors with modifiers from which to select that identify a defined horizontal factor graph. Additionally, a table can be used to create a custom graph. The graphs are used to identify the horizontal factor used in calculating the total cost of moving into a neighboring cell.

In the explanations below, two acronyms are used: HF stands for horizontal factor, which defines the horizontal difficulty encountered when moving from one cell to the next; and HRMA stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction.

The following horizontal factor keywords are available:

  • BINARY—Indicates that if the HRMA is less than the cut angle, the HF is set to the value associated with the zero factor; otherwise, it is infinity.
  • FORWARD—Establishes that only forward movement is allowed. The HRMA must be greater or equal to 0 and less than 90 degrees (0 <= HRMA < 90). If the HRMA is greater than 0 and less than 45 degrees, the HF for the cell is set to the value associated with the zero factor. If the HRMA is greater than or equal to 45 degrees, the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity.
  • LINEAR—Specifies that the HF is a linear function of the HRMA.
  • INVERSE_LINEAR—Specifies that the HF is an inverse linear function of the HRMA.

Characteristics for the horizontal keywords are as follows:

  • Zero factor—Establishes the horizontal factor to be used when the HRMA is zero. This factor positions the y-intercept for any of the horizontal factor functions.
  • Cut angle—Defines the HRMA angle beyond which the HF will be set to infinity.
  • Slope—Establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR horizontal factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).
  • Side value—Establishes the HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees when the FORWARD horizontal factor keyword is specified.

The default values are as follows:

Keywords     Zero factor   Cut angle     Slope   Side value
--------------   -----------   -----------   -----   ---------
Binary           1.0            45           ~       ~
Forward          0.5            45 (fixed)   ~       1.0
Linear           0.5           181            1/90   ~
Inverse linear   2.0           180           -1/90   ~

The default is BINARY.

Syntax: This parameter is a string

Examples:

  • "horizontalFactor": "BINARY 1 30"
  • "horizontalFactor": "LINEAR 1 -60 60 0.02"

inputVerticalRaster

A raster defining the vertical (z) value for each 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:

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

verticalFactor

Defines the relationship between the vertical cost factor and the vertical relative moving angle.

There are several factors with modifiers from which to select that identify a defined vertical factor graph. Additionally, a table can be used to create a custom graph. The graphs are used to identify the vertical factor used in calculating the total cost for moving into a neighboring cell.

In the explanations of the vertical factor keywords below, two acronyms are used: VF stands for vertical factor, which defines the vertical difficulty encountered in moving from one cell to the next; and VRMA stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell.

  • BINARY—Specifies that if the VRMA is greater than the low-cut angle and less than the high-cut angle, the VF is set to the value associated with the zero factor; otherwise, it is infinity.
  • LINEAR—Indicates that the VF is a linear function of the VRMA.
  • SYMMETRIC_LINEAR—Specifies that the VF is a linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis.
  • INVERSE_LINEAR—Indicates that the VF is an inverse linear function of the VRMA.
  • SYMMETRIC_INVERSE_LINEAR—Specifies that the VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis.
  • COS—Identifies the VF as the cosine-based function of the VRMA.
  • SEC—Identifies the VF as the secant-based function of the VRMA.
  • COS_SEC—Specifies that the VF is the cosine-based function of the VRMA when the VRMA is negative and the secant-based function of the VRMA when the VRMA is nonnegative.
  • SEC_COS—Specifies that the VF is the secant-based function of the VRMA when the VRMA is negative and the cosine-based function of the VRMA when the VRMA is nonnegative.

Characteristics for the vertical keywords are as follows:

  • Zero factor—Establishes the vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zero factor is not applicable to any of the trigonometric vertical functions (COS, SEC, COS-SEC, or SEC-COS). The y-intercept is defined by these functions.
  • Low Cut angle—Defines the VRMA angle below which the VF will be set to infinity.
  • High Cut angle—Defines the VRMA angle above which the VF will be set to infinity.
  • Slope—Establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR vertical factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).

Syntax: This parameter is a string.

Examples:

  • "verticalFactor": "BINARY 1 30"
  • "verticalFactor": "LINEAR 1 -60 60 0.02"

sourceCostMultiplier

Multiplier to apply to the cost values.

Syntax: This parameter can be specified as a Double value or as a field.

Domain: Double, Field

Examples:

  • Double:

    "sourceCostMultiplier": 2

  • Field

    "sourceCostMultiplier": "sourceMult"

sourceStartCost

The starting cost from which to begin the cost calculations.

Syntax: This parameter can be specified as a Double value or as a field.

Domain: Double, Field

Examples:

  • Double:

    "sourceStartCost": 2.7

  • Field

    "sourceStartCost": "startCost"

sourceResistanceRate

This parameter simulates the increase in effort to overcome costs as the accumulative cost increases.

Syntax: This parameter can be specified as a Double value or as a field.

Domain: Double, Field

Examples:

  • Double:

    "sourceResistanceRate": 10

  • Field

    "sourceResistanceRate": "ResistanceRate"

sourceCapacity

Defines the cost capacity for the traveler for a source.

Syntax: This parameter can be specified as a Double value or as a field.

Domain: Double, Field

Examples:

  • Double:

    "sourceCapacity": 100

  • Field

    "sourceCapacity": "Capacity"

sourceTravelDirection

Defines the direction of the traveler when applying horizontal and vertical factors, the source resistance rate, and the source starting cost.

Syntax: A string describing the optimization method, which can be one of the following:

  • FROM_SOURCE—The horizontal factor, vertical factor, source resistance rate, and source starting cost will be applied beginning at the input source and moving out to the nonsource cells. This is the default.
  • TO_SOURCE—The horizontal factor, vertical factor, source resistance rate, and source starting cost will be applied beginning at each nonsource cell and moving back to the input source.

Example:

  • "sourceTravelDirection": "TO_SOURCE"

outputBacklinkName

The output back link image service name that will be created.

Syntax: A JSON object describes the name of the output or the output raster.

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.

Output name example:

"outputBacklinkName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster examples:

"outputBacklinkName":{"itemId": <portal item id>}
"outputBacklinkName":{"url": <image service url}
"outputBacklinkName":{"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.

Syntax: A JSON object describes the name of the output or the output raster.

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.

Output name example:

"outputAllocationName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster examples:

"outputAllocationName":{"itemId": <portal item id>}
"outputAllocationName":{"url": <image service url}
"outputAllocationName":{"serviceProperties":
                            {"name":"testrasteranalysis",
                             "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, 
                             "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"}}

allocationField

A field on theinputSourceRasterOrFeatures layer that holds the values that define each source.

It can be an integer or a string field of the source dataset.

Domain: Integer or string field

Default: Value

Example:

  • "allocationField": "Boundary1"

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

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>/CalculateTravelCost/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/rasterLayer?token=<your token>&f=json

ParameterDescription

outputDistanceRaster

The output distance raster item ID and URL.

Example:

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

The result has 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. For example:

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

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

outputBacklinkRaster

The output back link raster item ID and URL.

Example:

{"url": 
"https://<analysis url>/CalculateTravelCost/jobs/<jobId>/results/outputBacklinkRaster"}

The result has 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. For example:

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

outputAllocationRaster

The output allocation raster item ID and URL.

Example:

{"url": 
"https://<analysis url>/CalculateTravelCost/jobs/<jobId>/results/outputAllocationRaster"}

The result has 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. For example:

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