Create Watersheds

Create Watersheds

The Watershed 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

ParameterDescription

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

  • a URL to a feature service layer with an optional filter to select specific features, or
  • 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 outputName is not supplied, the task will return a feature collection.

Syntax:
{
  "serviceProperties": {
    "name": "<service name>"
  }
}

context

Context contains additional settings that affect task execution. For Create Watersheds, there are two settings.

  1. Extent (extent)—a bounding box that defines the analysis area. Only those features in the inputLayer that intersect the bounding box will have their watersheds calculated.
  2. 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 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 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:

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 for Elevation services. 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

ParameterDescription

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.