Point Indexing Service

Description
Usage Scenarios
Input

Parameters
HTTP Service Notes
SOAP Service Notes

Output

UML Diagram
Return Object
HTTP Service Notes
SOAP Service Notes

Javascript Library
HTTP Service
Web Service (SOAP)
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 NHD hydrography via either a straightforward 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 NHD 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.
Distance Example 1

Raindrop: The raindrop option is a more complex process which utilizes the NHDPlus Flow Direction Grid

to travel "downhill" to the nearest NHD flowline. Two parameters control the maximum distance traveled:
p_point_indexing_raindrop_dist: 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.

p_point_indexing_max_dist: 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 coast and beach NHD features.
Raindrop Example 2

In the example below, the first graphic shows a raindrop indexing action running to the same point as the examples above. However in the second graphic, the p_point_indexing_raindrop_dist 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.
Raindrop Example 3

Service users should carefully evaluate the utility of using raindrop indexing to relate their input point to the NHD. In some cases the underlying geography could be urban with storm sewer systems greatly altering the reality of any surface water traversal.

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 service to take the network location returned from this service and enter it into the Upstream/Downstream 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 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 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 service.]

Information Returned from Service

Reach code and measure of the nearest NHD medium resolution feature.

Input

Parameters

Parameter	Datatype	Description
pGeometry	Number	Point geometry to index to the NHD.
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 NHD.
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 NHD 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 much better and service payload reduced using the the default 'FALSE' value.
pReturnFlowlineGeomFlag	Number	'TRUE' or 'FALSE' flag indicating whether to return NHD flowline(s) geometries. Default value is 'FALSE' to reduce service payload.

HTTP Service Notes

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

SOAP Service Notes

The parameter listing for SOAP services is slightly different. Array parameters are not followed by a "mod" parameter as the array format is specified by the WSDL documentation. For SOAP services, the input geometry parameter is always OGC Well-Known Text (WKT) and thus the secondary "mod" parameter is simply a numeric value of the Oracle Spatial Reference ID.

Output

UML Diagram

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.

HTTP Service Notes

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

SOAP Service Notes

The SOAP service returns OGC GML 2.1 formatted geometries.

Javascript Library

Function Name
WATERS.Services.PointIndexingService

HTTP Service

Resource	Location
Runtime Endpoint	http://oaspub.epa.gov/waters10/waters_services/PointIndexingService

Web Service (SOAP)

EPA hosted Oracle Application Servers currently utilize an older version of Oracle Containers for J2EE (OC4J). The SOAP endpoints generated for OC4J by Oracle Jdeveloper have several limitations that service users should be aware of. While many service parameters take a NULL value to indicate that a particular parameter is not applicable or not to used, the service endpoint may report an error if any numeric parameters are left empty. Users may choose to either utilize the "simple" service interfaces whereby all parameters are accepted as strings or users may enter numeric values of -9999 to indicate NULL.

Resource	Location
Runtime Endpoint	http://iaspub.epa.gov/WATERSWebServices/OWServices
WSDL Endpoint	http://iaspub.epa.gov/WATERSWebServices/OWServices?WSDL

Sample SOAP Request (Oracle 10.2.0.2 OC4J):

<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ns1="http://iaspub.epa.gov/WATERSWebServices/OWServices"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
>
   <SOAP-ENV:Body>
      <ns1:pointIndexingService>
         <pInputGeometry xsi:type="xsd:string">POINT(-87.85148619382586 42.64456621992253)</pInputGeometry>
         <pInputGeometrySrid xsi:type="xsd:decimal">8265</pInputGeometrySrid>
         <pReachresolution xsi:type="xsd:decimal">3</pReachresolution>
         <pPointIndexingMethod xsi:type="xsd:string">DISTANCE</pPointIndexingMethod>
         <pPointIndexingFcodeAllow xsi:nil="true" xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:decimal[0]"/>
         <pPointIndexingFcodeDeny xsi:nil="true" xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:decimal[0]"/>
         <pPointIndexingMaxDist xsi:type="xsd:decimal">5</pPointIndexingMaxDist>
         <pPointIndexingRaindropDist xsi:type="xsd:decimal">5</pPointIndexingRaindropDist>
         <pOutputPathFlag xsi:type="xsd:string">TRUE</pOutputPathFlag>
         <pTolerance xsi:type="xsd:decimal">0.05</pTolerance>
      </ns1:pointIndexingService>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample Soap Response:

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
>
   <SOAP-ENV:Body>
      <ns1:pointIndexingServiceResponse
      xmlns:ns1="http://iaspub.epa.gov/WATERSWebServices/OWServices"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
      >
         <return
         xmlns:ns2="http://waters-waters/OWServices.xsd"
         xsi:type="ns2:waters_waters_NhdPointIndexingOutputUser"
         >
            <startPoint xsi:type="xsd:string">&lt;gml:Point srsName=&quot;SDO:8265&quot; xmlns:gml=&quot;http://www.opengis.net/gml&quot;&gt;&lt;gml:coordinates decimal=&quot;.&quot; cs=&quot;,&quot; ts=&quot; &quot;&gt;-87.85148619382586,42.64456621992253 &lt;/gml:coordinates&gt;&lt;/gml:Point&gt;</startPoint>
            <aryFlowlines xsi:type="ns2:waters_waters_WatersGmlFlowlineList">
               <array xmlns:ns3="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="ns3:Array" ns3:arrayType="ns2:waters_waters_WatersGmlFlowlineUser[1]">
                  <item xsi:type="ns2:waters_waters_WatersGmlFlowlineUser">
                     <vertices xsi:type="xsd:decimal">41</vertices>
                     <wbdHuc12Percent xsi:type="xsd:decimal">1</wbdHuc12Percent>
                     <shape xsi:type="xsd:string">&lt;gml:Point srsName=&quot;SDO:8265&quot; xmlns:gml=&quot;http://www.opengis.net/gml&quot;&gt;&lt;gml:coordinates decimal=&quot;.&quot; cs=&quot;,&quot; ts=&quot; &quot;&gt;-87.8534801076,42.650293667 &lt;/gml:coordinates&gt;&lt;/gml:Point&gt;</shape>
                     <reachcode xsi:type="xsd:string">04040002000088</reachcode>
                     <fcode xsi:type="xsd:decimal">46006</fcode>
                     <comid xsi:type="xsd:decimal">12169187</comid>
                     <offset xsi:type="xsd:decimal">0</offset>
                     <wbdHuc12 xsi:type="xsd:string">040400020403</wbdHuc12>
                     <gnisId xsi:type="xsd:string">01571389</gnisId>
                     <tmeasure xsi:type="xsd:decimal">94.68703</tmeasure>
                     <gnisName xsi:type="xsd:string">Pike River</gnisName>
                     <nhdplusRegion xsi:type="xsd:string">04</nhdplusRegion>
                     <wbareacomi xsi:type="xsd:decimal" xsi:nil="true"/>
                     <nhdplusVersion xsi:type="xsd:string">01_02</nhdplusVersion>
                     <fmeasure xsi:type="xsd:decimal">94.68703</fmeasure>
                     <waterbodies xsi:type="xsd:int">0</waterbodies>
                     <reachresolution xsi:type="xsd:decimal">3</reachresolution>
                     <reachsmdate xsi:type="xsd:dateTime" xsi:nil="true"/>
                  </item>
               </array>
            </aryFlowlines>
            <pathDistance xsi:type="xsd:decimal">0.660456827303308</pathDistance>
            <tid xsi:type="xsd:decimal">1</tid>
            <indexingPath xsi:type="xsd:string">&lt;gml:LineString srsName=&quot;SDO:8265&quot; xmlns:gml=&quot;http://www.opengis.net/gml&quot;&gt;&lt;gml:coordinates decimal=&quot;.&quot; cs=&quot;,&quot; ts=&quot; &quot;&gt;-87.85148619382586,42.64456621992253 -87.8534801076,42.650293667 &lt;/gml:coordinates&gt;&lt;/gml:LineString&gt;</indexingPath>
            <endPoint xsi:type="xsd:string">&lt;gml:Point srsName=&quot;SDO:8265&quot; xmlns:gml=&quot;http://www.opengis.net/gml&quot;&gt;&lt;gml:coordinates decimal=&quot;.&quot; cs=&quot;,&quot; ts=&quot; &quot;&gt;-87.8534801076,42.650293667 &lt;/gml:coordinates&gt;&lt;/gml:Point&gt;</endPoint>
            <errorMessage xsi:type="xsd:string" xsi:nil="true"/>
            <errorCode xsi:type="xsd:decimal">0</errorCode>
            <totalDistance xsi:type="xsd:decimal">0.660456827303308</totalDistance>
         </return>
      </ns1:pointIndexingServiceResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Database Service

Users with schema accounts on the EPA waters10 database instance may directly access the upstream/downstream 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	ow_service	nhd_indexing_service.point_indexing_main

Sample Database Service Request:

-- Create a table to hold your results
CREATE TABLE nhd_point_indexing_results (input CLOB, output CLOB);

-- Run the raindrop service
DECLARE
   sdo_input    SDO_GEOMETRY;
   obj_output   ow_service.nhd_point_indexing_output;
   clb_input    CLOB;
   clb_output   CLOB;
BEGIN

   -----------------------------------------------
   -- Step 1
   -- Create the input parameters
   -----------------------------------------------
   sdo_input := SDO_GEOMETRY(
      2001,
      8265,
      NULL,
      SDO_ELEM_INFO_ARRAY(
         1,
         1,
         1
      ),
      SDO_ORDINATE_ARRAY(
         -85.9697971529134,
         43.4583773406535
      )
   );
   
   -----------------------------------------------
   -- Step 2
   -- Run the database service
   -----------------------------------------------
   obj_output := ow_service.nhd_indexing_service.point_indexing_main(
      1,
      sdo_input
   );
   
   -----------------------------------------------
   -- Step 3
   -- Serialize the input and output into CLOBs
   -----------------------------------------------
   clb_input  := XMLTYPE(sdo_input).getClobVal();
   clb_output := XMLTYPE(obj_output).getClobVal();
   
   -----------------------------------------------
   -- Step 4
   -- Pop values into the table
   -----------------------------------------------
   EXECUTE IMMEDIATE
   'INSERT INTO nhd_point_indexing_results VALUES(:p01,:p02)'
   USING clb_input,clb_output;
   COMMIT;
   
END;

-- Then inspect the results in the nhd_point_indexing_results table.
-- Note that empty attributes and child objects will not be represented in the serialized XML.

Changelog

Version: 2.0 - Released: August 31, 2009

Initial Release of HTTP Services and updated web page content

Point Indexing Service

Description

Capabilities:

Usage Scenarios

Hazardous Chemical Spill

Translate User Click to Stream Address

Input

Parameters

HTTP Service Notes

SOAP Service Notes

Output

UML Diagram

Return Object

nhd_point_indexing_output

HTTP Service Notes

SOAP Service Notes

Javascript Library

HTTP Service

Web Service (SOAP)

Sample SOAP Request (Oracle 10.2.0.2 OC4J):

Sample Soap Response:

Database Service

Sample Database Service Request:

Changelog

Version: 2.0 - Released: August 31, 2009

Local Navigation