Create Watersheds

The Create Watersheds task determines the watershed, or upstream contributing area, for each point in your analysis layer. For example, suppose you have point features representing locations of waterborne contamination, and you want to find the likely sources of the contamination. Since the source of the contamination must be somewhere within the watershed upstream of the point, you would use this tool to define the watersheds containing the sources of the contaminant.

This task is a wrapper around the Watershed task found in Elevation Analysis Services.

Request URL

http://<analysis url>/CreateWatersheds/submitJob

Request Parameters

Parameter	Description
inputLayer (Required)	The point features used for calculating watersheds. These are referred to as pour points, because it is the location at which water pours out of the watershed. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following: A URL to a feature service layer with an optional filter to select specific features A feature collection Examples: {"url": <feature service layer url>, "filter": <where clause>} {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}
searchDistance	The maximum distance to move the location of an input point. Use searchUnits to set the units for searchDistance. If your input points are located away from a drainage line, the resulting watersheds are likely to be very small and not of much use in determining the upstream source of contamination. In most cases, you want your input points to snap to the nearest drainage line in order to find the watersheds that flows to a point located on the drainage line. To find the closest drainage line, specify a search distance. If you do not specify a search distance, the tool will compute and use a conservative search distance. To use the exact location of your input point, specify a search distance of zero. For analysis purposes, drainage lines have been precomputed by Esri using standard hydrologic models. If there is no drainage line within the search distance, the location containing the highest flow accumulation within the search distance is used. Type: Double Default: Calculated as the resolution of the source data multiplied by 10
searchUnits	The linear units specified for the search distance. Type: String Values: Meters | Kilometers | Feet | Yards | Miles Default: Meters
sourceDatabase	Keyword indicating the data source resolution that will be used in the analysis. Type: String Values: The values for this parameter are: Finest (Default): Finest resolution available at each location from all possible data sources. 30m: The hydrologic source was built from 1 arc second - approximately 30 meter resolution, elevation data. 90m: The hydrologic source was built from 3 arc second - approximately 90 meter resolution, elevation data.
generalize	Determines if the output watersheds will be smoothed into simpler shapes or conform to the cell edges of the original DEM. Type: Boolean Values: True: The polygons will be smoothed into simpler shapes. This is the default. False: The edge of the polygons will conform to the edges of the original DEM.
outputName	If provided, the task will create a feature service of the results. You define the name of the service. If an outputName value is not provided, the task will return a feature collection. Syntax: { "serviceProperties": { "name": "<service name>" } } In ArcGIS Online or ArcGIS Enterprise 10.9.1 and later, you can overwrite an existing feature service by providing the itemId value of the existing feature service and setting the overwrite property to true. Including the serviceProperties parameter is optional. As described in the Feature output topic, you must either be the owner of the feature service or have administrative privileges to perform the overwrite. Syntax: { "itemProperties": { "itemId": "<itemID of the existing feature service>", "overwrite": true } } or { "serviceProperties": { "name": "<existing service name>" }, "itemProperties": { "itemId": "<itemID of the existing feature service>", "overwrite": true } }
context	The Context parameter contains the following additional settings that affect task operation: Extent (extent)—A bounding box that defines the analysis area. Only input features that intersect the bounding box will be analyzed. Output spatial reference (outSR)—The output features will be projected into the output spatial reference. Syntax: { "extent" : {extent}, "outSR" : {spatial reference} }
f	The response format. The default response format is html. Values: html | json

Response

When you submit a request, the request 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 the topic Checking job status. Once the job has successfully completed, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

http://<analysis url>/CreateWatersheds/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:

http://<analysis url>/CreateWatersheds/jobs/<jobId>/results/watershedLayer?token=<your token>&f=json

Parameter	Description
snapPourPtsLayer	These are point features where the watershed is calculated. If a search distance of zero is used, the points will be at the same location as the input points. The resultant points features have the attributes from the input points as well the following attribute: PourPtID—The unique ID field from the input points feature Request example: {"url": "http://<analysis url>/CreateWatersheds/jobs/<jobId>/results/snapPourPtsLayer"} The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request. If outputName was provided, value contains the URL to the feature service layer. { "paramName":"snapPourPtsLayer", "dataType":"GPString", "value":{"url":"<hosted featureservice layer url>"} } If outputName was not provided, value contains a feature collection. { "paramName":"snapPourPtsLayer", "dataType":"GPString", "value":{"layerDefinition": {}, "featureSet": {} } } See Feature Output for more information about how the result layer or collection is accessed.
watershedLayer	These are polygon features where each polygon is the watershed. The resultant polygon features have the attributes from the input points as well the following attributes: PourPtID—The unique ID field from the input points feature Description— Describes the source database used in the analysis. US30m-which is derived from the 30m NHDPlusV2.1 for the continental United States, and the 90m HydroSHEDS for the world between 60 degrees North and 56 degrees South, plus some areas in Canada and Alaska north of 60 degrees. DataResolution— The data-source resolution that was be used in the analysis AnalysisArea—The area of the polygon in the units specified in your profile, which will either be square miles or square kilometers. Request example: {"url": "http://<analysis url>/CreateWatersheds/jobs/<jobId>/results/watershedLayer"} The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request. If outputName was provided, value contains the URL to the feature service layer. { "paramName":"watershedLayer", "dataType":"GPString", "value":{"url":"<hosted featureservice layer url>"} } If outputName was not provided, value contains a feature collection. { "paramName":"watershedLayer", "dataType":"GPString", "value":{"layerDefinition": {}, "featureSet": {} } } See Feature Output for more information about how the result layer or collection is accessed.