Main menu

Welcome to the API of the Open Sensor Network Platform. In order to use the API you need to obtain a valid API-KEY registering into the platform.The OSN API is based on REST-WS technology. The platform produces responses in GeoJSON (JSON), KML (XML) and Layar(JSON) formats.

API limits

OSN API allows up to 10000 uploads and 10000 queries per day. This means 3 uploads/queries per minute. If these limits do not fit your requirements, please do not hesitate to put in contact with us.

Description

Upload a geoJSON file using the API.

HTTP POST Request

http://opencities.upf.edu/osn2/api/datasets/uploadGeoJson/{apiKey}/{datasetId}

Using curl:

curl -X POST -d @geoJsonFile http://opencities.upf.edu/osn2/api/datasets/uploadGeoJson/{apiKey}/{datasetId} --header "Content-Type:application/json"


Parameters
  • apiKey is the key obtained after you register into the platform.
  • datasetId is the identifier of the dataset that you want to inspect.
  • range is the depth of the query. If range is equal to 1, it will reponse only one result from each source of the dataset.

GeoJson allowed shapes:

OSN only accepts geoJson files based on the FeatureCollection object. The FeatureCollection object can only nest the following geometry shapes:

  • Point
  • LineString
  • Polygon

GeoJson required fields:

OSN only accepts geoJson files based on a custom modification of the GeoJson specification. This means that the geoJson files MUST provide some required/optional fields:

  • type is required
  • name is optional but recommended
  • timeStamp is optional
  • feaures.type is required
  • features.tags dictionary is optional but recommended
  • features.geometry.type is required
  • features.geometry.coordinates is required
  • features.properties.id is required
  • features.properties.name is required
  • features.properties.datasetId is required and must match with the dataset Id
  • features.properties.datasetName is required and must match with the dataset name
  • features.properties.address is required
  • features.properties.description is required
  • features.properties.timeStamp is optional. If it is not provided, the platform autogenerates one. Accepted formats: "2013-07-16T07:30:15Z" or "2013-07-16"
  • features.properties.value is required
  • features.properties.unit is optional but recommended
  • features.properties.contentType is required for Layar. It is required for visualizing media
  • features.properties.url is required for Layar. It is required for visualizing media
  • features.properties.previewImage is required for Layar. It is required for visualizing media
  • features.properties.size is required for Layar. Numeric format
  • features.properties.extra is optional for adding extra information. The key field can be any not reserved field. E.g. "author":"Barcelona City Council","license":"gnu"

GeoJSON example file

GeoJSON file with two geometry points:

{
    "type": "FeatureCollection",
    "name": "Weather Dataset1",
    "timeStamp":"2013-07-16T07:30:15Z",
    "features": [
     	{
            "type": "Feature",
    	    "tags": ["colours", "tall", "night", "agbar"],
            "geometry": {
                "type": "Point",
                "coordinates": [2.18946,41.403809]
            },
            "properties": {
            	"id" : "1",
                "name": "SENSOR-HUM-BCN-AGBAR",
                "datasetId": "Weather Dataset1",
                "datasetName": "Weather Dataset1",
                "address": "Torre Agbar, Av. Diagonal, Barcelona",
                "description": "Humidity sensor of Torre Agbar",
                "timeStamp":"2013-07-16T07:30:15Z",
                "value": "80.5",
                "unit":"%",
                "contentType":"video/ogg",
                "url":"http://v2v.cc/~j/theora_testsuite/320x240.ogg",
                "previewImage":"http://www.barcelonacitytour.cat/public/media/image/fotos_grandes/torre_agbar_2.jpg",
                "size":4,
                "extra0":"value",
                "extra1":"value",
                "extraX":"value"
     	},
     	{
            "type": "Feature",
            "tags": ["red", "tall", "cheap"],
            "geometry": {
	        	"type": "Point",
				"coordinates": [2.167028, 41.387547]
            },
            "properties": {
            	"id" : "2",
            	"name": "SENSOR-TEMP-BCN-PZCATALUNYA",
            	"datasetId": "Weather Dataset1",
            	"datasetName": "Weather Dataset1",
            	"address": "PZ. CATALUNYA, Barcelona",
            	"description": "Temperature sensor of Pz. Catalunya",
            	"timeStamp":"2013-07-16T07:30:15Z",
            	"value": "25.1",
            	"unit":"�C",
            	"contentType":"video/ogg",
            	"url":"http://download.blender.org/peach/trailer/trailer_1080p.ogg",
            	"previewImage":"http://peach.blender.org/wp-content/uploads/poster_rodents_small.jpg",
            	"size":4	
            }
     	}
    ]     	
}				
					

Description

You can obtain all the information of a selected dataset. It returns information of each source/sensor.

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getDatasetJson/{apiKey}/{datasetId}/{range}
http://opencities.upf.edu/osn2/api/datasets/getDatasetJsonp/{apiKey}/{datasetId}/{range}?callback
http://opencities.upf.edu/osn2/api/datasets/getDatasetKml/{apiKey}/{datasetId}/{range}

Parameters

  • apiKey is the key obtained after you register into the platform.
  • datasetId is the identifier of the dataset that you want to inspect.
  • range is the depth of the query. If range is equal to 1, it will reponse only one result from each source of the dataset.

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P
  • HTTP-200 OK KML

Description

You can obtain the information of a selected source/sensor in a dataset. This method is useful when you just want information of only one sensor (e.g. I want the data of temperature sensor with ID "2" of a dataset identified as "WeatherStation12345" ).

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getDatasetBySourceIdJson/{apiKey}/{datasetId}/{sourceId}/{range}
 
http://opencities.upf.edu/osn2/api/datasets/getDatasetBySourceIdJsonp/{apiKey}/{datasetId}/{sourceId}/{range}?callback
http://opendata.nets.upf.edu/osn2/api/datasets/getDatasetBySourceIdKml/{apiKey}/{datasetId}/{sourceId}/{range}

Parameters

  • apiKey is the key obtained after you register into the platform.
  • datasetId is the identifier of the dataset that you want to inspect.
  • sourceId is the identifier of the source/sensor that you want to inspect.
  • range is the depth of the query. If range is equal to 1, it will reponse only one result from each source of the dataset.

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P
  • HTTP-200 OK KML

Description

You can obtain the information of a selected source/sensor in a dataset between two given dates.

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getDatasetBySourceIdBetweenDatesJson/{apiKey}/{datasetId}/{sourceId}/{range}/{startDate}/{endDate}
http://opencities.upf.edu/osn2/api/datasets/getDatasetBySourceIdBetweenDatesJsonp/{apiKey}/{datasetId}/{sourceId}/{range}/{startDate}/{endDate}?callback
http://opencities.upf.edu/osn2/api/datasets/getDatasetBySourceIdBetweenDatesKml/{apiKey}/{datasetId}/{sourceId}/{range}/{startDate}/{endDate}

Parameters

  • apiKey is the key obtained after you register into the platform.
  • datasetId is the identifier of the dataset that you want to inspect.
  • sourceId is the identifier of the source/sensor that you want to inspect.
  • range is the depth of the query. If range is equal to 1, it will reponse only one result from each source of the dataset.
  • startDate is the initial date. Accepted format: "2013-05-27"
  • endDate is the final date. Accepted format: "2013-11-21"

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P
  • HTTP-200 OK KML

Description

You can obtain the information about nearby datasets.

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getDatasetNearJson/{apiKey}/{longitude}/{latitude}/{radius}
http://opencities.upf.edu/osn2/api/datasets/getDatasetNearJsonp/{apiKey}/{longitude}/{latitude}/{radius}?callback
http://opencities.upf.edu/osn2/api/datasets/getDatasetNearKml/{apiKey}/{longitude}/{latitude}/{radius}

Parameters

  • apiKey is the key obtained after you register into the platform.
  • longitude expressed in CRS. E.g. 2.123654
  • latitude expressed in CRS. E.g. 41.121512
  • radius expressed in kilometres. E.g. 0.3, 1.25 or 20

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P
  • HTTP-200 OK KML

Description

You can obtain the information about nearby sensors of a given dataset.

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getDatasetNearJson/{apiKey}/{datasetId}/{longitude}/{latitude}/{radius}
http://opencities.upf.edu/osn2/api/datasets/getDatasetNearJsonp/{apiKey}/{datasetId}/{longitude}/{latitude}/{radius}?callback
http://opencities.upf.edu/osn2/api/datasets/getDatasetNearKml/{apiKey}/{datasetId}/{longitude}/{latitude}/{radius}

Parameters

  • apiKey is the key obtained after you register into the platform.
  • datasetId is the identifier of the dataset that you want to inspect.
  • longitude expressed in CRS. E.g. 2.123654
  • latitude expressed in CRS. E.g. 41.121512
  • radius expressed in kilometres. E.g. 0.3, 1.25 or 20

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P
  • HTTP-200 OK KML

Description

You can obtain the information about nearby datasets with advanced filters such as tags, min and max values and unit.

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getDatasetsAdvancedJson/{apiKey}/{longitude}/{latitude}/{radius}/{tags}/{minValue}/{maxValue}/{unit}
http://opencities.upf.edu/osn2/api/datasets/getDatasetsAdvancedJsonp/{apiKey}/{longitude}/{latitude}/{radius}/{tags}/{minValue}/{maxValue}/{unit}?callback
http://opencities.upf.edu/osn2/api/datasets/getDatasetsAdvancedKml/{apiKey}/{longitude}/{latitude}/{radius}/{tags}/{minValue}/{maxValue}/{unit}

Parameters

  • apiKey is the key obtained after you register into the platform.
  • longitude expressed in CRS. E.g. 2.123654
  • latitude expressed in CRS. E.g. 41.121512
  • radius expressed in kilometres. E.g. 0.3, 1.25 or 20
  • tags is an optional list of comma-sepparated keywords. E.g. "temperature,tourism,barcelona"
  • minValue is an optional filter for minimum value
  • maxValue is an optional filter for maximum value
  • unit is an optional filer for unit

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P
  • HTTP-200 OK KML

Description

You can obtain the information about nearby sources/sensors of a given dataset with advanced filters such as tags, min and max values and unit.

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getDatasetAdvancedJson/{apiKey}/{datasetId}/{longitude}/{latitude}/{radius}/{tags}/{minValue}/{maxValue}/{unit}
http://opencities.upf.edu/osn2/api/datasets/getDatasetsAdvancedJsonp/{apiKey}/{longitude}/{latitude}/{radius}/{tags}/{minValue}/{maxValue}/{unit}?callback
http://opencities.upf.edu/osn2/api/datasets/getDatasetsAdvancedKml/{apiKey}/{longitude}/{latitude}/{radius}/{tags}/{minValue}/{maxValue}/{unit}

Parameters

  • apiKey is the key obtained after you register into the platform.
  • datasetId is the identifier of the dataset that you want to inspect.
  • longitude expressed in CRS. E.g. 2.123654
  • latitude expressed in CRS. E.g. 41.121512
  • radius expressed in kilometres. E.g. 0.3, 1.25 or 20
  • tags is an optional list of comma-sepparated keywords. E.g. "temperature,tourism,barcelona"
  • minValue is an optional filter for minimum value
  • maxValue is an optional filter for maximum value
  • unit is an optional filer for unit

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P
  • HTTP-200 OK KML

Description

You can obtain information about a selected layer for Layar. You need to register in Layar to obtain an userId and you are required to create a layer. Please visit Layar site to configure the API endpoint.

HTTP GET Request

http://opencities.upf.edu/osn2/api/datasets/getLayarPOIs/{apiKey}?userId={userId}&countryCode={countryCode}&layerName={datasetId}&lon={longitude}&lat={latitude}&radius={radius}
http://opencities.upf.edu/osn2/api/datasets/getLayarPOIsJsonp/{apiKey}?userId={userId}&countryCode={countryCode}&layerName={datasetId}&lon={longitude}&lat={latitude}&radius={radius}?callback

Parameters

The request call is done using "key=value" URL parameters.

  • apiKey is the key obtained after you register into the platform.
  • userId is the user identifier obtained after you register into Layar
  • countryCode is the country code. E.g. "ES" for Spain, "UK" for United Kingdom, "NL" for Netherlands...
  • datasetId is the identifier of the dataset that you want to inspect
  • longitude expressed in CRS. E.g. 2.123654
  • latitude expressed in CRS. E.g. 41.121512
  • radius expressed in metres. E.g. 300, 125 or 2000

Response

  • HTTP-200 OK JSON
  • HTTP-200 OK JSON-P