Jump to main content or area navigation.

Contact Us

Water: Services

Navigation Service


The Navigation service is a subset component of the Upstream/Downstream service designed to provide standard stream network traversal.  The traversal request may include a description of where, on the stream network, to begin the traversal, and a description of where or how to end the traversal.  All Upstream/Downstream executions require a navigation type and at least one start point.  All other input parameters are optional.

Usage Scenarios

Drinking Water Designated Use Evaluation

Problem Statement

Determine if the waters upstream from a drinking water intake have the proper designated use assigned to them.

Desired Information

List of all waters within 50 miles upstream of all drinking water intakes that have a designated use different from drinking water supply.

Information Returned from Service

Event tables of waters 50 miles upstream of each drinking water intake. NOTE: The results of this service will need to be overlaid with the assessed waters layer and joined to the ATTAINS database to complete the analysis.


Code Samples



Parameter Datatype Description
pNavigationType String 'UM' for upstream mainstem navigation
'UT' for upstream with tributaries navigation
'DM' for downstream mainstream navigation
'DD' for downstream with divergences navigation
'PP' for point-to-point navigation
pStartComid Number NHD flowline comid to begin navigating from. Must be greater than 0 and less than 999999999.
pStartReachcode String NHD reach code to begin navigating from. User must provide either a comid or a reach code. If both are provided, then the comid takes precedence. 
pStartMeasure Number Measure on the NHD reach code to begin navigating from. Must be between 0 and 100 inclusive, or NULL. A value of null means that a measure will be calculated to be either the bottom or the top of the NHD flowline. (depending on whether the navigation type is upstream or downstream and whether it is a start or stop measure).
pStopComid Number NHD flowline comid to stop navigating at. Must be greater than 0 and less than 999999999.
pStopReachcode String NHD reach code to stop navigating at. User must provide either a comid or a reach code. If both are provided, then the comid parameter takes precedence.
pStopMeasure Number Measure on the NHD reach code to stop navigating at. Must be between 0 and 100 inclusive, or NULL.
pMaxDistanceKm Number Distance in KM to navigate. If pMaxDistance is not provided, then distance to travel defaults to 50 km. 
pReturnFlowlineAttr String TRUE/FALSE - flag to return the geometry of each navigated flowline. Note the collection and clipping of flowline geometries adds a performance penalty to each service call. The default value is FALSE.

HTTP Service Notes

Additional parameters specific to HTTP services are listed in the WATERS HTTP Services documentation. 



UML Diagram

Navigation Service UML 

Return Object


Property Datatype Description
return_code Number Return Code indicate success or failure of the navigation process. 
0 = Up/Down Service completed as requested 
1nn= Interpreter errors 
2nn= Resolver errors 
3nn=Traverser errors 
4nn=Pruner errors 
5nn=Outputer errors 
999=General error
status_message String Status message provides text details for return codes 1nn thru 5nn.
ntnavresultsstandard Array of
Object Type: updn_nttypenavresultsstandard

Supporting Objects

updn_recnavresultsstandard object

Property Datatype Description
comid Number NHD flowline comid.
reachcode String NHD reach code.
frommeas Number NHD reach code beginning measure.
tomeas Number NHD reach code ending measure.
totaldist Number Total distance of the flowline in KM for the traversal.
totaltime Number Total navigation time of the flowline in hours for the traversal.  Currently all values are zero in NHDPlus v2.1.
hydroseq Number The hydrologic sequence of the flowline in the total traversal.
shape Geometry Geometry of the feature.

HTTP Service Notes

The output format for this service is JSON with GEOJSON formatted geometries.

JavaScript Library

Function Name

HTTP Service

Resource Location

Database Service  

Schema Resource


Version: 3.01 - Released: April 21, 2013

  • pMaxTime parameter removed as NHDPlus v2.1 does not support time of travel calculations at this time.

Version: 3.0 - Released: February 03, 2014

  • SOAP version of the service decommissioned.

Version: 2.0 - Released: August 31, 2009

  • Initial Release of SOAP and HTTP Service for this component

Jump to main content.