-
Notifications
You must be signed in to change notification settings - Fork 44
GSN API v3
You will need Sbt ([http://www.scala-sbt.org/]) to run the service. To run the service from the source code follow the following steps:
1 Go to the gsn-tools folder
2 Run sbt
> sbt
3 In the sbt console switch to the gsnweb project:
> project gsnweb
4 Start the play service, indicate the port:
> start 22002
The following call will return metadata of all sensors in the GSN instance:
http://localhost:22002/ws/api/sensors
The return format is Json (GeoJSON) by default. Each virtual sensor is represented by a Feature object.
{"type":"FeatureCollection","features":[
{"type":"Feature",
"properties":{
"vs_name":"WANNENGRAT_WAN7",
"values":[],
"fields":[
{"name":"relative_humidity","type":"double","unit":"%"},
{"name":"air_temperature","type":"double","unit":"°C"},],
"stats":{"start-datetime":1166623200000,"end-datetime":1442896200000},
"gps_precision":"10","geographical":"Davos, Switzerland.","slope":"0"},
"geometry":{"type":"Point","coordinates":[9.788119,46.807626,2399.0]},
}
]}
The latest sensed values can be obtained by adding the latestValues=true. The values are in the values property as an Array.
The format can be specified using the ``formatparameter. Supported formats include:json` `csv` `xml`
For example the `http://localhost:22002/ws/api/sensors?latestValues=true&format=csv` can throw an output similar to this:
#vs_name,description,latitude,longitude,altitude,accessProtected,fields,units,types,values
WANNENGRAT_WAN7,"Sensor description","46.807626","9.788119","2399","false","relative_humidity|air_temperature","%|°C","double|double",84.6|2.061
The same behavior is obtained for only one sensor, by adding the name of the virtual sensor to the URL:
http://montblanc.slf.ch:22002/ws/api/sensors/wannengrat_wan7?latestValues=true&format=json
For the JSON output, the result is a single Feature, not a FeatureCollection.
To obtain observed data form a virtual sensor, add the /data suffix to the url, e.g.:
http://localhost:22002/ws/api/sensors/wannengrat_wan7/data?size=3
The size parameter indicates the number of rows. The JSON format includes the metadata information as before. The data values are contained in the values property, e.g.:
"values":[[1442896200000,84.6,2.061],[1442895600000,83.6,2.131],[1442895000000,82.1,2.407]]
Each sub-array is a record, and the first field is the timestamp. The order of the fields follows the order of the fields listed in the metadata.
The timestamp is formatted using the timeFormat parameter. Pre-defined formats are:
-
timeFormat=iso8601: e.g. 2015-09-22T04:10:00Z -
timeFormat=iso8601ms: e.g. 2015-09-22T04:10:00.000Z -
timeFormat=unixTime: e.g. 1442895000000 Other formats are possible following the JDK data time format strings, e.g.timeFormat=YYYYMMDD
By default data for all fields are included in the output. They can be filtered out with the ``fieldsparameter. E.g.fields=temperature,humidity` will only include the temperature and humidity fields.
Filtering with a starting and end dates:
from=2010-10-01&to=2010-10-03
Date times can be specified:
from=2010-10-01T10:00:00&to=2010-10-01T11:00:00
Filtering by value is possible by adding conditions in the filter parameter. Eg:
filter=relative_humidity>99.7
Obtain data from a given period every year. e.g. from 1st to 2nd May every year:
period=05-01/05-02
The aggregation functions available are avg sum min max. The aggregation period is the time window on which the aggregation is computed. Each aggregated record is accompanied by the timestamp of the starting timestamp of the aggregation period. The aggregation period follows the ISO 8601 for periods. For instance:
http://localhost:22002/ws/api/sensors/wannengrat_wan7/data?agg=max&aggPeriod=P20D&fields=relative_humidity&timeFormat=iso8601
Other example periods: 1 hour: PT1H, 20 minutes: ``PT20M`
For public sensors the data is freely available. For private ones, it requires an api key:
apikey=YOUR_KEY_HERE