Skip To Content
ArcGIS Developer
Dashboard

Watershed

Watershed request

The Watershed request is used to identify catchment areas based on a particular location you provide.

Request URL

https://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/Watershed/submitJob

Description

The Watershed request is used to delineate watersheds. You identify a location you are interested in finding a watershed for, and whether you wish to snap the location to the nearest stream. The request combines this with Esri-curated data to create an output polygon for that particular watershed.

This request uses multiple source databases which are available for different geographic areas and at different spatial scales. Please refer to the Hydrology analysis data coverage to see the areas and sources currently available.

Usage

  • For each input point, or pour point, a watershed feature will be returned.

  • Output watershed features are the complete upstream area that contributes flow. For example, an input point on the Mississippi River in Louisiana will create a watershed feature extending to include areas from New York to Montana and into Canada.

  • A watershed feature will not be returned if the pour point does not fall inside the extent of the specified data source.

  • If no point identification field is specified, the unique ID field is used by default.

  • The maximum number of input points is 1000. If more input features are provided, the request will return an error and will not execute.

  • The pour point identification field must be of type integer or string. It is most useful to use a field consisting of unique values.

  • The output watershed feature dataset has a field called PointID consisting of the values supplied in the point identification field. This allows the watershed to easily be related back to the input points.

  • The resulting watershed feature dataset contains a field called AreaSqKm, which is the area in square kilometers for each watershed.

  • The default snapping distance is the resolution of the data in the specified database multiplied by 5.

  • The optional output of snapped points contain a field called PointID. This field contains the values supplied in the pour point ID field. This is used to relate the input pour points to their watersheds.

  • This request uses multiple source databases which are available for different geographic areas and at different spatial scales. Please refer to the Hydrology analysis data coverage to see the areas and sources currently available.

  • To provide feedback on this request, please visit the Hydro Forum on GeoNet.

Request Parameters

ParameterDescription

InputPoints

(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.

  • Type : Feature Set

PointIDField

(Optional)

The field used to identify to the input points.

It can be an integer or string field. The default is to use the unique ID field.

  • Type : String

SnapDistance

The maximum distance to move the location of an input point.

Interactive input points and documented gage locations may not exactly align with the stream location in the DEM. This parameter allows to move each point to a nearby location with the largest contributing area.

The snap distance should always be larger than the source data resolution. By default, the snapping distance is calculated as the resolution of the source data multiplied by 5.

  • Type : Double

  • Value : The numerical value to use for the snap distance is specified as a string.

SnapDistanceUnits

The linear units specified for the snap distance.

  • Type : String

  • Values : The values for this parameter are: Meters | Kilometers | Feet | Yards | Miles

  • Default : The default units for this parameter are Meters.

DataSourceResolution

Keyword indicating the source data that will be used in the analysis.

The keyword is an approximation of the spatial resolution of the digital elevation model used to build the foundation hydrologic database. Since many elevation sources are distributed with units of arc seconds, we provide an approximation in meters for easier understanding.

  • Type : String

  • Values : The values for this parameter are:

    • Blank : The hydrologic source was built from 3 arc second - approximately 90 meter resolution, elevation data. This is the default.

    • Finest : Finest resolution available at each location from all possible data sources.

    • 10m : The hydrologic source was built from 1/3 arc second - approximately 10 meter resolution, elevation data.

    • 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 : The values for this parameter are: True | False

    • 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.

ReturnSnappedPoints

Determines if a point feature at the watershed’s pour point will be returned. If snapping is enabled, this might not be the same as the input point.

  • Type : Boolean

  • Values : The values for this parameter are: True | False

    • True : A point feature will be returned. This is the default.

    • False : No point features will be returned.

Response

When you submit a request, it is assigned 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, you use the jobId to retrieve the results. To track the status, you can make a request of the following form:

https://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/Watershed/jobs/<jobId>

Accessing results

When the status of the job request is esriJobSucceded, you can access the results of the analysis by making a request of the following form.

https://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/Watershed/jobs/<jobId>/results/<output_parameter_name>?token=yourToken&f=json

ParameterDescription

WatershedArea

(Required)

The watershed polygon is a derived output.

Type : Feature Set

SnappedPoints

The snapped points is a derived output.Watershed

Type : Feature Set

Javascript Example

In the ArcGIS API for Javascript, hydrology analysis is performed using the Geoprocessor class. The constructor to the Geoprocessor creates an instance pointing to the REST URL of the hydrology analysis service request you wish to perform. When the map is clicked, an event listener calls a function that adds a SimpleMarkerSymbol at the location of the click, assembles the parameters necessary to complete the request, and submits the job. Each hydrology analysis request has different input parameters, so be sure to read the documentation closely. A callback function is used to get and draw the result data once the job succeeds.

The use of these requests requires user authentication. This is accomplished using IdentityManager, which handles the process of prompting the user for their credentials, generating a token, and appending it to the job request. To use the IdentityManager simply add the following dojo.require to your application:

dojo.require("esri.IdentityManager");

Note:

If the analysis your application performs requires the use of tokens, make sure this is clearly indicated to the user.

Code sample

A live sample of this can be viewed with the following link:

Following is the javascript used for the sample:

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=7, IE=9, IE=10">
    <!--The viewport meta tag is used to improve the presentation and behavior of the samples 
      on iOS devices-->
    <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
    <title>Watershed Delineation</title>

    <link rel="stylesheet" href="http://js.arcgis.com/3.8/js/esri/css/esri.css">
    <link rel="stylesheet" href="http://js.arcgis.com/3.8/js/dojo/dijit/themes/claro/claro.css">
    
    <style>
      html, body, #mapDiv {
        height: 100%;
        margin: 0;
        padding: 0;
        width: 100%;
      }
      #info {
        bottom: 20px;
        color: #444;
        height: auto;
        font-family: arial;
        left: 20px;
        margin: 5px;
        padding: 10px;
        position: absolute;
        text-align: left;
        width: 200px;
        z-index: 40;
      }
    </style>

    <script src="http://js.arcgis.com/3.8/"></script>
    <script>
    require(["dojo/dom",
              "dojo/_base/Color",

              "esri/map",
              "esri/graphic",
              "esri/tasks/Geoprocessor",
              "esri/tasks/FeatureSet",
              "esri/layers/ArcGISTiledMapServiceLayer",
              "esri/layers/GraphicsLayer",
              "esri/symbols/SimpleMarkerSymbol",
              "esri/symbols/SimpleFillSymbol",
              "esri/symbols/CartographicLineSymbol",
              "esri/IdentityManager"
             ],
        function(dom, Color, Map, Graphic, Geoprocessor, FeatureSet, ArcGISTiledMapServiceLayer, GraphicsLayer, SimpleMarkerSymbol, SimpleFillSymbol, CartographicLineSymbol){

          var map, gp;


    //Initialize Map
            map = new Map("mapDiv", {
              //basemap: "topo",
              center: [20.6, 0],
              zoom: 4
            });

            var basemap = new ArcGISTiledMapServiceLayer("http://server.arcgisonline.com/ArcGIS/rest/services/World_Terrain_Base/MapServer");
            var overlay = new ArcGISTiledMapServiceLayer("http://hydrology.esri.com/arcgis/rest/services/WorldHydroReferenceOverlay/MapServer");
            var tempPoint = new GraphicsLayer();
            var watersheds = new GraphicsLayer();
            map.addLayers([basemap, overlay, tempPoint, watersheds])

    //Set GP Symbology
            var outline = new CartographicLineSymbol(CartographicLineSymbol.STYLE_SOLID, new Color([0,0,0,1]), 2);
            outline.setCap(CartographicLineSymbol.CAP_ROUND);
            outline.setJoin(CartographicLineSymbol.JOIN_ROUND);

            var pointSymbol = new SimpleMarkerSymbol();
            pointSymbol.setStyle(SimpleMarkerSymbol.STYLE_CIRCLE)
            pointSymbol.setSize("10");
            pointSymbol.setColor(new Color([59, 148, 0, 1]));
            pointSymbol.setOutline(outline);

            var polySymbol = new SimpleFillSymbol();
            polySymbol.setColor(new Color([55,138,73,.25]));
            polySymbol.setOutline(outline);

    //Add Watershed Delineation Geoprocessing Function
            gp = new Geoprocessor("http://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/Watershed");
            gp.setOutSpatialReference({wkid: 102100});
            map.on("click", computeWatershed);

          function computeWatershed(evt) {
            var graphic = new Graphic(evt.mapPoint, pointSymbol);
            tempPoint.add(graphic);
            //window.setTimeout(function(){tempPoint.clear()}, 350);

            var features = [];
            features.push(graphic);
            var featureSet = new FeatureSet();
            featureSet.features = features;

            var params = {
              "InputPoints": featureSet,
              "SnapDistance": "5000",
              "SnapDistanceUnits": "Meters",
              "DataSourceResolution": "FINEST",
              "Generalize": "True"
            };
            gp.submitJob(params, Callback, function(error){
            console.log("error", error, params);
            window.alert("Sorry, we do not have data for this region at your requested resolution");
            });
          }

          function Callback(jobInfo){
            gp.getResultData(jobInfo.jobId, "WatershedArea", drawWatershed);
            gp.getResultData(jobInfo.jobId, "SnappedPoints", drawSnappedPoint);
          }

          function drawWatershed(results) {
            console.log(results);
            var features = results.value.features;
            for (var f=0, fl=features.length; f<fl; f++) {
              var feature = features[f];
              feature.setSymbol(polySymbol);
              watersheds.add(feature);
            }
          }

          function drawSnappedPoint(results) {
            console.log(results);
            tempPoint.clear()
            var features = results.value.features;
            for (var f=0, fl=features.length; f<fl; f++) {
              var feature = features[f];
              feature.setSymbol(pointSymbol);
              map.graphics.add(feature);
            }
          }
    });
    </script>

  </head>
  <body class="claro">
    <div id="mapDiv"></div>
    <div id="info" class="esriSimpleSlider">
      Click on a stream to delineate its watershed. <br>
      <a href="http://www.arcgis.com/home/item.html?id=8e48f6209d5c4be98ebbf90502f41077" target="Ref">More...</a>
    </div>
  </body>
</html>