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 www.epa.gov. 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 »

Upstream/Downstream Search Service


Description

The Upstream/Downstream Search service is designed to provide standard traversal and event 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 Search service receives the stream network traversal request, performs the traversal, and returns the requested results. The Upstream/Downstream Search 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 Search service executions require a navigation type and at least one start point. All other input parameters are optional. 

Top of Page


Usage Scenarios

Reviewing a TMDL for a single listed water and pollutant

Problem Statement: Reviewing a TMDL for a single listed water and pollutant.Upstream Downstream Usage Scenario Example

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.

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

Top of Page


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

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

Top of Page


Output 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

updn_recFlowLineInfo

Property Datatype Description
comid Number NHDPlus flowline ComID integer value.
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
start_permanent_identifier String NHD flowline Permanent Identifier string value of the flowline beginning the navigation
permanent_identifier String NHD flowline Permanent Identifier string value
start_comid Number NHDPlus flowline ComID integer value of the flowline beginning the navigation
comid Number NHDPlus flowline ComID integer value
reachcode String NHD reach code.
fmeasure Number NHD reach code beginning measure.
tmeasure 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
start_permanent_identifier String NHD flowline Permanent Identifier string value of the flowline beginning the navigation.
permanent_identifier String NHD flowline Permanent Identifier string value containing the RAD event.
start_comid Number NHDPlus flowline ComID integer value of the flowline beginning the navigation.
comid Number NHDPlus flowline ComID integer value containing the RAD event.
event_permanent_identifier String RAD event Permanent Identifier.
reachcode Number NHD reach code containing the RAD event.
source_featureid String RAD event source featureid value.
source_program String RAD event program.
fmeasure Number NHD reach code beginning measure of the RAD event.
tmeasure 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.
start_permanent_identifier String NHD flowline Permanent Identifier string value of the flowline beginning the traversal.
start_comid Number NHDPlus flowline ComID integer value 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.

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

Top of Page


HTTP Service

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

Top of Page


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

Top of Page


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

Top of Page