WATERS HTTP Services
Description
The HTTP Services provide easy lightweight HTTP access to the WATERS analytical web services.
For more information about individual services including endpoints, service-specific parameters and usage notes, reference the WATERS Web, Mapping and Database Services page. For coding examples of how to consume and display WATERS services, see the WATERS Code Playground Exit.
Common HTTP Service Parameters
The following parameters are common to most WATERS HTTP services.
| Property | Datatype | Description |
|---|---|---|
| optFeatureID | Number | For results containing numerous iterable geometry objects, each object will be assigned a feature id beginning with the value of this parameter or 1 if the parameter is not specified. |
| optOut2D | String | TRUE/FALSE flag which will remove any height or measure dimensions from service geometry output. While most WATERS datasets are two-dimensional, a notable few (NHD flowlines for example) carry extra measure information as a third dimension. Setting this flag to TRUE will guarantee removal of this extraneous information on the server side of the transaction lowing the cost of the service call. |
| optOutCS | String | By default all geometry output from WATERS services utilize the NAD83 geodetic coordinate system. Use this parameter to specify if a different coordinate system for output geometries is desired. All server side transformations are highly dependent on Oracle Spatial settings, particularly in regards to those coordinate systems which are not part of Oracle Spatial by default. Use the format "SRID=4326" to specify that the server, then utilize spatial reference id 4326 (WGS84) to transform outgoing geometries. If the exact Oracle Spatial SRID is unknown, use the format "EPSG:4326" to utilize the OGP Surveying & Positioning Committee Exitcode for WGS84 instead. |
| optOutFormat | String | While the majority of WATERS HTTP services produce JSON formatted output, some services are also available as KML. Use this option to control the desired output format. |
| optOutGeomFormat | String | For data structures containing geometries, the output format of the geometries defaults to the best match for the format of the output data structure. For example, requesting the JSON data structure format produces by default GEOJSON formatted geometries. Use this parameter to override defaults and force custom output geometry format. See the geometry formats section for more information on available formats. |
| optOutPrettyPrint | Number | Optional feature to attempt to format output with logical indentations and linefeeds to promote visualization and debugging efforts. Numeric value indicates the number of three-space indentations to begin pretty printing efforts at. Value of 0 begins at the left margin. Do not pass any value for compacted results. Pretty printed results should never be utilized in production. |
| optOSTolerance | String | Geometry functions and transformations within Oracle Spatial utilize the concept of tolerance extensively. Tolerance values indicate the minimum distance by which two points are considered distinct when manipulating geometries. See Oracle Spatial Documentation Exitfor more information. The default tolerance value for WATERS geometries stored using the NAD83 coordinate system is 0.001 meters. Raising or lowering this value will affect performance with larger values producing speedier but less accurate results. |
| optQueueResults | String | Optional feature which will execute the given service in an offline queue for pickup via the Results Queue Service. Instead of returning service output synchronously following processing. The user will be returned an identification id which can be used in subsequent calls to the Results Queue Service to fetch results at a later time. Valid parameter values for this option are ASYNCHRONOUS or THREADED. |
| optQueueID | String | Optional value used to identify a given submission to the Results Queue Service. When using this parameter the value MUST be unique to the submission otherwise creating an error condition. Leave this parameter blank to accept the server-generated identification number which is always guaranteed to be unique and safe in all circumstances. |
| optSubmissionID | String | Identifier submitted with a service request representing a unique or meaningful name for the request. This value will be reflected in return results allowing control over multiple asynchronous service calls. In KML-formatted requests the upper-most folder-equivalent in the results will be named with this value. |
| optStyleURL | String | Keyword utilized by services when creating output data structures for stylization of geometries. The optStyleURL parameter is used as a prefix to the geometry field name in the output object. |
| optOutPruneNumber | Number | For services returning spatial data, oftentimes the coordinates may be returned having a large (up to 32 digits) amount of decimal precision. If that amount of precision is not required, the service payload may be substantially reduced by pruning the coordinate precision to a given number of decimal places. All services currently prune by default to 16 places of precision. This parameter may be used to tune this default up or down as needed by the user. Excessive pruning of coordinates may result in invalid geometries. |
| optVerticeLimit | Number | Depending on the parameters used, WATERS services may return results that are too large to reasonably transfer via a HTTP service. In most cases the attribute information associated with output results are only a small portion of the total payload. By far, the geometry is the largest data structure being passed to the client. Restricting results to those having a total count of vertices less than this parameter is an effective way to avoid service timeouts. While the service endpoint may cap total vertices returned at a certain number, the client has the option to use this parameter to further restrict output results. This parameter cannot be used to loosen those vertice restrictions imposed by the service endpoint. |
| optNHDDataModel | String | Parameter controlling the format of the output object. Some services return multiple formats depending on the evolution of the data model and service feature expansion. Without this parameter, the service will return the current default output object as defined on the service description page. |
| optNHDPlusDataset | String | Parameter controlling the source dataset used for generating service output. Without this parameter the service will return the current default NHDPlus dataset (currently 2.1). |
Geometry Formats
WATERS HTTP services allow the serialization of Oracle Spatial geometries into several common formats suitable for transference via web services. Note that following formats refer only to the serialization of the geometry structures themselves.
| Format Abbreviation | Format | Description |
|---|---|---|
| SFA | OGC Simple Feature Access Exit | Also called "Well-Known Text", this common format is defined by OGC specifications. WATERS services support the full OGC WKT specification with the addition of "extended" WKT (EWKT Exit) supporting Z values and LRS values. |
| GEOKML | OGC Keyhole Markup Language Exit | Popular XML-based format used in desktop products such as Google Earth Exitand ESRI ArcGIS Explorer Exit. |
| GEOJSON | JSON Geometry and Feature Description Format Exit | Format which stores geometries as ECMAScript-ready structures. Very useful when consuming services via web browser clients using Ajax-technologies such as OpenLayers Exit. GEOJSON is the default geometry format for most WATERS HTTP services. |
| GEOGML | OGC Geography Markup Language Exit | Complex XML-based format defined by OGC specifications. For backwards compatibility, GEOGML maps to GML version 2.1. Output is generated via the Oracle Spatial function, SDO_UTIL.TO_GMLGEOMETRY. |
| GEOGML3 | OGC Geography Markup Language Exit | Complex XML-based format defined by OGC specifications. GEOGML currently maps to GML version 3.1.1. Output is generated via the Oracle Spatial function, SDO_UTIL.TO_GML311GEOMETRY. |
| SQLSDO | Oracle Object Constructor Format | Debugging format which converts Oracle Spatial geometries into their equivalent PL/SQL constructor format. |
Complex Object Modifiers
WATERS HTTP services have been designed to accept arrays and geometries as complex objects. Below is the current list of object types accepted and modifiers required for their use. Future formats will include JSON and XML object serializations. Modifiers are either single scalar values or comma-delimited lists of keywords. Note: due to the lack of universal standards when passing date values via web services, dates are also defined as "complex" data structures.
| Complex Object | Modifer | Description |
|---|---|---|
| Date | Oracle Date Format | All date parameters provided to WATERS web services include a secondary modifier field relating to the format parameter of the Oracle database TO_DATE function. See Oracle documentation Exitfor usage. A common date format would be MM/DD/YYYY. |
| Geometry | WKT,SRID=X | When the geometry modifier begins with the keyword WKT, the geometry field is considered to be formatted as OGC Well-Known Text Exitor Extended WKT Exit. For all WKT formats, provide the Oracle Spatial SRID as a second keyword in the modifier field using the format SRID=X where X is the SRID value to utilize. |
| Array | <null> | When the array modifier is NULL, then the data in the array field is considered to be a single scalar. Many services require one or more inputs with the majority of usage only requiring that single input. |
| Array | <one-byte delimiter> | The simplest way to submit an array of values is serialize them as a delimited list. When the modifier is a single-byte value, that value is assumed to be the delimiter for a list of values in the array field. A common usage is a comma modifier indicating the array field contains a comma-delimited list of values. |
| Array of Objects | |, | For services requiring more complex input than simple scalars or short lists, technologies such as SOAP, XML and JSON are best utilized for the purpose. However, some more simplistic and rigid object arrays can be easily modeled with a double-delimiter such as a pipe and comma. For example, a list of an object which requires a three data element constructor can be expressed as A1|B1|C1,A2|B2|C3,A3|B3|C3. |