- URL:https://<rasteranalysistools-url>/FlowDistance
- Version Introduced:10.6
Description
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:
|
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:
|
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:
Output raster examples:
|
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:
|
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:
Example:
|
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:
Example:
|
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:
|
context | Contains additional settings that affect task processing. This task has the following settings:
|
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"
}
}