Point Indexing Service
- Description
- Usage Scenarios
- Code Samples
- Input Parameters
- Output Return Object
- Http Service
- Database Service
- Changelog
Description
The Point Indexing service is a subset component of the Event Indexing Service providing a simplified point indexing function for linking a point to the NHDPlus hydrology network via either a straightforward shortest distance snap or via raindrop indexing utilizing the NHDPlus flow direction grid. The service returns the point, information about the indexing action and NHD flowline information describing the nearest NHD hydrography.
Capabilities:
Distance:
This is a fairly straightforward action calculating the nearest point on the NHDPlus meeting any FCODE filters and within the maximum point indexing distance. The total distance reported is just the length of the point indexing path between the two points.
Raindrop:
The raindrop option is a more complex process which utilizes the NHDPlus Flow Direction Grid to travel "downhill" to the nearest NHD flowline. Please see the Raindrop Tool usage notes for more information.
Two parameters control the maximum distance traveled:
pPointIndexingRaindropDist: the maximum amount (in KM) that the flow direction grid is traveled in search of the NHD flowline destination. Depending on given FCODE filters, this may need to be increased to produce the desired results.
pPointIndexingMaxDist: At the end of all raindrop actions, there is a final distance snap to connect to the NHD. This parameter is the maximum amount (in KM) that the final snap to the NHD flowline may travel.
Here are a few illustrations showing raindrop indexing examples. In all cases the FCODE filter is set to only allow indexing to coastline/shoreline NHD features.
The first graphic shows a raindrop indexing action running to the same point as in previous examples. However in the second graphic, the pPointIndexingRaindropDist parameter is not set large enough for the raindrop action to travel to the feature resulting in a final distance snap to the nearby shoreline.
Usage Scenarios
Hazardous Chemical Spill
Problem Statement: Identify potentially impacted facilities downstream of a leaking storage tank. Note: This service can be combined with the Upstream/Downstream Search Service to take the network location returned from this service and enter it into the Upstream/Downstream Search Service to return the drinking water and NPDES facilities downstream from the point of entry into the surface water network.
Desired Information: Location of point of entry into the medium resolution NHD surface water network. [Drinking water and NPDES facilities downstream of the entry point to the surface water network can be obtained from the Upstream/Downstream Search Service.]
Information Returned from Service: Location, using the raindrop point indexing service option, where contents of the leaking storage tank are likely to enter the medium resolution NHD surface water network. Service returns a reach code and measure, as well as the distance traveled to the NHD feature.
Translate User Click to Stream Address
Problem Statement: When the user clicks on a surface water feature on the screen, and the desired service requires a surface water network location, not a latitude/longitude location, the latitude/longitude click point needs to be translated to the corresponding network location (i.e., reach code and measure). [For example, a user wanting to return the Identify Service information or start an Upstream/Downstream Search Service navigation starting with a click point on a map screen in a mapping application would require this service.]
Desired Information: Reach code and measure of the nearest NHD medium resolution feature. [Drinking water and NPDES facilities downstream of the entry point to the surface water network can be obtained from the Upstream/Downstream Search Service.]
Information Returned from Service: Reach code and measure of the nearest NHD medium resolution feature.
Code Samples
Input Parameters
| Parameter | Datatype | Description |
|---|---|---|
| pGeometry | Number | Point geometry to index to the NHDPlus. |
| pGeometryMod | String | Modifier explaining the input geometry. See the complex object modifier descriptions for more information. |
| pResolution | Number | National Hydrography Dataset resolution to use for service. Default value is 3 for medium resolution NHDPlus. |
| pPointIndexingMethod | String | Method to use in service call, either 'DISTANCE' or 'RAINDROP'. Use the raindrop method with caution understanding what kind of results the method produces. |
| pPointIndexingFcodeAllow | String | List of NHD FCODEs to allow when choosing an indexing destination. The default value is a NULL array. |
| pPointIndexingFcodeAllowMod | String | Modifier explaining the array format used in pPointIndexingFcodeAllow. |
| pPointIndexingFcodeDeny | String | List of NHD FCODEs to deny when choosing an indexing destination. The default value is a NULL array. |
| pPointIndexingFcodeDenyMod | String | Modifier explaining the array format used in pPointIndexingFcodeDeny. |
| pPointIndexingMaxDist | Number | The maximum distance in KM to snap to a qualifying NHDPlus flowline. The default value is 2 KM. |
| pPointIndexingRaindropDist | Number | The maximum distance in KM to travel during a raindrop indexing action. Note this refers to the actual raindrop traversal, not the final distance snap which is controlled by the p_point_indexing_max_dist parameter. The default value is 5 KM. |
| pOutputPathFlag | String | 'TRUE' or 'FALSE' flag to indicate whether the point indexing engine will populate the output indexing path. Note: performance is better and service payload reduced using the the default 'FALSE' value. |
| pReturnFlowlineGeomFlag | Number | 'TRUE' or 'FALSE' flag indicating whether to return NHDPlus flowline(s) geometries. Default value is 'FALSE' to reduce service payload. |
Additional parameters specific to HTTP services are listed in the WATERS HTTP Services documentation.
Output Return Object
nhd_point_indexing_output
| Property | Datatype | Description |
|---|---|---|
| tid | Number | Identifier passed into the service via input parameters. |
| total_distance | Number | The total distance traveled during the indexing action. |
| path_distance | Number | The total distance traveled during the raindrop portion of the indexing action. |
| start_point | Geometry | Point geometry of the input point. |
| end_point | Geometry | Point geometry of the indexing result. |
| indexing_path | Geometry | Line geometry representing the path travelled by the indexing action. This result is only populated when the input p_output_path_flag parameter is 'TRUE'. |
| ary_flowlines | Array of Object |
See ow_indexed_flowline. |
| error_code | Number | Code indicating that the service returned an erroneous condition. A value of zero indicates success. |
| error_message | String | Message explaining any errors indicated by the error code. |
Note that while the service returns a single point geometry representing the intersecting location on the NHD, in reality that point may represent more than one flowline depending on the geography of the area. Thus the output object contains an array of indexed flowline objects. In the example sketch to the right, a network of three flowlines drains from left to right. The confluence point is the nearest NHD point for the repoint point and a large proportion of the area above the flowlines. Thus the service may return multiple flowlines in more cases than expected. In this situation the service user must evaluate which flowline to utilize for further analysis. For example by evaluating reach measures of the resulting flowlines, the user may decide to ignore flowlines upstream from the confluence point.
The output format for this service is JSON with GEOJSON formatted geometries.
HTTP Service
| Resource | Location |
|---|---|
| Runtime Endpoint |
https://ofmpub.epa.gov/waters10/PointIndexing.Service |
Database Service
Users with schema accounts on the EPA waters10 database instance may directly access the Point Indexing Service via a stored procedure interface. Input and output is managed via the objects described below. Callers need to create, submit, receive and interpret these objects for their own needs.
| Database Instance |
Schema | Resource |
|---|---|---|
| WATERS10 | NHDPLUS_INDEXING | POINT_INDEXING.INDEXER |
Changelog
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 updated web page content.