Jump to main content or area navigation.

Contact Us

Water: Services

Upstream/Downstream Service

Description

The Upstream/Downstream service is designed to provide standard traversal and discovery functions upon the NHDPlus stream network. The traversal request may include a description of where, on the stream network, to begin the traversal, a description of where or how to end the traversal, and a list of one or more formats for the returned results. The Upstream/Downstream service receives the stream network traversal request, performs the traversal, and returns the requested results. The Upstream/Downstream service is an elemental function to be used by applications as a stand alone service or in combination with other WATERS services. All Upstream/Downstream executions require a navigation type and at least one start point. All other input parameters are optional.

Usage Scenarios

Reviewing a TMDL for a single listed water and pollutant

Problem Statement

Reviewing a TMDL for a single listed water and pollutant.

Desired Information

Upstream surface water permitted dischargers for waters within 50 miles of the downstream end of the listed water.

Information Returned from Service

List of NPDES IDs upstream of or coincident with the listed water.

Example map showing listed water with navigation results and PCS points 

Permit Example

Problem Statement

Need to evaluate downstream potential impacts for a NPDES permit renewal application approval.

NOTE: If the NPDES discharge location is stored in the RAD, only the NPDES ID will be required. If the location has not been indexed (or not stored in the RAD), then this service can be combined with the point indexing service to obtain a network location to start the upstream/downstream navigation from. If the discharge point is on a feature in the medium resolution NHD, then the snap option should be used, however, if the discharge point is on a tributary to a medium resolution NHD feature (i.e., not in the medium resolution NHD dataset), then the raindrop option should be selected in the point indexing service.

Desired Information

All impaired waters and drinking water intakes within 40 miles downstream of the NPDES discharge point.

Information Returned from Service

Table object with all NPDES, DWI, and impaired waters downstream with divergences within 40 miles of the discharge point. In addition, return the navigation track as a spatial object.

     

Code Samples

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
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. Must be length 14 and contain all digits.
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).
pStartSourceFeatureid String Event source feature id to begin navigating from.
pStartSourceProgram String Event source feature id program.
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.  Must be length 14 and contain all digits.
pStopMeasure Number Measure on the NHD reach code to stop navigating at. Must be between 0 and 100 inclusive, or NULL.
pStopSourceFeatureid String Event source feature id to stop navigating at.
pStopSourceProgram String Event source feature id program
pStopDistancekm Number Distance in KM to navigate. If pStopDistancekm is not provided, then distance to travel defaults to 50 km.
pStopBottomOfPath String TRUE/FALSE - Navigate to the end of path overruling pStopDistancekm. Only valid with UM and DM navigation types.
pTraversalSummary String TRUE/FALSE - Indicates whether to populate and include the updn_recTraversal_summary object in results.
pFlowlinelist String TRUE/FALSE - Indicates whether to populate and include the updn_recFlowline_traversed object in results.
pEventList String Array of program abbreviations to search for along the navigation route. See the complete list of RAD program abbreviations. 
pEventListMod String Modifier explaining the array format used in pEventList. See the complex object modifier descriptions for more information. 
pNearestEntityList String Array of entity IDs for each program.
pNearestEntityListMod String Modifier explaining the array format used in pNearestEntityListMod. See the complex object modifier descriptions for more information.

HTTP Service Notes

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

 

Output

UML Diagram

Upstream/Downstream Service UML

Return Object

updn_obj_output

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.
resolved_starts Array of
Object
Oracle object: updn_recFlowLineInfo
resolved_stops Array of
Object
Oracle object: updn_recFlowLineInfo
updn_traversal_summary Array of
Object
Oracle object: updn_recTraversal_summary
flowlines_traversed Array of
Object
Oracle object: updn_recFlowline_traversed
events_encountered Array of
Object
Oracle object: updn_recEvent_encountered
nearest_entities_encountered Array of
Object
Oracle object: updn_recEntity_encountered

Supporting Objects

updn_recFlowLineInfo

Property Datatype Description
comid Number NHD flowline comid.
measure Number NHD reach code measure.                                                 

updn_recTraversal_summary

Property Datatype Description
total_km_navigated Number Total KM navigated during process.
total_flowlines_traversed Number Total number of flowlines traversed during navigation.    

updn_recFlowline_traversed

Property Datatype Description
startcomid Number NHD flowline comid of the flowline beginning the navigation.
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. All values are zero for NHDPlus v2.1.
hydroseq Number The hydrologic sequence of the flowline in the total traversal.

updn_recEvent_encountered

Property Datatype Description
startcomid Number NHD flowline comid of the flowline beginning the navigation.
flcomid Number NHD flowline comid containing the RAD event.
evtcomid Number RAD event comid.
reachcode Number NHD reach code containing the RAD event.
source_featureid String RAD event source featureid value.
source_program String RAD event program.
from_measure Number NHD reach code beginning measure of the RAD event.
to_measure Number NHD reach code ending measure of the RAD event.
start_measure Number Represents the first point of intersection between the event and the traversal.
traveled_distancekm Number Total distance of the traversal in KM.
traveled_time Number Total navigation time of the traversal in hours. All values are zero for NHDPlus v2.1.

updn_recEntity_encountered

Property Datatype Description
source_featureid String RAD event source featureid value.
source_program String RAD event program.
reachcode String NHD reach code containing the RAD event.
measure Number NHD reach code measure at which the event occurs.
startcomid Number NHD flowline comid of the flowline beginning the traversal.                 
traveled_distancekm Number Total distance of the traversal in KM.
traveled_time Number Total navigation time of the traversal in hours. All values are zero for NHDPlus v2.1.

HTTP Service Notes

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

JavaScript Library

Function Name
WATERS.Services.PointIndexingService

HTTP Service

Resource Location
Runtime
Endpoint
http://ofmpub.epa.gov/waters10/UpstreamDownStream.Service

Database Service

Database service users will require the RAD_PUBLIC role for accessing unprotected RAD program results. Accessing protected RAD program data requires additional roles which must be may only be obtained through proper EPA channels.

Database
Instance
Schema Resource
WATERS10 UPSTREAM_DOWNSTREAM UPDN_MAIN.UPSTREAMDOWNSTREAM

Changelog

Version: 3.01 - Released: April 21, 2014

  • pStopTimeOfTravel parameter removed. NHDPlus v2.1 does not support time 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 HTTP Services and update web page content

Jump to main content.