Jump to main content.

WATERS HTTP Services

Description

The HTTP Services provide easy lightweight HTTP access to the WATERS analytical web services. WATERS encourages consumers to use the WATERS JavaScript Library to access the HTTP Services instead of directly consuming them. The WATERS JavaScript Library provides a level of abstraction on top of the HTTP services to make them even easier to use. The WATERS JavaScript Library is maintained in tandem with the HTTP Services which alleviates the need for application developers to modify code when server side HTTP Services change.

Common HTTP Service Parameters

The following parameters are common to all WATERS HTTP services.

Property Datatype Description
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 Exit code for WGS84 instead.
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 in the results will be named with this value.
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.
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.
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 Exit for more information.  The default tolerance value for WATERS geometries stored using the NAD83 coordinate system is 0.05 meters.  Raising or lowering this value will affect performance with larger values producing speedier but less accurate results.
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.

Geometry Formats

Available 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
WKT OGC Well-Known Text Exit Also called "Simple Features", 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 Exit and 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.  Currently only GML version 2.1 is supported in WATERS services.
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 Exit for 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.

Jump to main content.