Name 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

Advanced query function to find USGS GNIS water feature names and provide general location information for NHD features.

Usage Scenarios

Mapping "Zoom to" Function

Problem Statement

User wants to center map canvas on a particular water feature knowing only the name of the waterbody and general location information (state, county, etc.). User wants text completion option where suggested matching names are provided as the user begins typing the name.

Desired Information

Bounding box information for the NHD feature corresponding to the user’s water feature.

Information Returned from Service

Part I: List of water feature names that match the user’s water feature name or partial name, with additional information such as state and county to allow the user to identify the correct water feature. Part II: Bounding box information for the user selected water feature.

Water manager – "QA/Find my Waterbody"

Problem Statement

Quality assurance on water feature name entries and data standardization and improvement for names that with minor misspellings or non-standard formations. Could be done as an automated check or as a operator assisted check.

Desired Information

List of matching feature names or nearly matching names.

Information Returned from Service

List of water features matching or nearly matching the input feature name with additional information such as state, county, bounding box which can be used to QA/improve the data and/or provide additional data elements for the requesting program data store.

Input

Parameters

Parameter	Datatype	Description
pFullText	String	If executing a fulltext query, the full text of the feature name to search for. Case is ignored.
pFullTextRegex	String	Any regular expression modifiers when executing a regular expression query.
pBasename	String	If executing a composite query, the basename of the feature name to search for. Case is ignored.
pBasenameRegex	String	Any regular expression modifiers when executing a regular expression query.
pHydrography	String	If executing a composite query, the hydrology name of the feature to search for. Case is ignored.
pHydrographyRegex	String	Any regular expression modifiers when executing a regular expression query.
pDirectional	String	If executing a composite query, the directional part of the feature name to search for. Case is ignored.
pDirectionalRegex	String	Any regular expression modifiers when executing a regular expression query.
pOperator	String	EQ/LIKE/REG_EX/JARO - indicating the type of query to execute. Note that REG_EX and JARO queries do not utilize table indexes and may take a very long time to return results. Default value is 'EQ'.
pQueryType	String	FULLNAME/COMPOSITE - indicating which type of text matching query to execute. Default value is to examine pFullname and execute FULLNAME query if a value is provided.
pQueryLimit	Number	Numeric value to halt returning results at. Default is no limit.
pJWThreshold	Number	Numeric value of the Jaro Winkler text matching algorithm if executing a Jaro Winkler text match. Default value is 90.
pResolution	Number	0/1/2/3 values. 0 indicates examine all resolutions. 1 indicates examine local resolution NHD only. 2 indicates examine high resolution NHD only. 3 indicates examine medium resolution NHD only.
pSourceTable	String	nhdpoint/nhdline/nhdarea/nhdflowline/nhdwaterbody - used to limit queries to specific NHD tables.
pSourceTableMod	String	Modifier explaining the array format used in pSourceTable. See the complex object modifier descriptions for more information.
pState	String	Any postal abbreviation to limit queries to the primary state value listed in the USGS gnis_id records.
pStateMod	String	Modifier explaining the array format used in pState. See the complex object modifier descriptions for more information.
pCountyFips5	String	Any FIPS5 numeric value of a US county. Used to limit queries to the primary county value listed in the USGS gnis_id records.
pCountyFips5Mod	String	Modifier explaining the array format used in pCountyFips5. See the complex object modifier descriptions for more information.
pSubbasin	String	Any 8 digit numeric value representing a WBD subbasin. Used to limit queries to specific WBD subbasins.
pSubbasinMod	String	Modifier explaining the array format used in pSubbasin. See the complex object modifier descriptions for more information.
pGnisClass	String	Any string value used to limit queries to the feature_type values listed in the USGS gnis_id records.
pGnisClassMod	String	Modifier explaining the array format used in pGnisClass. See the complex object modifier descriptions for more information.
pFtype	String	Any string value used to limit queries to the ftype values in the NHD records.
pFtypeMod	String	Modifier explaining the array format used in pFtype. See the complex object modifier descriptions for more information.
pBreakBySubbasin	String	TRUE/FALSE - flag to group results by unique NHD subbasins.
pBreakByFcode	String	TRUE/FALSE - flag to group results by unique NHD fcodes.

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

Property	Datatype	Description
results	Array of Object	Object Type: namesrv_results

Supporting Objects

namesrv_results

Property	Datatype	Description
featureId	String	The gnis_id of the result record.
featureName	String	The gnis_name of the result record.
featureClass	String	The gnis feature class of the result record.
primaryState	String	The 2 byte primary state abbreviation of the result record as defined by gnis.
primaryStateFips	String	The 2 byte FIPS code of the primary state as defined by gnis.
primaryCounty	String	The primary county name of the result record as defined by gnis.
primaryCountyFips	String	The 3 bytes FIPS code of the primary county as defined by gnis.
gnisPrimaryStem	String	The primary basename or stem of the gnis name.
gnisPrimaryHydro	String	The primary hydro name of the gnis name.
gnisPrimaryDir	String	The primary directional value of the gnis name.
gnisSecondaryStem	String	The secondary basename or stem of the gnis name (if any).
gnisSecondaryHydro	String	The secondary hydro name of the gnis name.
gnisSecondaryDir	String	The secondary directional value of the gnis name.
gnisCentroid	Geometry	Geometry representing the centroid of the result record as defined by GNIS.
resolution	Number	2/3 - the resolution of the NHD records with 2 = high resolution and 3 = medium resolution.
sourceSchema	String	The schema holding the source NHD records in the RAD (for lookup).
sourceTable	String	The table holding the source NHD records in the RAD (for lookup).
subbasin	String	The HUC8 or subbasin value of the NHD records (if any).
ftype	String	The ftype of the matching NHD records.
fcode	Number	The fcode of the matching NHD records.
nhdMbr	Geometry	Geometry representing the maximum bounding rectangle of the matching NHD feature. Note that in the case that the matching NHD record is a single point, that point will be stored in this field.
shape	Geometry	The aggregated NHD geometry of the GNIS feature.

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. The aggregated NHD feature (shape) is not available from the SOAP service.

Javascript Library

Function Name
WATERS.Services.NameService

HTTP Service

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

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:nameService>
         <pFulltext xsi:type="xsd:string">bass LAK%</pFulltext>
         <pFulltextRegex xsi:type="xsd:string" xsi:nil="true"/>
         <pBasename xsi:type="xsd:string" xsi:nil="true"/>
         <pBasenameRegex xsi:type="xsd:string" xsi:nil="true"/>
         <pHydrography xsi:type="xsd:string" xsi:nil="true"/>
         <pHydrographyRegex xsi:type="xsd:string" xsi:nil="true"/>
         <pDirectional xsi:type="xsd:string" xsi:nil="true"/>
         <pDirectionalRegex xsi:type="xsd:string" xsi:nil="true"/>
         <pOperator xsi:type="xsd:string">LIKE</pOperator>
         <pQueryType xsi:type="xsd:string" xsi:nil="true"/>
         <pQueryLimit xsi:type="xsd:decimal" xsi:nil="true"/>
         <pJwthreshold xsi:type="xsd:decimal" xsi:nil="true"/>
         <pResolution xsi:type="xsd:decimal">2</pResolution>
         <pSourceTable
          xsi:nil="true"
          xsi:type="SOAP-ENC:Array"
          SOAP-ENC:arrayType="xsd:string[0]"
         />
         <pState
          xmlns:ns1="http://waters-waters/OWServices.xsd"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:type="ns1:waters_waters_OwStringVry"
         >
            <array
             xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
             xsi:type="SOAP-ENC:Array"
             SOAP-ENC:arrayType="xsd:string[1]"
            >
               <string xsi:type="xsd:string">WI</string>
            </array>
         </pState>
         <pCountyFips5
          xmlns:ns1="http://waters-waters/OWServices.xsd"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:type="ns1:waters_waters_OwStringVry"
         >
            <array
             xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
             xsi:type="SOAP-ENC:Array"
             SOAP-ENC:arrayType="xsd:string[1]"
            >
               <string xsi:type="xsd:string">55107</string>
            </array>
         </pCountyFips5>
         <pSubbasin xsi:nil="true" xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[0]"/>
         <pGnisClass
          xsi:nil="true"
          xsi:type="SOAP-ENC:Array"
          SOAP-ENC:arrayType="xsd:string[0]"
         />
         <pFtype xsi:nil="true" xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[0]"/>
         <pBreakBySubbasin xsi:type="xsd:string" xsi:nil="true"/>
         <pBreakByFcode xsi:type="xsd:string" xsi:nil="true"/>
      </ns1:nameService>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample SOAP Response (Oracle 10.2.0.2 OC4J):

<?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:nameServiceResponse 
       xmlns:ns1="http://epadev.induscorp.com/WATERSWebServices/OWServices" 
       SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
      >
         <return 
          xmlns:ns2="http://waters-waters/OWServices.xsd" 
          xsi:type="ns2:waters_waters_NamesrvOutputUser"
         >
            <results xsi:type="ns2:waters_waters_NamesrvList">
               <array 
                xmlns:ns3="http://schemas.xmlsoap.org/soap/encoding/" 
                xsi:type="ns3:Array" 
                ns3:arrayType="ns2:waters_waters_NamesrvResultsUser[4]"
               >
                  <item xsi:type="ns2:waters_waters_NamesrvResultsUser">
                     <primaryCountyFips xsi:type="xsd:string">107</primaryCountyFips>
                     <gnisSecondaryHydro xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryHydro>
                     <primaryState xsi:type="xsd:string">WI</primaryState>
                     <sourceTable xsi:type="xsd:string">nhdwaterbody</sourceTable>
                     <primaryCounty xsi:type="xsd:string">RUSK</primaryCounty>
                     <gnisPrimaryStem xsi:type="xsd:string">BASS</gnisPrimaryStem>
                     <featureClass xsi:type="xsd:string">LAKE</featureClass>
                     <primaryStateFips xsi:type="xsd:string">55</primaryStateFips>
                     <fcode xsi:type="xsd:decimal" xsi:nil="true"></fcode>
                     <resolution xsi:type="xsd:decimal">2</resolution>
                     <gnisSecondaryDir xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryDir>
                     <gnisCentroidGeom 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;-91.255153,45.4052423 &lt;/gml:coordinates&gt;&lt;/gml:Point&gt;
                     </gnisCentroidGeom>
                     <gnisSecondaryStem xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryStem>
                     <gnisPrimaryDir xsi:type="xsd:string" xsi:nil="true"></gnisPrimaryDir>
                     <featureId xsi:type="xsd:string">01561239</featureId>
                     <subbasin xsi:type="xsd:string" xsi:nil="true"></subbasin>
                     <featureName xsi:type="xsd:string">BASS LAKE</featureName>
                     <sourceSchema xsi:type="xsd:string">rad_nhdhi</sourceSchema>
                     <gnisPrimaryHydro xsi:type="xsd:string">LAKE</gnisPrimaryHydro>
                     <ftype xsi:type="xsd:string" xsi:nil="true"></ftype>
                     <mbrGeom xsi:type="xsd:string">
                        &lt;gml:Box 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;-91.2585257,45.4034602 -91.2517631,45.40750553 &lt;/gml:coordinates&gt;&lt;/gml:Box&gt;
                     </mbrGeom>
                  </item>
                  <item xsi:type="ns2:waters_waters_NamesrvResultsUser">
                     <primaryCountyFips xsi:type="xsd:string">107</primaryCountyFips>
                     <gnisSecondaryHydro xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryHydro>
                     <primaryState xsi:type="xsd:string">WI</primaryState>
                     <sourceTable xsi:type="xsd:string">nhdwaterbody</sourceTable>
                     <primaryCounty xsi:type="xsd:string">RUSK</primaryCounty>
                     <gnisPrimaryStem xsi:type="xsd:string">BASS</gnisPrimaryStem>
                     <featureClass xsi:type="xsd:string">LAKE</featureClass>
                     <primaryStateFips xsi:type="xsd:string">55</primaryStateFips>
                     <fcode xsi:type="xsd:decimal" xsi:nil="true"></fcode>
                     <resolution xsi:type="xsd:decimal">2</resolution>
                     <gnisSecondaryDir xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryDir>
                     <gnisCentroidGeom 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;-91.4926621,45.4246838 &lt;/gml:coordinates&gt;&lt;/gml:Point&gt;
                     </gnisCentroidGeom>
                     <gnisSecondaryStem xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryStem>
                     <gnisPrimaryDir xsi:type="xsd:string" xsi:nil="true"></gnisPrimaryDir>
                     <featureId xsi:type="xsd:string">01561241</featureId>
                     <subbasin xsi:type="xsd:string" xsi:nil="true"></subbasin>
                     <featureName xsi:type="xsd:string">BASS LAKE</featureName>
                     <sourceSchema xsi:type="xsd:string">rad_nhdhi</sourceSchema>
                     <gnisPrimaryHydro xsi:type="xsd:string">LAKE</gnisPrimaryHydro>
                     <ftype xsi:type="xsd:string" xsi:nil="true"></ftype>
                     <mbrGeom xsi:type="xsd:string">
                        &lt;gml:Box 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;-91.4980321,45.42136833 -91.4889813,45.4294342 &lt;/gml:coordinates&gt;&lt;/gml:Box&gt;
                     </mbrGeom>
                  </item>
                  <item xsi:type="ns2:waters_waters_NamesrvResultsUser">
                     <primaryCountyFips xsi:type="xsd:string">107</primaryCountyFips>
                     <gnisSecondaryHydro xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryHydro>
                     <primaryState xsi:type="xsd:string">WI</primaryState>
                     <sourceTable xsi:type="xsd:string">nhdwaterbody</sourceTable>
                     <primaryCounty xsi:type="xsd:string">RUSK</primaryCounty>
                     <gnisPrimaryStem xsi:type="xsd:string">BASS</gnisPrimaryStem>
                     <featureClass xsi:type="xsd:string">LAKE</featureClass>
                     <primaryStateFips xsi:type="xsd:string">55</primaryStateFips>
                     <fcode xsi:type="xsd:decimal" xsi:nil="true"></fcode>
                     <resolution xsi:type="xsd:decimal">2</resolution>
                     <gnisSecondaryDir xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryDir>
                     <gnisCentroidGeom 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;-91.180986,45.5238543 &lt;/gml:coordinates&gt;&lt;/gml:Point&gt;
                     </gnisCentroidGeom>
                     <gnisSecondaryStem xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryStem>
                     <gnisPrimaryDir xsi:type="xsd:string" xsi:nil="true"></gnisPrimaryDir>
                     <featureId xsi:type="xsd:string">01561246</featureId>
                     <subbasin xsi:type="xsd:string" xsi:nil="true"></subbasin>
                     <featureName xsi:type="xsd:string">BASS LAKE</featureName>
                     <sourceSchema xsi:type="xsd:string">rad_nhdhi</sourceSchema>
                     <gnisPrimaryHydro xsi:type="xsd:string">LAKE</gnisPrimaryHydro>
                     <ftype xsi:type="xsd:string" xsi:nil="true"></ftype>
                     <mbrGeom xsi:type="xsd:string">
                        &lt;gml:Box 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;-91.1837221,45.5213614 -91.17934137,45.5257254 &lt;/gml:coordinates&gt;&lt;/gml:Box&
                     gt;</mbrGeom>
                  </item>
                  <item xsi:type="ns2:waters_waters_NamesrvResultsUser">
                     <primaryCountyFips xsi:type="xsd:string">107</primaryCountyFips>
                     <gnisSecondaryHydro xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryHydro>
                     <primaryState xsi:type="xsd:string">WI</primaryState>
                     <sourceTable xsi:type="xsd:string">nhdwaterbody</sourceTable>
                     <primaryCounty xsi:type="xsd:string">RUSK</primaryCounty>
                     <gnisPrimaryStem xsi:type="xsd:string">BASS</gnisPrimaryStem>
                     <featureClass xsi:type="xsd:string">LAKE</featureClass>
                     <primaryStateFips xsi:type="xsd:string">55</primaryStateFips>
                     <fcode xsi:type="xsd:decimal" xsi:nil="true"></fcode>
                     <resolution xsi:type="xsd:decimal">2</resolution>
                     <gnisSecondaryDir xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryDir>
                     <gnisCentroidGeom 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;-91.2465473,45.6374617 &lt;/gml:coordinates&gt;&lt;/gml:Point&gt;
                     </gnisCentroidGeom>
                     <gnisSecondaryStem xsi:type="xsd:string" xsi:nil="true"></gnisSecondaryStem>
                     <gnisPrimaryDir xsi:type="xsd:string" xsi:nil="true"></gnisPrimaryDir>
                     <featureId xsi:type="xsd:string">01561252</featureId>
                     <subbasin xsi:type="xsd:string" xsi:nil="true"></subbasin>
                     <featureName xsi:type="xsd:string">BASS LAKE</featureName>
                     <sourceSchema xsi:type="xsd:string">rad_nhdhi</sourceSchema>
                     <gnisPrimaryHydro xsi:type="xsd:string">LAKE</gnisPrimaryHydro>
                     <ftype xsi:type="xsd:string" xsi:nil="true"></ftype>
                     <mbrGeom xsi:type="xsd:string">
                        &lt;gml:Box 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;-91.2477607,45.6367776 -91.2450789,45.638629 &lt;/gml:coordinates&gt;&lt;/gml:Box&gt;
                     </mbrGeom>
                  </item>
               </array>
            </results>
         </return>
      </ns1:nameServiceResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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 ow_service namesrv

Database Instance	Schema	Resource
WATERS10	ow_service	namesrv

Changelog

Version: 2.0 - Released: August 31, 2009

Initial Release of HTTP Services and new Web Page Layout

Name Service

Description

Usage Scenarios

Mapping "Zoom to" Function

Water manager – "QA/Find my Waterbody"

Input

Parameters

HTTP Service Notes

SOAP Service Notes

Output

UML Diagram

Return Object

Supporting Objects

namesrv_results

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 (Oracle 10.2.0.2 OC4J):

Database Service

Changelog

Version: 2.0 - Released: August 31, 2009

Local Navigation