ArcGIS REST API

Calculate Distance

Calculate Distance diagram

The Calculate Distance task calculates the Euclidean distance, direction, and allocation from a single source or set of sources.

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 URL

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

Request Parameters

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

ParameterDescription

inputSource

(Required)

The layer that defines the sources to calculate the distance too. The layer can be raster or feature.

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.

Calculates, for each cell, the Euclidean distance to the closest source.

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:

"outputDistanceName":{"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"}}

maximumDistance

Calculates the maximum distance.

If no distance is provided, a default will be calculated that is based on the locations of the input sources.

Domain: Meters, Kilometers, Feet, Miles

Example:

  • "maximumDistance": {"distance":"60","units":"Meters"}

outputCellSize

Specifies the cell size to use for the output raster.

Domain: Meters, Kilometers, Feet, Miles

Default: Same as the analysis environment

Example:

  • "outputCellSize": {"distance":"60","units":"Meters"}

outputDirectionName

The output image service name that will be created.

The output direction raster is in degrees, and it indicates from each cell center the direction to go to return to the closest source. The values on the direction raster are based on compass directions, with 0 degrees reserved for the source cells (90 to the east, 180 to the south, 270 to the west, and 360 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.

Output name example:

"outputDirectionName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster examples:

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

Calculates, for each cell, the nearest source based on Euclidean distance.

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>/CalculateDistance/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

Replace rasterLayer with the particular output you are interested in.

ParameterDescription

outputDistanceRaster

The output distance raster item ID and URL.

Example:

{"url": 
"https://<analysis url>/CalculateDistance/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"
    }
}

outputDirectionRaster

The output direction raster item ID and URL.

Example:

{"url": 
"https://<analysis url>/CalculateDistance/jobs/<jobId>/results/outputDirectionRaster"}

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": "outputDirectionRaster",
    "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>/CalculateDistance/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"
    }
}