Version: 1.0

Date: 2011-11-17

Editor: Arne Brφring, 52°North

 

 

REST API of the ArcGIS Server SOS Extension

This document presents a service model for providing spatio-temporal observations, in particular in form of near real time sensor data, with an extension for ArcGIS Server, the Sensor Observation Service (SOS) extension for ArcGIS Server. This ArcGIS SOS Extension is aligned with the OGC specification “Sensor Observation Service” (SOS). The ArcGIS SOS conforms to the abstract service model defined in the OGC SOS 2.0 standard, but provides a new implementation of this standard aligned with the ESRI Geoservices REST API.

The next sections describe the REST API of the ArcGIS SOS Extension, and how the associated resources can be accessed and filtered.

1.   SOS Service

URL   http://<mapservice-url>/exts/SosSOE

Parent Resource   Map Service

Child Resources   Observations, Procedures, Features

 

Description

This ArcGIS Server extension of a Sensor Observation Service (SOS) is designed to support the provision of near real time sensor observations. The service interface follows the design principles of ESRI’s ArcGIS Server REST API. It allows querying of observations, metadata of procedures (= sensors), as well as descriptions of features observed by the sensors.

These data sets are made available as resources via a REST API. Either all available resource instances can be queried by appending the according URL segment, or the resources can be filtered with query operations.

 

The REST API of the ArcGIS Server SOS works only as an extension of a Map Server which is based upon the Geodatabase observation model as described here.

This SOS resource provides basic information about the data set the service is based upon. The information content is aligned with the contents of an OGC Capabilities document of the SOS standard. This information includes the contact details to the service provider, keywords, intended applications, the associated sensors (= procedures), observed properties, time periods for which data is available, as well as the overall observed area.

 

SOS services do not expose editing capabilities. They provide read-only access to observations, sensors (or more specifically procedures) and features.

 

The SOS service resource supports query operations on the resources observations, and features. Those Query operations return subsets of the according resources based on user defined criteria.

 

Resource Hierarchy

 

Parameters

Parameter 

Details

f

Description: Specifies the desired response format. The default is html.

 

Optionality: optional

 

Values: html | json

 

 

[The schema of the SOS is returned as a JSON formatted string by specifying the query parameter f=schema on the root resource.]

 

 

JSON Response Syntax

{

"title" : "<title of the SOS service>",

"description" : "<abstract description>",

"keywords" : "["<keyword 1>", “<keyword 2>", ..., "<keyword n>"]",

"providerName": "<service provider name>",

"providerSite" : "<service provider site>",

"serviceContacts" : [ //contact details of the service provider

    {

    "individualName" : “<name of responsible individual>”,

    "positionName" : "<position of responsible individual>",

    "phone" : “<phone number>”,

    "facsimile" : “<fax number>”,

    "deliveryPoint" : “<delivery point (e.g. street & number) of the mailing address>”,

    "city" : “<city of the mailing address>”,

    "administrativeArea" : “<administrative area of the mailing address>”,

    "postalCode" : “<postal code of the mailing address>”,

    "country" : “<country of the mailing address>”,

    "electronicMailAddress" : “<e-mail address>”

    }

],

"procedures" : [

  { "id" : "<identifier of procedure 1>", "name" : "<name of procedure 1>" },

  ...

  { "id" : "<identifier of procedure N>", "name" : "<name of procedure N>" },

]

}

 

JSON Response Example

{

 "title": "AirQualitySOS",

 "description": "Air quality observation across Europe",

 "keywords": [

  "Air quality",

  "CO",

  "O3",

  "Carbon Monoxide",

  "Ozone"

 ],

 "providerName": "52North",

 "providerSite": "http://52north.org",

 "serviceContacts": [

  {

   "individualName": "Arne Broering",

   "positionName": "Project Manager",

   "phone": "+4925139637132",

   "facsimile": "+4925139637111 ",

   "deliveryPoint": "Martin-Luther-King-Weg 24",

   "city": "Muenster",

   "administrativeArea": "NRW",

   "postalCode": "48155",

   "country": "Germany",

   "electronicMailAddress": "broering@52north.org"

  }

 ],

 "procedures": [

  {

   "id": "CO-SensorNetwork",

   "name": "CO Sensor Network in Europe"

  },

  {

   "id": "Ozone-SensorNetwork",

   "name": "Ozone Sensor Network in Europe"

  }

 ]

}

 

JSON Response (if f=schema)

{

"name":"ArcGIS_SOS_Extension",

"description":"An_SOS_extension_for_ArcGIS_Server",

"isCollection":false,

"resources":[

  {

  "name":"observations",

  "description":"description of observations resource",

  "isCollection":false,

  "operations":[

    {

    "name":"query",

    "parameters":[

      "offering",

      "observedProperty",

      "procedure",

      "featureOfInterest",

      "spatialFilter",

      "temporalFilter",

      "where"

    ],

    "supportedOutputFormats":["json"],

    "postOnly":false

    }

  ]

  },

  {

  "name":"procedures",

  "description":"description of procedure resource",

  "isCollection":true

  },

  {

  "name":"features",

  "description":"description of features resource",

  "isCollection":false,

  "operations":[

    {

    "name":"query",

    "parameters":[

      "feature",

      "observedProperty",

      "procedure",

      "spatialFilter"

    ],

    "supportedOutputFormats":["json"],

    "postOnly":false

    }

  ]

  }

]

}

2.   Observations

URL   http://<mapservice-url>/exts/SosSOE/observations

Supported Operations   Query

Parent Resource  SOS Service

 

Description

The observations resource represents all observations under an SOS service published by the ArcGIS Server. It provides information about the available observations. Therefore, it groups the observations in so-called observation offerings.

An observation offering groups collections of observations produced by a certain procedure, usually a sensor system. Thereby, a sensor system can be a simple thermometer, but can also consist of several sub-systems. In that sense, a valid sensor system can be a weather station with attached sensors, or it can be a network of spatially distributed sensors.

The observation offering lists the basic metadata for the associated observations, i.e., the identifier and human-readable name of the offering, the observed properties of the observations, the procedure which produced the observations, the observed area within which the features of interest of the observations are located, as well as the time extent of the observations.

An observation may belong to more than one observation offering, for the purpose of grouping pre-filtered observations. This way functionality is given which allows grouping of observations according to some thematic criteria. An example could be the grouping of severe and all weather forecast observations.

The observations resource supports the Query operation which returns a subset of observations based on query criteria.

 

Resource Hierarchy

REST_specification_resource_observations

 

Parameters

Parameter 

Details

f

Description: Specifies the desired response format for transport of the observations. The default is html.

 

Optionality: optional

 

Values: html | json

 

 

JSON Response Syntax

{

"observationOfferings" : [

  { "observationOffering" : {

      "id" : "<identifier of the offering>",

      "name" : "<human-readable name of the offering>",

      "observedProperties" : [

          "<observed property identifier 1>",

          ...

          "<observed property identifier N>"

      ]

      "procedure" : "<procedure identifier>",

      "observedArea" : <envelope>,         // encoding follows ESRI’s ‘envelope’ encoding

      "timeExtent" : [<startTime>, <endTime>]  // in ISO8601

    }

  },

    ...,

    {

    <observationOffering N>

    }

]

}

 

JSON Response Example

{

 "observationOfferings": [

  {

   "id": "1",

   "name": "CO-Offering",

   "observedProperties": [

    {

     "dataType": "NUMERIC",

     "definition": "http://sweet.jpl.nasa.gov/ontology/substance.owl#CarbonMonoxide"

    }

   ],

   "procedure": "CO-SensorNetwork",

   "observedArea": {

    "xmin": -16.570832999999936,

    "ymin": 28.000000000000057,

    "xmax": 28.054740000000038,

    "ymax": 55.945591000000036,

    "spatialReference": {"wkid": 4326}

   },

   "timeExtent": "2011-09-20T00:00:00+00:00/2011-10-20T00:00:00+00:00"

  },

  {

   "id": "2",

   "name": "Ozone-Offering",

   "observedProperties": [

    {

     "dataType": "NUMERIC",

     "definition": "http://sweet.jpl.nasa.gov/ontology/substance.owl#Ozone"

    }

   ],

   "procedure": "Ozone-SensorNetwork",

   "observedArea": {

    "xmin": -61.59026899999992,

    "ymin": -21.342888999999957,

    "xmax": 55.47419200000007,

    "ymax": 78.90000200000003,

    "spatialReference": {"wkid": 4326}

   },

   "timeExtent": "2011-09-20T00:00:00+00:00/2011-10-20T00:00:00+00:00"

  }

 ]

}

 

2.1. Query (Operation)

URL   http://<mapservice-url>/exts/SosSOE/observations/query

Parent Resource   Observations

 

Description

The query operation is performed on the observations resource of the SOS. The result of this operation is a set of observations. The returned observations contain the attributes of the Geodatabase observation model.

You can provide arguments to the query operation as query parameters defined in the parameters table below. The filter parameters are connected with an explicit AND. The values of each of the parameters are connected with an implicit OR.

 

Parameters

Parameter 

Details

offering

Description: Comma-separated unordered list of one or more ObservationOffering identifiers.

 

Optionality: optional

 

observedProperty

Description: Comma-separated unordered list of one or more observed property identifiers of the requested observations.

 

Optionality: optional

 

procedure

Description: Comma-separated unordered list of one or more procedure identifiers of the requested observations.

 

Optionality: optional

 

featureOfInterest

Description: Comma-separated unordered list of one or more feature of interest identifiers of observations stored by the service.

 

Optionality: optional

 

spatialFilter

Description: A spatial filter which applies to the geometry of the feature of interest of the queried observations. The structure of this filter is the same as the structure of the json geometry objects used by the ArcGIS REST API. In addition to the JSON structures, for envelopes and points, the filtered geometry can be specified with a simpler comma-separated syntax.

 

Optionality: optional

 

Syntax:

·          JSON structure: spatialFilter=<ESRI geometry>

 

Example:

·          BBOX: spatialFilter={xmin:0.0,ymin:40.0,xmax:2.0,ymax:43.0,spatialReference:{wkid:4326}}

·          Point: spatialFilter={x:1.121389,y:41.152222,spatialReference:{wkid:4326}}

temporalFilter

Description: A temporal filter which applies to the TIME_STAMP property of requested observations.

A timeInstant needs to conform to the ISO 8601 format, i.e., ‘yyyy-MM-ddTHH:mm:ss+HH:mm’. The returned observations will be converted to the queried time zone. For example, if a client requests data in the time zone GMT+07:00, the returned observations will be in that time zone, too.

In case of the last filter, which queries all observations measured during the last x milliseconds, the requested time zone must be appended after a ‘,’ in the format of ‘+HH:mm’ (or ‘-HH:mm’ respectively).

 

Optionality: optional

 

Syntax:

·          temporalFilter={equals:<time instant>}

·          temporalFilter={during:<time instant start>,<time instant end>}

·          temporalFilter={after:<time instant>}

·          temporalFilter={before:<time instant>}

·          temporalFilter={last:<time duration>,<time zone offset>}  //time duration in milliseconds

 

Examples:

·          temporalFilter=equals:2011-10-19T15:00:00+02:00

·          temporalFilter=during:2011-10-19T15:00:00+02:00,2011-10-20T00:00:00+02:00

·          temporalFilter=last:2419200000,+02:00  // returns the last 28 days from now and the observation times are given in UTC + 2 hours

where

Description: A where clause for the query filter. Any legal SQL where clause operating on the fields of the observations resource is allowed.

Optionality: optional


Example: where=numeric_value<=35

 

f

Description: Specifies the desired response format for transport of the observations. The default is html.

 

Optionality: optional

 

Values: html | json

 

 

JSON Response Syntax

{

“observationData” : [

  {

    "id" : "<identifier of the observation>"

    "type" : "<type of observation>"

    “phenomenonTime” : ”<time stamp of the observation>”, //in ISO 8601

    “resultTime” : ”<time stamp of the observation result>”, //in ISO 8601, mostly the same as phenomenonTime

    “procedure” : ”<identifier of the procedure>”,

    “observedProperty” : ”<identifier of the observed property>”,

    “featureOfInterest” : ”<identifier of the feature of interest>”,

    “result : {

      “type : ”<numerical | textual>”,    //type of the result; either numeric or textual

      “uom” : ”<unit of measure>”,

      “value” : <numerical value> | “<textual value>”  //either numeric or textual result value

      }

    }

  },

  ...

  <observation N>

]

}

 

JSON Response Example

{

 "observationData": [

  {

   "id": "738235",

   "type": "OM_Measurement",

   "phenomenonTime": "2011-10-19T23:00:00+02:00",

   "resultTime": "2011-10-19T23:00:00+02:00",

   "observedProperty": "http://sweet.jpl.nasa.gov/ontology/substance.owl#Ozone",

   "procedure": "Ozone-SensorNetwork",

   "featureOfInterest": "ES1125A",

   "result": {

    "type": "numerical",

    "uom": "ug/m3",

    "value": 18

   }

  },

  {

   "id": "990899",

   "type": "OM_Measurement",

   "phenomenonTime": "2011-10-20T00:00:00+02:00",

   "resultTime": "2011-10-20T00:00:00+02:00",

   "observedProperty": "http://sweet.jpl.nasa.gov/ontology/substance.owl#Ozone",

   "procedure": "Ozone-SensorNetwork",

   "featureOfInterest": "ES1910A",

   "result": {

    "type": "numerical",

    "uom": "ug/m3",

    "value": 66.5

   }

  },

  {

   "id": "738377",

   "type": "OM_Measurement",

   "phenomenonTime": "2011-10-20T00:00:00+02:00",

   "resultTime": "2011-10-20T00:00:00+02:00",

   "observedProperty": "http://sweet.jpl.nasa.gov/ontology/substance.owl#Ozone",

   "procedure": "Ozone-SensorNetwork",

   "featureOfInterest": "ES1339A",

   "result": {

    "type": "numerical",

    "uom": "ug/m3",

    "value": 49.5

   }

  }

 

3.   Procedures (= Sensors)

URL   http://<mapservice-url>/exts/SosSOE/procedures

Parent Resource  SOS Service

Child Resource  Procedure

 

Description

The procedures resource represents all procedures (e.g., sensor systems) of an SOS service published by the ArcGIS Server. It returns the IDs of all procedures.

 

Resource Hierarchy

 

Parameters

Parameter 

Details

f

Description: The response format. The default response format is html.

 

Optionality: optional

 

Values: html | json

 

JSON Response Syntax

{

"procedures" : [

    <procedure id 1>,

    ...

    <procedure id N>

  ]

}

 

JSON Response Example

{

 "procedures": [

  {"id": "CO-SensorNetwork"},

  {"id": "Ozone-SensorNetwork"}

 ]

}

 

3.1. Procedure

URL   http://<mapservice-url>/exts/SosSOE/procedures/<procedure identifier>

Parent Resource  Procedures

 

Description

The procedure resource represents a single procedure (e.g., a sensor system or sensor network) of an SOS service published by the ArcGIS Server. The last URL segment is the identifier of the procedure for which a metadata description shall be retrieved.

 

Resource Hierarchy

REST_specification_resource_procedure

 

Parameters

Parameter

Details

f

Description: Specifies the desired response format for transport of the procedure. The default is html.

 

Optionality: optional

 

Values: html | json

 

JSON Response Syntax

{

  "id" : “<identifier of the procedure>”,

  "name" : “<human-readable name of the procedure>”,

  "description" : “<human-readable description of the procedure>”,

  “sensorType” : “<type of the procedure>”,

  “intendedApplication” : “<intended application of the procedure>”,

    “contact” : [ //contact details of the procedure provider

        {

        "individualName" : “<name of responsible individual>”,

        "positionName" : "<position of responsible individual>",

        "phone" : “<phone number>”,

        "facsimile" : “<fax number>”,

        "deliveryPoint" : “<delivery point (e.g. street & number) of the mailing address>”,

        "city" : “<city of the mailing address>”,

        "administrativeArea" : “<administrative area of the mailing address>”,

        "postalCode" : “<postal code of the mailing address>”,

        "country" : “<country of the mailing address>”,

        "electronicMailAddress" : “<e-mail address>”

        }

    ],

  "observedArea” : <envelope>,     

  "outputs” : [

    {

      "dataType", "<data type of output 1>",

      "definition": "<semantics definition of of output N>"

    },

    ...

    {

      "dataType": "<data type of output N",

      "definition": "<semantics definition of of output N>"

    }

  ]

}

 

JSON Response Example

{

 "id": "CO-SensorNetwork",

 "name": "CO Sensor Network in Europe",

 "description": "This procedure is a sensor network of air quality stations in Europe measuring Carbon Monoxide.",

 "intendedApplication": "Air quality in Europe",

 "sensorType": "sensor network",

 "observedArea": {

  "xmin": -16.570832999999936,

  "ymin": 28.000000000000057,

  "xmax": 28.054740000000038,

  "ymax": 55.945591000000036,

  "spatialReference": {"wkid": 4326}

 },

 "contact": {

  "individualName": "Arne Broering",

  "positionName": "Project Manager",

  "phone": "+4925139637132",

  "facsimile": "+4925139637111 ",

  "deliveryPoint": "Martin-Luther-King-Weg 24",

  "city": "Muenster",

  "administrativeArea": "NRW",

  "postalCode": "48155",

  "country": "Germany",

  "electronicMailAddress": "broering@52north.org"

 },

 "outputs": [

  {

   "dataType": "NUMERIC",

   "definition": "http://sweet.jpl.nasa.gov/ontology/substance.owl#CarbonMonoxide"

  }

 ]

}

 

4.   Features (of Interest)

URL   http://<mapservice-url>/exts/SosSOE/features

Supported Operations   Query

Parent Resource  SOS Service

 

Description

The features resource represents all features of interest which are associated with the observations hosted by the SOS service and are observed by the procedures. By calling this resource the SOS service returns the IDs of all features of interest. The query operation can be used to retrieve full descriptions of particular features.

 

Resource Hierarchy

REST_specification_resource_features

 

JSON Response Syntax

{

  "features": [

  {"id": "<id feature 1>"},

  ...

  {"id": "<id feature N>"}

  ]

}

 

 

JSON Response Example

{

 "features": [

  {"id": "BETR701"},

  {"id": "DERP023"},

  {"id": "CH0049A"},

  {"id": "PT03085"}

 ]

}

 

4.1. Query (Operation)

URL   http://<mapservice-url>/exts/SosSOE/features/query

Parent Resource  Features

 

Description

The query operation is performed on the features resource of the SOS. The result of this operation is a set of features.

You can provide arguments to the query operation as query parameters defined in the parameters table below. The filter parameters are connected with an explicit AND. The values of each of the parameters are connected with an implicit OR.

 

Parameters

Parameter

Details

observedProperty

 

Description: Comma-separated unordered list of one or more identifiers of observed properties of the requested features of interest.

 

Optionality: optional

 

procedure

Description: Comma-separated unordered list of one or more identifiers of procedures which observe the requested features of interest.

 

Optionality: optional

 

spatialFilter

Description: A spatial filter which applies to the geometry of the requested features of interest. The structure of this filter is the same as the structure of the json geometry objects used by the ArcGIS REST API. In addition to the JSON structures, for envelopes and points, the filtered geometry can be specified with a simpler comma-separated syntax.

 

Optionality: optional

 

Syntax:

·          JSON structure: spatialFilter=<ESRI geometry>

 

Example:

·          BBOX: spatialFilter={xmin:0.0,ymin:40.0,xmax:2.0,ymax:43.0,spatialReference:{wkid:4326}}

·          Point: spatialFilter={x:1.121389,y:41.152222,spatialReference:{wkid:4326}}

 

JSON Response Syntax

{

 "features": [

  {

   "id": "<feature identifier>",

   "codeSpace": "<codeSpace of the feature identifier>",

   "name": "<name of the feature>",

   "description": "<description of the feature>",

   "type": "<type of the feature>",

   "sampledFeature": <link to the sampled feature>,

   "shape": <geometry>,     

  }

  ...

  {

  <feature N>

  }

 ]

}

 

JSON Response Example

{

 "features": [

  {

   "id": "PT03085",

   "codeSpace": "http://eea.europa.eu",

   "name": "Loures",

   "description": "LOURES, AML NORTE, PORTUGAL, http://www.qualar.org/",

   "type": "http://www.opengis.net/def/samplingFeatureType/OGC-OM/2.0/SF_SamplingPoint",

   "sampledFeature": null,

   "shape": {

    "x": -9.165290999999911,

    "y": 38.82888800000006,

    "spatialReference": {

     "wkid": 4326

    }

   }

  }

 ]

}