Flow Distance—REST APIs | Documentation for ArcGIS Enterprise

URL:https://<rasteranalysistools-url>/FlowDistance
Version Introduced:10.6

Description

Flow Distance diagram

The FlowDistance task computes the downslope horizontal or vertical distance to cells in a stream or river into which they flow. A flow direction raster can also be applied. In case of multiple flow paths, minimum, weighted mean, or maximum flow distance can be computed.

To limit downslope directions along which flow distance is measured, you can provide an optional input flow direction service that can be derived using the FlowDirection task. Choose from D8, D-Infinity (DINF), and multiple flow direction (MFD) flow models while generating an optional input flow direction service. Use the flowDirectionType parameter to specify which method was used when the flow direction raster was created.

If an optional input flow direction service is provided, it is recommended that it be created using the FlowDirection task, using the same input surface that you'll provide to the FlowDistance task. If this input surface is void of sinks, the distance measurements would be to stream cells represented by the input stream raster. If this input surface has sinks present, some flow paths can get terminated short by them flowing into sinks before reaching streams. In such cases, flow distance measurements for these cells are calculated only up to the sink cells into which they flow.

When FlowDistance is run with no optional flow direction input, flow distance is assessed considering all possible downslope flow paths from each cell to cell(s) on a stream into which they flow.

When task is run with an optional D8 flow direction raster, there is only one possible downslope path from every cell to a cell on the stream, and flow distance is measured along this single flow path.

When multiple flow paths exist from each cell to cells on the stream into which they flow, use the statisticsType to compute minimum, weighted mean, or maximum flow distance.

If there is only a single flow path from each cell to a cell on the stream, all statistics types produce the same result.

Request parameters


Parameter	Details
inputStreamRaster (Required)	An input raster that represents a linear stream network. 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: `//Portal item as input raster "inputStreamRaster": {"itemId": <portal item id>} //URL as input raster "inputStreamRaster": {"url": <image service layer url>}`
inputSurfaceRaster (Required)	The input raster representing a continuous surface. 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: `//Portal item as input raster "inputSurfaceRaster": {"itemId": <portal item id>} //URL as input raster "inputSurfaceRaster": {"url": <image service layer url>}`
outputName (Required)	The name of the output image service that will be created. 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. Syntax: A JSON object describes the name of the output or the output raster. Output name example: `"outputName":{"serviceProperties":{"name":"testrasteranalysis"}}` Output raster examples: `//Output portal item: "outputName":{"itemId": <portal item id>} //Output url: "outputName":{"url": <image service url} //Output raster layer service: "outputName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"} }`
inputFlowDirectionRaster	The input raster that shows the direction of flow out of each 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. Examples: `//Portal item as input raster "inputFlowDirectionRaster": {"itemId": <portal item id>} //URL as input raster "inputFlowDirectionRaster": {"url": <image service layer url>}`
distanceType	Determines whether the vertical or horizontal component of flow distance is calculated. Syntax: A string describing the distance calculation type, which can be one of the following: VERTICAL calculations represent the vertical component of flow distance, following the flow path, from each cell in the domain to the cells on the stream into which they flow. This is the default. HORIZONTAL calculations represent the horizontal component of flow distance, following the flow path, from each cell in the domain to the cells on the stream into which they flow. Example: `"distanceType": "HORIZONTAL"`
flowDirectionType	The input flow direction raster can be of type D8, Multi Flow Direction (MFD), or D-Infinity (DINF). Syntax: A string describing the flow direction type, which can be one of the following: D8 is for the D8 flow direction type. This is the default. MFD is for the Multi Flow Direction type. DINF is for the D-Infinity type. Example: `"flowDirectionType": "DINF"`
statisticsType	Determines the statistics type used to compute flow distance over multiple flow paths. If there is only a single flow path from each cell to a cell on the stream, all statistics types produce the same result. Syntax: A string describing the statistics type, which can be one of the following: MINIMUM—Where multiple flow paths exist, minimum flow distance in computed. This is the default. WEIGHTED_MEAN—Where multiple flow paths exist, a weighted mean of flow distance is computed. Flow proportion from a cell to its downstream neighboring cells are used as weights for computing weighted mean. MAXIMUM—When multiple flow paths exist, maximum flow distance is computed.
context	Contains additional settings that affect task processing. 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 \| 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>/FlowDistance/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>/FlowDistance/jobs/<jobId>/results/outputRaster

Example usage

Below is a sample request URL for FlowDistance.

https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/FlowDistance/submitJob

JSON Response example

The response returns the outputRaster output parameter, which has properties for parameter name, data type, and value. The content of value is always the output raster dataset itemId and the image service URL.

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

Feedback on this topic?

Description

Request parameters

Response

Example usage

JSON Response example

In this topic