Forgot your password?
New user?
OGC® Ocean Science IE Report has been submitted to OGC
Ocean Innovation 2008 – “World Summit – Ocean Observing Systems”
Document Actions
Best Practices SOS HTTP GET Request
Recommendations and discussions of best practices for using HHTP Get request for a Sensor Observation Service (SOS)
Introduction
The discussion page of this topic could be found here.
HTTP request could be of various types: GET, POST, PUT etc., as explain in the RFC 2616. GET uses the HTTP URL to pass parameters to the server in the URL (e.g. http://marinemetadata.org:9600/oostethys/sos?VERSION=1.0.0&SERVICE=SOS&REQUEST=GetCapabilities). POST, sends a document to the server, allowing for example to post a message to board list or to provide a block of XML data, among others. GET is easier to use, POST is more robust and extensible; however, the OGC Sensor Observation Service (SOS) specification does not explicitly promotes a GET request. At OOSTethys we found that the GET request is very popular in the oceanographic community, because it is very useful, easier to implement and easier to query.
This document explains the GET request operations supported by OOSTethys Sensor Observation Service cookbooks. The information presented here was extracted from OGC specifications and minor comments were added. If not noted, this document complies with the OGC Web Services Common Specification 1.1.0 (OGC 06-121r3) and the Sensor Observation Service Specification 1.0 (OGC 06-009r6).If there are discrepancies between the specification and the schema, the schema is preferred. Schemas are available in the OGC schema repository.
The document first presents the general structure of a GET request, notes about how to handle special characters and capitalization rules. Then, the document presents the GET request details for each of the Sensor Observation Service (SOS) supported by OOSTethys, which correspond to the three mandatory operations in a Sensor Observation Service (SOS):
- GetCapabilities: returns general metadata about the service, operations supported and list of observation offerings.
- DescribeSensor: returns metadata about a sensor system. It could be an observing system, platform or a simple device, such as a bin. The return is given as a SensorML or TML document
- GetObservation: returns a collection of observations. each observation is composed of metadata, description of the phenomena being returned (parameter names, units of measure, reference systems) and values.
Structure of the GET request
The structure of the operation is specified in Table 34 (Whiteside, 2007).
| URL component | Description |
| http://host[:port]/path[?{name[=value]&}] | URL prefix of service operation. [ ] denotes 0 or 1 occurrence of an optional part; {} denotes 0 or more occurrences. |
| name=value& | One or more standard request parameter name/value pairs as defined for each operation by this International Standard. This parameter encoding is referred to as Keyword Value Pair (KVP) encoding in this document. |
Reserved characters
| Character | _Reserved usage |
| ? | Separator indicating start of query string or the KVPs. |
| & | Separator between the parameter (name/value) pairs in query string. |
| = | Separator between name and value of parameter. |
| , | Separator between individual values given for a parameter. |
Capitalization of KVP
- Parameter names are case insensitive. Example for parameter name “request”: REQUEST, request, Request, or ReQuEsT.
- Parameter values are case sensitive and string values are UpperCamelCase. Example for parameter values: GetObservation, DescribeSensor
Escaping special characters
IETF 2396 , section 2.4.1 explains that special characters should be escaped as follows: percent character "%" followed by the two hexadecimal digits. An online application that helps to convert special characters to escaped characters could be found here.
| Special character | Escaped encoding |
| : | %3A |
| / | %2F |
| # | %23 |
| ? | %3F |
| = | %3D |
GetCapabilities Get Request
The parameters rules for the getCapabilities operation are taken from table 3 and table 5 of OGC 06-121r3
Example: http://host[:port]/path?request=GetCapabilities&version=1.0.0&service=sos
| Parameter Name | Definition | Data type and Values | Multiplicity and Use of the Parameter |
| request | Operation name | GetCapabilities | One (mandatory) |
| service | Service type identifier | SOS | One (mandatory) |
| AcceptFormats | Comma-separated prioritized sequence of zero or more response formats desired by client, with preferred formats listed first | text/xml | One (mandatory). When omitted or not supported by server, return service metadata document using MIME type "text/xml" . |
| AcceptVersions | Prioritized sequence of one more specification versions accepted by client, with preferred versions listed first | 1.0.0 has format X.Y.Z |
Zero or more (optional). |
DescribeSensor Request
The attributes of the DescribeSensor request are detailed in the Table 3 of the Sensor Observation Service specification 1.0 (OGC 06-009r6)
The sensorId parameter specifies the sensor for which the description is to be returned. This value must match the value advertised in the xlink:href attribute of a procedure element advertised in the SOS GetCapabilities response. anyURI One (mandatory)| Parameter Name | Definition | Data type and Values | Multiplicity and Use of the Parameter |
| request | Operation name | describeSensor | One (mandatory) |
| procedure | Is the process or sensor system, for which the description is to be returned. It could be an observing system, platform or a simple device, such as a bin. This value must match the value advertised in the xlink:href attribute of a procedure element advertised in the SOS GetCapabilities response. In the specification it is referred as SensorID (Table 3) | anyURI | One (mandatory) |
| service | Service type identifier | SOS | One (mandatory) |
| version | Specification version of the SOS accepted by client | 1.0.0 has format X.Y.Z |
One (mandatory) |
| outputFormat | Specifies the desire output format. | text/xml;subtype=sensorML/1.0.1 | One (mandatory) |
GetObservation Request
The attributes of the GetObservation request are detailed in the Table 4 of the Sensor Observation Service specification 1.0 (OGC 06-009r6) .
| Parameter Name | Definition | Data type and Values | Multiplicity and Use of the Parameter |
| offering | Specifies the offering URI advertised in the GetCapabilities document. This must match the gml:name of the offering. This could also be constructed as a URL with a fragment identifier resolving to the offering gml:id.{ need to revise what this means }. The eventTime and observedProperties are dependent on the selected offering. | anyURI | One (mandatory) |
| observedProperty | Comma-separated URIs, specifying the phenomenon for which observations are requested. { it should not be mandatory. If not presented then all the properties in the observationOffering should be given } | anyURI | One (mandatory) |
| srsName | Defines the spatial reference system that should be used for any geometries that are returned in the response. This must be one of the advertised values in the offering specified in gml:srsName elements. | urn:ogc:def:crs:EPSG:6.5:4326. | One (optional). When omitted or not supported it is assume that the SRS is WGS 84 identified as urn:ogc:def:crs:EPSG:6.5:4326, which is a 2 D reference system and longitude and latitude are given in decimal degrees. |
| eventTime | Specifies the time period(s) for which observations are requested. This allows a client to request observations from a specific instant, multiple instances or periods of time in the past, present and future. The supported range is listed in the selected offering capabilities. | Time should conform to ISO format: YYYY-MM-DDTHH:mm:ssZ. Instance and Periods are supported. Instance is given as one time value. Periods of time (start and end) are separate by “/”. For example: 2008-04-10T10:00:00Z/2008-04-12T11:00:00Z.
|
One (optional). When omitted then the latest observation is returned. |
| BBOX | This is not define in the SOS spec. OOSTethys is using a recommended approach in : section 10.2.3 of OGC 06-121r3 | minlon,minlat,maxlon,maxlat,srsURI?. First 4 all in decimal degrees. srsURI is optional and could take a value of = “urn:ogc:def:crs:EPSG:6.5:4326”. | One (optional). |
| procedure | System for which the observations are requested | anyURI | Zero or Many (optional). |
| featureOfInterest | Not used at the moment. Added here as a place holder | Not applicable | Not applicable |
References
- Whiteside, A., Ed. 2007, OGC Web Services Common Specification, Open Geospatial Consortium Inc. , OGC 06-121r3 [pdf]
-
Na, A. and Priest, M., Eds, 2007, Sensor Observation Service, Open Geospatial Consortium Inc. , OGC 06-009r6. [pdf]
Revision History
| Date | Editor | Primary Sections modified | Description |
| 2008-06-17 | Luis Bermudez | Initial Draft | |
| 2008-06-27 | Luis Bermudez | GetObservation Request | Added procedure and feutureOfInterest parameters. |