5. Web Services

Sensor Web Services

Sensor Observation Service

The OGC Sensor Observation Service (SOS) is a Web Service that allows users to request observations and associated metadata of sensors. Within the context of the SWE framework, the SOS represents the core service to access sensor data in an interoperable and standardized manner. The service specification (version 2.0), which can be downloaded from

http://www.opengeospatial.org/standards/sos,

defines several mandatory as well as some optional operations, as introduced in the following. With regard to the core operations (GetCapabilities, DescribeSensor, GetObservation), a description, the service interface (request parameters) and an example is presented. For most optional operations, only a description of the method as well as the request parameters is included. Most of the subsequent information was extracted from the SOS 2.0 standard specification (OGC 2012). A valid SOS instance is available via the URL

http://insitu.webservice-energy.org/52n-sos-webapp.

It will be used throughout this section to present examples of the main operations.

GetCapabilities

Similar to other OGC services, the GetCapabilities operation responds with metadata about the service instance itself. Amongst others, the Capabilities document lists available sensors/procedures, offerings, observedProperties, featuresOfInterest as well as spatial and temporal bounding boxes of the available observations. A GetCapabilities request may contain the following parameters:

A full response document contains several sections offering metadata. The most relevant sections are:

• serviceIdentification: metadata about the service itself, such as title, versions, languages

• serviceProvider: metadata about the provider/organization, such as contact information

• operationsMetadata: metadata about the offered operations, including which operations are offered (like GetCapabilites, DescribeSensor, GetObservation, …), available bindings (e.g. POX, KVP, SOAP, JSON) and a URL endpoint.

• contents: metadata about available observation offerings including their associated properties such as identifier, procedure, reponseFormats, temporal and spatial aspects, …

• filterCapabilities: metadata about the supported spatial and temporal filter functionalities extension: container for extensions

Sending a capabilities request (e.g. http://insitu.webservice-energy.org/52n-sos-webapp/sos?service=SOS&REQUEST=GetCapabilities), results in a full capabilities document. As an excerpt, the following Listing presents an exemplary observation offering from the content section of the Capabilities document.

<?xml version="1.0" encoding="UTF-8"?>
<sos:ObservationOffering xmlns:sos="http://www.opengis.net/sos/2.0" xmlns:fes="http://www.opengis.net/fes/2.0" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:swe="http://www.opengis.net/swe/2.0" xmlns:swes="http://www.opengis.net/swes/2.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" service="SOS" version="2.0.0" xsi:schemaLocation="http://www.opengis.net/sos/2.0 http://schemas.opengis.net/sos/2.0/sos.xsd">
   <!-- identifier and name of the offering -->
   <swes:identifier>ENTPE-BH-KZ-CH1-QCfull</swes:identifier>
   <swes:name codeSpace="eng">ENTPE-BH-KZ-CH1-QCfull</swes:name>
   <swes:procedure>ENTPE-BH-KZ-CH1-QCfull</swes:procedure>
   <!-- available description format for sensor descriptions; here SensorML 1.0.1 and 2.0 as well as WaterML 2.0 -->
   <swes:procedureDescriptionFormat>http://www.opengis.net/sensorML/1.0.1</swes:procedureDescriptionFormat>
   <swes:procedureDescriptionFormat>http://www.opengis.net/sensorml/2.0</swes:procedureDescriptionFormat>
   <swes:procedureDescriptionFormat>http://www.opengis.net/waterml/2.0/observationProcess</swes:procedureDescriptionFormat>
   <!-- observed phenomena -->
   <swes:observableProperty>Direct Horizontal Irradiance</swes:observableProperty>
   <!-- bounding box of observed area -->
   <sos:observedArea>
      <gml:Envelope srsName="http://www.opengis.net/def/crs/EPSG/0/4326">
         <gml:lowerCorner>45.7786 4.9225</gml:lowerCorner>
         <gml:upperCorner>45.7786 4.9225</gml:upperCorner>
      </gml:Envelope>
   </sos:observedArea>
   <!-- period in time for which the mesaurment applies -->
   <sos:phenomenonTime>
      <gml:TimePeriod gml:id="phenomenonTime_122">
         <gml:beginPosition>2006-01-01T00:00:00.000Z</gml:beginPosition>
         <gml:endPosition>2016-01-01T00:00:00.000Z</gml:endPosition>
      </gml:TimePeriod>
   </sos:phenomenonTime>
   <!-- period in time for when the mesaurment was performed -->
   <sos:resultTime>
      <gml:TimePeriod gml:id="resultTime_122">
         <gml:beginPosition>2006-01-01T00:01:00.000Z</gml:beginPosition>
         <gml:endPosition>2016-01-01T00:00:00.000Z</gml:endPosition>
      </gml:TimePeriod>
   </sos:resultTime>
   <!-- available response formats; here JSON, O&amp;M 2.0 WaterML 2.0 -->
   <sos:responseFormat>application/json</sos:responseFormat>
   <sos:responseFormat>http://dd.eionet.europa.eu/schemaset/id2011850eu-1.0</sos:responseFormat>
   <sos:responseFormat>http://www.opengis.net/om/2.0</sos:responseFormat>
   <sos:responseFormat>http://www.opengis.net/waterml-dr/2.0</sos:responseFormat>
   <sos:responseFormat>http://www.opengis.net/waterml/2.0</sos:responseFormat>
   <!-- observation type; here Measurement -->
   <sos:observationType>http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement</sos:observationType>
   <!-- type of associated featureOfInterest -->
   <sos:featureOfInterestType>http://www.opengis.net/def/samplingFeatureType/OGC-OM/2.0/SF_SamplingPoint</sos:featureOfInterestType>
</sos:ObservationOffering>

DescribeSensor

The DescribeSensor operation can be used to retrieve a detailed sensor description about a certain sensor, encoded in a Sensor Model Language (SensorML) version 1.0.1 or 2.0 document. As sensor configuration and calibration might change over time, several different instances of a sensor description for the same sensor can be stored by a SOS, each being valid for a certain amount of time. To request a certain sensor description the following request parameters are offered:

For instance, an exemplar DescribeSensor request (using the binding POX) against the URL http://insitu.webservice-energy.org/52n-sos-webapp/service might look like:

<?xml version="1.0" encoding="UTF-8"?>
<swes:DescribeSensor xmlns:swes="http://www.opengis.net/swes/2.0" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:swe="http://www.opengis.net/swe/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" service="SOS" version="2.0.0" xsi:schemaLocation="http://www.opengis.net/swes/2.0 http://schemas.opengis.net/swes/2.0/swes.xsd http://www.opengis.net/swe/2.0 http://schemas.opengis.net/sweCommon/2.0/swe.xsd">
   <!-- reference to sensor/procedure using its identifier -->
   <swes:procedure>ENTPE-BH-KZ-CH1-QCfull</swes:procedure>
   <!-- definition of sensor description format; here SensorML 1.0.1 -->
   <swes:procedureDescriptionFormat>http://www.opengis.net/sensorML/1.0.1</swes:procedureDescriptionFormat>
   <!-- optional validTime: if not set, latest sensor description is returned -->
   <swes:validTime>
      <gml:TimePeriod gml:id="validTime">
         <gml:beginPosition>2014-08-14T15:02:43.219</gml:beginPosition>
         <gml:endPosition>2014-08-14t15:02:47</gml:endPosition>
      </gml:TimePeriod>
   </swes:validTime>
</swes:DescribeSensor>

With regard to the request,the following Listing presents the basic response structure. In particular, the SensorML description is included within DescribeSensorResponse/description/ SensorDescription/data/. The content is omitted here by intention.

<?xml version="1.0" encoding="UTF-8"?>
<swes:DescribeSensorResponse xmlns:swes="http://www.opengis.net/swes/2.0" xmlns:sml="http://www.opengis.net/sensorML/1.0.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <swes:procedureDescriptionFormat>http://www.opengis.net/sensorML/1.0.1</swes:procedureDescriptionFormat>
   <swes:description>
      <swes:SensorDescription>
         <swes:data>
            <sml:Component>
               <!-- details omitted for brevity -->
            </sml:Component>
         </swes:data>
      </swes:SensorDescription>
   </swes:description>
</swes:DescribeSensorResponse>

GetObservation

The GetObservation operation represents the core operation of the SOS to request observation data encoded in Observations & Measurements (O&M) standard or any other suitable format (O&M is recommended though for interoperability). In general a SOS might host a huge number of observations, each composed within a certain offering. For this reason, several filter options can be submitted in a GetObservation request, as listed in the below table. Note that although all filter options are not mandatory, at least some filters should be set in order to reduce the length of the response document.

An exemplar GetObservation request against http://insitu.webservice-energy.org/52n-sos-webapp/service using POX binding is illustrated in the below example. It contains an example for each filter option.

<?xml version="1.0" encoding="UTF-8"?>
<sos:GetObservation xmlns:sos="http://www.opengis.net/sos/2.0" xmlns:fes="http://www.opengis.net/fes/2.0" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:swe="http://www.opengis.net/swe/2.0" xmlns:swes="http://www.opengis.net/swes/2.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" service="SOS" version="2.0.0" xsi:schemaLocation="http://www.opengis.net/sos/2.0 http://schemas.opengis.net/sos/2.0/sos.xsd">
   <!-- optional sensor identifier, multiple values possible -->
   <sos:procedure>ENTPE-BH-KZ-CH1-QCfull</sos:procedure>
   <!-- optional offering identifier, multiple values possible -->
   <sos:offering>ENTPE-BH-KZ-CH1-QCfull</sos:offering>
   <!-- optional phenomena isentifier, multiple values possible -->
   <sos:observedProperty>Direct Horizontal Irradiance</sos:observedProperty>
   <!-- optional definition of a period in time, for which observation should be returned -->
   <sos:temporalFilter>
      <fes:During>
         <fes:ValueReference>phenomenonTime</fes:ValueReference>
         <gml:TimePeriod gml:id="tp_1">
            <gml:beginPosition>2014-11-19T14:00:00.000+01:00</gml:beginPosition>
            <gml:endPosition>2014-11-19T15:00:00.000+01:00</gml:endPosition>
         </gml:TimePeriod>
      </fes:During>
   </sos:temporalFilter>
   <!-- optional identifier of featureOfInterest, multiple values possible -->
   <sos:featureOfInterest>ENTPE</sos:featureOfInterest>
   <!-- optional definition of a spatial filter for which observations should be returned -->
   <sos:spatialFilter>
      <fes:BBOX>
         <fes:ValueReference>om:featureOfInterest/sams:SF_SpatialSamplingFeature/sams:shape</fes:ValueReference>
         <gml:Envelope srsName="http://www.opengis.net/def/crs/EPSG/0/4326">
            <gml:lowerCorner>0 0</gml:lowerCorner>
            <gml:upperCorner>60 60</gml:upperCorner>
         </gml:Envelope>
      </fes:BBOX>
   </sos:spatialFilter>
   <!-- optional definition of the response format; here O&amp;M 2.0 -->
   <sos:responseFormat>http://www.opengis.net/om/2.0</sos:responseFormat>
</sos:GetObservation>

As a result, the SOS responds with a GetObservationResponse document comprising zero or multiple observationData entries, each storing an instance of an observation (e.g. an O&M document, if the associated response format was requested). The following listing provides an excerpt from the response to the previously presented request.

<?xml version="1.0" encoding="UTF-8"?>
<sos:GetObservationResponse xmlns:sos="http://www.opengis.net/sos/2.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/om/2.0 http://schemas.opengis.net/om/2.0/observation.xsd http://www.opengis.net/sos/2.0 http://schemas.opengis.net/sos/2.0/sos.xsd">
   <!-- exemplar entry -->
   <sos:observationData>
      <!-- observation with uniwue identifier -->
      <om:OM_Observation xmlns:om="http://www.opengis.net/om/2.0" xmlns:gml="http://www.opengis.net/gml/3.2" gml:id="o_129567565">
         <!-- observation type; here Measurement -->
         <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement" />
         <!-- period in time for which the mesaurment applies -->
         <om:phenomenonTime>
            <gml:TimePeriod gml:id="phenomenonTime_129567565">
               <gml:beginPosition>2014-11-19T13:39:00.000Z</gml:beginPosition>
               <gml:endPosition>2014-11-19T13:40:00.000Z</gml:endPosition>
            </gml:TimePeriod>
         </om:phenomenonTime>
         <!-- point in time when the measurement was observed -->
         <om:resultTime>
            <gml:TimeInstant gml:id="ti_9FC93B1C00320A5DC5A324BE1DBF4C6754E7F746">
               <gml:timePosition>2014-11-19T13:40:00.000Z</gml:timePosition>
            </gml:TimeInstant>
         </om:resultTime>
         <!-- reference to sensor/procedure using its identifier -->
         <om:procedure xlink:href="ENTPE-BH-KZ-CH1-QCfull" />
         <!-- reference to phenomena using its identifier -->
         <om:observedProperty xlink:href="Direct Horizontal Irradiance" />
         <!-- reference to featureOfInterest using its identifier -->
         <om:featureOfInterest xlink:href="ENTPE" xlink:title="ENTPE" />
         <!-- result of the observation -->
         <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="W m-2" xsi:type="ns:MeasureType">119.0</om:result>
      </om:OM_Observation>
   </sos:observationData>
   <!-- other entries omitted for brevity -->
</sos:GetObservationResponse>

Operations of Enhanced Extension

The Enhanced Extension of the SOS defines two additional optional operations, as introduced subsequently. For each operation, its task as well as specified request parameters are presented. The operations are:

GetFeatureOfInterest

This operation is used for requesting a set of features that are the target of an observation, encoded in GML. As request parameters, the following can be used:

GetObservationById

This operation is used for requesting a certain observation by its unique identifier. As response, the queried instance of OM_Observation is returned, encoded as O&M.

Operations of Transactional Extension

The Transactional Extension of the SOS defines four additional optional operations, as introduced subsequently. For each operation, its task as well as specified request parameters are presented.

InsertSensor

This operation is used to insert a new sensor into the SOS. The available request parameters are listed below. In response to a successful InsertSensor request, the SOS responds with a pointer to the created sensor instance as well as a pointer to the created offering associated to the inserted sensor/procedure.

UpdateSensorDescription

This operation is used for updating the description of an existing sensor. The available request parameters are listed in the following. In response to a successful UpdateSensorDescription request, the SOS responds with a pointer to the created sensor instance as well as a pointer to the created offering associated to the inserted sensor/procedure:

DeleteSensor

This operation is used to delete an existing sensor from the SOS. The available request parameters are listed below. In response, the SOS provides a pointer to the deleted sensor instance. As a result, the associated observation offerings shall no longer be listed within the SOS capabilities. Each SOS instance may individually decide on further impacts of this request, e.g whether the procedure and all of its observations shall be removed completely from the SOS, or whether it is just prohibited to insert new data for that sensor.

InsertObservation

This operation is used to insert new observations for registered sensors to the SOS. The available request parameters are listed in the following. A successful insertion results in an instance of InsertObservationResponse.

Operations of Result Handling Extension

The Result Handling Extension of the SOS defines four additional optional operations, as introduced subsequently. For each operation, its task as well as specified request parameters are presented. The operations are:

InsertResultTemplate

This operation is used for inserting a result template into a SOS server that describes the structure of the values of subsequently executed InsertResult of GetResult requests. In addition it contains a complete observation template comprising observation metadata such as procedure, observed property and feature of interest related to the results. The available request parameters are listed below. In response, the SOS provides a pointer to the inserted result template instance.

InsertResult

This operation is used for uploading raw results values accordingly to the structure and encoding defined in the InsertResultTemplate request. This is useful, if the remaining metadata elements of an observation are equal (according to the specified observationTemplate within the InsertResultTemplate request). The available request parameters are listed in in the following. A successful insertion results in an instance of InsertResultResponse.

GetResultTemplate

This operation is used for getting the result structure and encoding for specific parameter constellations. In particular this is a necessary preliminary step to correctly interpret retrieved raw result values from a subsequent GetResult request. The available request parameters are listed below. In response, the SOS provides the structure and encoding of the queried result template within the parameters resultStructure and resultEncoding of the associated GetResultTemplateResponse.

GetResult

This operation is used for retrieving raw result data for specific parameter constellations. In contrast to a GetObservation response, the returned document only contains the raw result without the remaining observation metadata components. Similar to the GetObservation operation, several filters can be submitted using request parameters listed in the following table.

Sensor Planning Service

The OGC Sensor Planning Service (SPS) is a Web service to acquire information about the capabilities of sensors and how to task them through specified operations. Remarkably, the SPS does not allow retrieval of observations, as this is done by a SOS. Instead it may be used to dynamically change the parametrization of sensors to adjust them to a new observation scenario. The standardized specification is available at

http://www.opengeospatial.org/standards/sps

Similar to the presentation of the SOS, the section introduces each specified operation of an SPS version 2.0 by listing the operations purpose and request parameters. All information has been extracted from the official SPS 2.0 standard (Simonis & Echterhoff, 2016).

In general, the SPS is designed in a generic fashion to support arbitrary types of sensors. As each sensor is different and requires syntactically and/or semantically different input parameters to be tasked, several operations are specified. Typically, a client first has to acquire meta-information about the capabilities and available parameters (including their syntax) to know how to task them. Having gathered these information, so-called tasks can be registered/submitted to the sensor to actually perform the parametrization adjustment. The following core operations are mandatory:

• GetCapabilities - metadata about service and sensor

• DescribeTasking - metadata about sensor parameter structure for subsequent task creations

• Submit - create and execute a new task by specifying relevant sensor parameters

• GetStatus - get status of a certain task

• GetTask - get status of a certain task (currently more or less equal to GetStatus)

• DescribeResultAccess - acquire information on how/where to retrieve result data (e.g. observation data from an associated SOS)

In addition, the following optional operations can be offered by an SPS:

• DescribeSensor - metadata about the sensor, similar to SOS operation

• Reserve - create a new task, but do not execute it immeadiately

• Confirm - execute a reserved task

• GetFeasibility - create and execute a new task or get alternative parameter constellations to improve the request

• Update - update a non-finished task

• Cancel - cancel/abort a scheduled (reserved/executing) task

• UpdateSensorDescription - update the description of the sensor, similar to SOS operation

GetCapabilities

The GetCapabilites operation returns general metadata about the SPS, such as service identification and provider information. Specific to an SPS, additional information about the procedure, the observed property and observed area as well as supported encodings of tasking parameters and a minimum status time, for which the SPS stores the state of a finalized task, are of high relevance. A GetCapabilities request may include the following parameters:

DescribeTasking

The DescribeTasking operation can be used to retrieve the description of data structures for tasking parameters for subsequent tasking requests. Using the returned tasking parameter description as a basis, clients know how to formulate/encode associated parameters within Submit requests. The following request parameters are offered:

Submit

Via the Submit operation, clients may reparametrize the sensor/procedure according to the parameter structure, as retrieved from a DescribeTasking request. As Submit request may contain invalid parameter constellations, the SPS instance first performs a feasibility check before executing the task. The available request parameters are:

In response, the service provides a so-called status report, providing information on the request as well as task status and other meta-information. Moreover, the response also contains a reference to a created task. The following figure shows all properties of a status report. In particular, a request may have the status Accepted, Pending or Rejected. E.g. it might be rejected for a non-valid parameter definition. If the SPS is busy with the execution of another task or is performing a feasibility check, the request status is set to Pending. Should a client receive a Submit response, where the request is still Pending, then subsequent calls of the GetStatus operation should be used in order to retrieve the final result of the request. In general, within the processing of a Submit request, the request and task experience several transition state changes when they are initialized, processed and finished.

GetStatus

As mentioned in the previous section, the GetStatus operation is used to retrieve the latest status report for a certain task. Without definition of the optional since parameter, the operation returns the last available status report for the specified task. The request parameters are:

GetTask

Via the GetTask operation, clients can retrieve information about the specified task. Currently, this operation is very similar to GetStatus, but is intended to be an extension point for future developments. The response contains the requested task including its last available status report. The request parameters are:

DescribeResultAccess

Via this operation, clients are enabled to acquire information on where to retrieve data that was produced by a certain task or where to retrieve sensor observations from a specified sensor in general. The response may contain a link to any information resource, such as simple files on an FTP server or any remote location. Of particular interest is a reference to other OGC services like an SOS or a Web Feature Service.

Within the request, clients may submit either a procedure or task identifier. While the former is a generic query to find out, how all measured data from that particular sensor is accessible (e.g. resulting in the base URL of a SOS), the latter intends to acquire only the measurements associated with the task (e.g. resulting in a fully parametrized SOS GetObservation request). In addition to this reference location, further metadata about the type of reference (e.g. title, role, format). The following table contains the request parameters:

DescribeSensor

Similar to the equivalently named SOS request (see above), the operation may be used to get a Sensor description, preferably encoded in SensorML.

Reserve

Basically, this operation causes the same effect as a Submit request. A client encodes a certain parameter constellation using the valid structure from a DescribeTasking response and the SPS creates a new task (and performs feasibility checks). However, in contrast to the Submit operation, the task is only created and not executed immediately. Instead the task is just reserved and addressable via its identifier. To execute the task, a client has to send a subsequent Confirm request, as explained in below. Similarly, a reserved task can also be canceled via the Cancel operation, as described below. In consequence, the request parameters equal those of the Submit operation. The response of the SPS again contains a status report providing task metadata (where the state of the task is set to Reserved).

Confirm

Via the Confirm operation, clients are enabled to start a reserved task, which has not expired yet. Implicitly, this changes the tasks state from Reserved to InExecution. Within the response, the modified status report is attached. The available request parameters are:

GetFeasibility

The GetFeasibility operation is meant to check the feasibility of a certain parameter constellation. Clients may execute this operation previously to a Submit operation, in order to verify their request. If the parameter constellation is feasible, then a new task is created, similar to the Submit operation. The response contains a status report with metadata about the task. In addition the response might offer dedicated feasible alternatives, where each alternative suggests a similar parameter constellation to obtain similar results. This might be of high relevance to optimize requests. Of course, these alternatives are only feasible at the time, when they were created. Due to future changes, the feasibility might be lost. The subsequent table lists the available request parameters:

7.2.11 Update

This operation enables clients to update an already created task, which has not yet finalized. The response contains a status report representing the metadata of the modified task as well as the identifier of that task. In case, the request is rejected (e.g. if an unmodifiable property was tried to be modified), then the response will contains the “old” unmodified status report.

Cancel

The Cancel operation is meant to cancel a scheduled task. A task is scheduled, when its state is Reserved or InExecution. If the request fails, the task remains untouched and a proper reason shall be part of the response document. The request parameters are:

UpdateSensorDescription

This operation is equal to the equivalent of the SOS (see above) and is meant to update an existing sensor description of a certain sensor/procedure. Again it is recommended to use SensorML as description format. The request parameters are: