-
Notifications
You must be signed in to change notification settings - Fork 15
waters
This is a comparison between the NLDI services and EPA Waters UpstreamDownstream and NavigationDelineation services. The NLDI is based on the same database logic but offers a different service interface and somewhat limited functionality.
The greatest distinction between the two is the Waters is a query-parameter-based web service and the NLDI is a resource-oriented API with optional query parameters. That is, the NLDI offers a resource such as:
https://labs.waterdata.usgs.gov/api/nldi/linked-data/comid/22338109 which has a navigate resource:
https://labs.waterdata.usgs.gov/api/nldi/linked-data/comid/22338109/navigate which has a UM resource:
https://labs.waterdata.usgs.gov/api/nldi/linked-data/comid/22338109/navigate/UM which has a "nwissite" resource.
https://labs.waterdata.usgs.gov/api/nldi/linked-data/comid/22338109/navigate/UM/nwissite The UM navigation resource and its sub resources accept query parameters such as distance:
https://labs.waterdata.usgs.gov/api/nldi/linked-data/comid/22338109/navigate/UM/nwissite?distance=150
In contrast, the Waters services are based entirely on query parameters. For example, an example UpstreamDownstream that is roughly equivalent to the NLDI query above is:
https://ofmpub.epa.gov/waters10/UpstreamDownstream.Service?
pNavigationType=UM
pStartComid=22338109
pStartMeasure=0
pStopDistancekm=150
The NLDI has a very rudimentary basin delineation capability:
https://labs.waterdata.usgs.gov/api/nldi/linked-data/comid/22338109/basin
The roughly equivalent Waters NavigationDelineation service request is:
https://ofmpub.epa.gov/waters10/NavigationDelineation.Service?
pNavigationType=UT
pStartComid=22338109
pStartMeasure=0
pMaxDistance=150
Waters offers a wide array of query parameters to support a diversity of use cases. They are summarized as "shared" parameters, those that are unique to UpstreamDownstream and those that are unique to NavigationDelineation.
- pNavigationType
- pStartComID
- pStopComid
- pStartPermanentIdentifier
- pStopPermanentIdentifier
- pStartReachcode
- pStopReachcode
- pStartMeasure
- pStopMeasure
- pStartSourceFeatureid
- pStopSourceFeatureid
- pStartSourceProgram
- pStopSourceProgram
- pStopDistancekm
- pStopBottomOfPath
- pTraversalSummary
- pFlowlinelist
- pEventList
- pEventListMod
- pNearestEntityList
- pNearestEntityListMod
- pStartHydrosequence
- pStopHydrosequence
- pMaxDistance
- pMaxFlowtimeDay
- pFeatureType
- pOutputFlag
- pAggregationFlag
- pFlowlineLists
Note: that all "stopID" functionality is only relevant to the "point to point" service request.
- pNavigationType
- pStartComID
- pStartSourceFeatureid
- pStopSourceFeatureid
- pStartSourceProgram
- pStopSourceProgram
Note that the NLDI implements different semantics for these parameters. SourceProgram is a {featureSource} and SourceFeatureid is {featureSourceId}. Additionally, not all "Programs" are available as "featureSources" in the NLDI -- something that could be fixed with little effort.
- None
- None
-
pStopDistancekm:distance -
pStopComid:stopComid
- None
Note that the basin resource in NLDI is an unconstrained Upstream with Tributaries navigation. It is a cached object with no opportunity to modify. However, it is implemented such that not hitting a cache is possible and configuration of a request could be made possible.
While the core functionality is waters is satisfied, a number of functions would be required to make the NLDI work for all the use cases Waters satisfies.
Given that the NLDI is resource oriented and the core-resource, the comid, is shared, a future NLDI will be a single API. If we first consider the shared parameters, a significant feature that would be required.
- pStartMeasure
- pStopMeasure
MEDIUM for navigation XLARGE for basins
Waters and the NLDI implement a navigation method that first finds whole-catchments that should be returned. Waters will optionally truncate the response such that a partial catchment is returned. The NLDI does not support this functionality. In the case of the distance parameter, whole catchments and flowlines are returned.
Flowline splitting to a measure is software-only and would be achievable but has service performance implications that may necessitate a major rethinking of the NLDI synchronous response model. Catchment splitting to a measure is significantly more involved as it requires a flow-direction / flow-accumulation grid and functionality to determine a catchment split.
There are numerous implementation patterns that could be used -- an in-depth design process would be necessary.
- pStartPermanentIdentifier
- pStopPermanentIdentifier
- pStartReachcode
- pStopReachcode
- pStartHydrosequence
- pStopHydrosequence
SMALL
Waters supports additional NHDPlus identifiers, ReachCode and PermanentIdentifier, for start and stop locations. These work with the start and stop measure, which applies only to ReachCodes, because there is a 1:1 mapping between COMID, PermanentIdentifier, and ReachCode.
Adding this functionality to the NLDI would be a software only change and relatively easy. Performance should be very good. There are a number of design options for the API which would need to be evaluated.
MEDIUM/LARGE
The NLDI basin resource is an unconstrained upstream with tributaries navigation. This allows the vast majority of geoprocessing to be run once and cached. The delineation functionality of Waters first navigates the network then retrieves catchment boundaries and optionally merges them together. While the specific parameter combination pFeatureType=CATCHMENTSP&pOutputFlag=FEATURE&pAggregationFlag=TRUE will invoke a cache in Waters, the scope of functionality introduces significant processing overhead and potential limitations.
In order to support the general functionality of Waters in the NLDI, an asynchronous processing scheme would be required.
Most of the functionality available from Waters in this area is available or would be easy to add in the NLDI database but is not exposed via the API. If taken together, with measure-specific navigation, this is a lower total effort as the asynchronous processing scheme would have some overlap.
- pStopBottomOfPath
SMALL
Add query parameter "mainstemOnly" to stop DM navigation at outlet of mainstem.
- pTraversalSummary
This is an output format flag. See output format details.
- pFlowlinelist
This is an output format flag. See output format details
- pEventList
- pEventListMod
SMALL
Currently, NLDI navigation only allows discovery of a single {featuresource}. Could add optional comma separated query parameter that would cause multiple feature sources worth of output to be returned.
- pNearestEntityList
- pNearestEntityListMod
???
I need help understanding what an "Entity" is in this context.
All items here assume that Non-basin delineation is completed.
- pMaxDistance
- pMaxFlowtimeDay (unsupported in Waters)
SMALL
Same as pStopDistancekm
- pFeatureType
SMALL
Would require loading complete (not simplified) catchments, but otherwise trivial.
- pOutputFlag
SMALL
Ability to return flowlines, catchments, or both would be easy to add.
- pAggregationFlag
SMALL
Ability to aggregate catchments or not is a trivial addition.
- pFlowlineLists
SMALL
Code only addition.
MEDIUM
Output data is all available in the NLDI database but calculations and output serialization would be a non-trivial amount of work to prepare.