Upstream/Downstream Search Service
- Description
- Usage Scenarios
- Code Samples
- Input Parameters
- Output Return Object
- Http Service
- Database Service
- Changelog
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.
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.
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.
Code Samples
- Upstream/Downstream Search Service (OpenLayers) Exit
- Upstream/Downstream Search Service (Leaflet) Exit
- Upstream/Downstream Search Service - 303(d) Downstream (OpenLayers) Exit
- Upstream/Downstream Search Service - Results Queue Example (Leaflet) Exit
- Upstream/Downstream Search Service - Point to Point Example (Leaflet) Exit
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.
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.
HTTP Service
| Resource | Location |
|---|---|
| Runtime Endpoint |
https://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