An official website of the United States government.

This is not the current EPA website. To navigate to the current EPA website, please go to This website is historical material reflecting the EPA website as it existed on January 19, 2021. This website is no longer updated and links to external websites and some internal pages may not work. More information »

Navigation Service


The Navigation service is 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 executions require a navigation type and at least one start point. All other input parameters are optional.

Top of Page

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

Top of Page

Input Parameters

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 NHDPlus flowline ComID integer value to begin navigating from.
pStartPermanentIdentifier String NHDPlus flowline Permanent Identifier string value to begin navigating from.
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 NHDPlus flowline ComID integer value to stop navigating at.
pStopPermanentIdentifier String NHDPlus flowline Permanent Identifier string value to stop navigating at.
pStopReachcode String NHDPlus 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 NHDPlus 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.

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

Output 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

updn_recnavresultsstandard object

Property Datatype Description
comid Number NHDPlus flowline ComID.
permanent_identifier String NHDPlus flowline Permanent Identifier.
reachcode String NHDPlus reach code.
fmeasure Number NHDPlus reach code beginning measure.
tmeasure Number NHDPlus 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.

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

Top of Page

HTTP Service

Resource Location

Top of Page

Database Service

Schema Resource

Top of Page


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

Top of Page