Trace Downstream

Trace Downstream task

The Trace Downstream task is used to determine the flow path in a downstream direction from the identified location.

Request URL

http://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/TraceDownstream/submitJob

Description

The Trace Downstream task is used to determine the flow path in a downstream direction from the identified location.

Usage

  • For each input point a downstream trace line feature will be returned.

  • An output downstream trace is the downstream path to the ocean. For example, an input point anywhere in the Mississippi River watershed will result in a down stream trace that ends in the Gulf of Mexico.

  • A downstream trace feature will not be returned if the 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 100. If more input features are provided, the task 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 downstream trace feature dataset has a field called PointID consisting of the values supplied in the point identification field. This allows the downstream trace to easily be related back to the input points.

  • The resulting downstream trace feature dataset contains a field called LengthKm, which is the length in kilometers for each downstream trace.

  • This service uses multiple source databases which are available for different geographic areas and at different spatial scales. Please refer to the locator map to see the areas and sources currently available.

  • Using this task consumes credits. The rate of use is 1 credit per 1000 input features.

    For more information, see the Service Credits Overview.

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

Request Parameters

ParameterDescription

InputPoints

(Required)

The point features used for the starting location of a downstream trace.

  • Type : The type of the input is a 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 : This parameter is a String type.

SourceDatabase

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 : The data source is specified as a String type.

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

    • 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 downstream trace lines will be smoothed into simpler lines.

  • Type : This parameter is a Boolean type.

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

    • False : The lines will not be smoothed. The ungeneralized stream trace is more accurate but has more vertices, so the result is larger. This is the default.

    • True : The lines will be smoothed into simpler lines. The generalized stream trace looks best. It also has fewer vertices and, therefore, a smaller result file to transmit.

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 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://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/TraceDownstream/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://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/TraceDownstream/jobs/<jobId>/results/<output_parameter_name>?token=yourToken&f=json

ParameterDescription

OutputTraceLine

(Required)

The Output Trace Line is the derived output.

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 task 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 task, and submits the job. Each hydro analysis task 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 tasks 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>Trace Downstream</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/symbols/SimpleMarkerSymbol",
              "esri/symbols/CartographicLineSymbol",
              "esri/IdentityManager"
              ],
        function(dom, Color, Map, Graphic, Geoprocessor, FeatureSet, ArcGISTiledMapServiceLayer, SimpleMarkerSymbol, 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");
            map.addLayers([basemap, overlay])

    //Add Trace Downstream Geoprocessing Function
            gp = new Geoprocessor("http://hydro.arcgis.com/arcgis/rest/services/Tools/Hydrology/GPServer/TraceDownstream");
            gp.setOutputSpatialReference({wkid: 102100});
            map.on("click", Trace);

          function Trace(evt) {
            var pointSymbol = new SimpleMarkerSymbol();
            pointSymbol.setStyle(SimpleMarkerSymbol.STYLE_CROSS)
            /pointSymbol.setSize("13");
            var graphic = new Graphic(evt.mapPoint, pointSymbol);
            map.graphics.add(graphic);

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

            var params = {
              "InputPoints": featureSet,
              "SourceDatabase": "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, "OutputTraceLine", drawTrace);
          }

          function drawTrace(results) {
            var traceLine = new CartographicLineSymbol(CartographicLineSymbol.STYLE_SOLID, new Color([0,0,255,1]), 5);
            traceLine.setCap(CartographicLineSymbol.CAP_ROUND);
            traceLine.setJoin(CartographicLineSymbol.JOIN_ROUND);

            console.log(results);
            var features = results.value.features;
            for (var f=0, fl=features.length; f<fl; f++) {
              var feature = features[f];
              feature.setSymbol(traceLine);
              map.graphics.add(feature);
            }
          }

    });
    </script>

  </head>
  <body class="claro">
    <div id="mapDiv"></div>
    <div id="info" class="esriSimpleSlider">
      Click on map to execute Trace Downstream. <br>
        <a href="http://www.arcgis.com/home/item.html?id=5314c23c24484c68ac961f8772be813b" target="Ref">More...</a>
    </div>
  </body>
</html>