Developer API Documentation


Resources


The system is composed of five different objects: devices, infrastructures, cities, manufacturers and collections. Being the devicess the basic element, the rest are groups of devices. Infrastructures, cities and manufacturers are defined by the system, while collections defined are by the user.



Devices


The public API only offers look-up methods (GET) to obtain information about a device or a group of them. Devices are created, updated and deleted by the system or by the administrator.

Action

List all devices

Method
GET

Resource
/devices?deviceName={deviceName}
&infrastructureID={infrastructureID}&infrastructureName={infrastructureName}
&manufacturerID={manufacturerID}&manufacturerName={manufacturerName}
&cityID={cityID}&cityName={cityName}
&propertyName={propertyName}

Request parameters
Parameter Description Type Compulsory
deviceName Device name String No
infrastructureID Infrastructure identification number Integer No
infrastructureName Infrastructure name String No
manufacturerID Manufacturer identification number Integer No
manufacturerName Manufacturer name String No
cityID City identification number Integer No
cityName City name String No
propertyName Property name String No

Returns

A full list of all available devices objects in the specified format.

Sample JSON response
[
{
"sensorID":"1",
"platformID":"1",
"latitude":"41.471478",
"longitude":"2.085578",
"offering":"urn:OFF02:192",
"procedure"
:"urn:santcugat:PLTURB0002:SNS01000013b8240512_0",
"name":"SNS01000013b8240512_0",
"city":"Sant Cugat del Valles",
"manufacturer":"Urbiotica",
"properties":["urn:humidity"]
},
{
"sensorID":"2",
"platformID":"2",
"latitude":"0.000000",
"longitude":"0.000000",
"offering":"urn:OFF02:193",
"procedure":"urn:santcugat:PLTWRS00002:SNS1088",
"name":"SNS1088","city
":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
{
"sensorID":"3",
"platformID":"2",
"latitude":"0.000000",
"longitude":"0.000000",
"offering":"urn:OFF02:194",
"procedure":"urn:santcugat:PLTWRS00002:SNS1110",
"name":"SNS1110",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
...
]

Action

List all devices by Proximity (RADIUS)

Method
GET

Resource
/devices?latitude={latitude}&longitude={longitude}&distance={distance} &deviceName={deviceName}
&infrastructureID={infrastructureID}&infrastructureName={infrastructureName}
&manufacturerID={manufacturerID}&manufacturerName={manufacturerName}
&cityID={cityID}&cityName={cityName}
&propertyName={propertyName}

Request parameters
Parameter Description Type Compulsory
longitude Longitude coordinate Float (10,6) Yes
Latitude coordinate Float (10,6) Yes
distance Distance in km Float (10,6) Yes
deviceName Device Name String No
infrastructureID Infrastructure identification number Integer No
infrastructureName Infrastructure Name String No
manufacturerID Manufacturer identification number Interger No
manufacturerName Manufacturer Name String No
cityID City identification number Integer No
cityName City Name String No
propertyName Property Name String No

Returns

A full list of all available devices objects in the specified format.

Sample JSON response
[
{
"sensorID":"1",
"platformID":"1",
"latitude":"41.471478",
"longitude":"2.085578",
"offering":"urn:OFF02:192",
"procedure"
:"urn:santcugat:PLTURB0002:SNS01000013b8240512_0",
"name":"SNS01000013b8240512_0",
"city":"Sant Cugat del Valles",
"manufacturer":"Urbiotica",
"properties":["urn:humidity"]
"distance":"134.34051421072"
"OriginLongitude":"2.125425"
"OriginLatitude":"51.563801"
},
{
"sensorID":"2",
"platformID":"2",
"latitude":"0.000000",
"longitude":"0.000000",
"offering":"urn:OFF02:193",
"procedure":"urn:santcugat:PLTWRS00002:SNS1088",
"name":"SNS1088","city
":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
"distance":"79.2078868697"
"OriginLongitude":"2.125425"
"OriginLatitude":"51.563801"
},
{
"sensorID":"3",
"platformID":"2",
"latitude":"0.000000",
"longitude":"0.000000",
"offering":"urn:OFF02:194",
"procedure":"urn:santcugat:PLTWRS00002:SNS1110",
"name":"SNS1110",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
"distance":"115.426916375"
"OriginLongitude":"2.125425"
"OriginLatitude":"51.563801"
},
...
]

Action

Describe device

Method
GET

Resource
/devices/{id}

Request parameters
Parameter Description Type Compulsory
id Device identification number Integer Yes
Returns

A full description of the device with ID {id}.

Sample JSON response
{
"sensorID":"1",
"platformID":"1",
"latitude":"41.471478",
"longitude":"2.085578",
"offering":"urn:OFF02:192",
"procedure"
:"urn:santcugat:PLTURB0002:SNS01000013b8240512_0",
"name":"SNS01000013b8240512_0",
"city":"Sant Cugat del Valles",
"manufacturer":"Urbiotica",
"properties":["urn:humidity"]
}


Infrastructures

Action

List all infrastructures

Method
GET

Resource
/infrastructures?infrastructureName={infrastructureName}
&manufacturerID={manufacturerID}&manufacturerName={manufacturerName}
&cityID={cityID}&cityName={cityName}
&propertyName={propertyName}

Request parameters
Parameter Description Type Compulsory
infrastructureName Infrastructure name String No
manufacturerID Manufacturer identification number Integer No
manufacturerName Manufacturer name String No
cityID City identification number Integer No
cityName City name String No
propertyName Property name String No

Returns

A full list of all available platform objects in the specified format.

Sample JSON response
[
{
"platformID":"1",
"sos_nickname":"PLTURB0002",
"latitude":"41.472279",
"longitude":"0.000000",
"city":"Sant Cugat del Valles",
"manufacturer":"Urbiotica"
},
{
"platformID":"2",
"sos_nickname":"PLTWRS00002",
"latitude":"900.000000",
"longitude":"2.084822",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing"
},

...
]

Action

Describe infrastructure

Method
GET

Resource
/infrastructures/{id}

Request parameters
Parameter Description Type Compulsory
id Infrastructure identification number Integer Yes
Returns

A full description of the infrastructure with ID {id}.

Sample JSON response
{
"platformID":"1",
"sos_nickname":"PLTURB0002",
"latitude":"41.472279",
"longitude":"0.000000",
"city":"Sant Cugat del Valles",
"manufacturer":"Urbiotica"
}

Action

List all devices from infrastructure

Method
GET

Resource
/infrastructures/{id}/devices

Request parameters
Parameter Description Type Compulsory
id Infrastructure identification number Integer Yes
Returns

A full list of all available devices from a certain infrastructure with ID {id} in the specified format.

Sample JSON response
[
{
"sensorID":"16",
"platformID":"2",
"latitude":"41.471882",
"longitude":"2.085344",
"offering":"urn:OFF02:208",
"procedure":"urn:santcugat:PLTWRS00002:SNS1146",
"name":"SNS1146",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
{
"sensorID":"17",
"platformID":"2",
"latitude":"41.472031",
"longitude":"2.085223",
"offering":"urn:OFF02:209",
"procedure":"urn:santcugat:PLTWRS00002:SNS1177",
"name":"SNS1177",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
...
]


Cities

Action

List all cities

Method
GET

Resource
/cities?cityName={cityName}
&infrastructureID={infrastructureID}&infrastructureName={infrastructureName}
&manufacturerID={manufacturerID}&manufacturerName={manufacturerName}
&propertyName={propertyName}

Request parameters
Parameter Description Type Compulsory
cityName City name String No
infrastructureID Infrastructure identification number Integer No
infrastructureName Infrastructure name String No
manufacturerID Manufacturer identification number Integer No
manufacturerName Manufacturer name String No
propertyName Property name String No

Returns

A full list of all available city objects in the specified format.

Sample JSON response
[
{
"cityID":"1",
"sos_nickname":"abertis",
"name":"Abertis Smart Zone",
"longitude":"2.126110",
"latitude":"41.340618",
"description":""
},
{
"cityID":"2",
"sos_nickname":"santcugat",
"name":"Sant Cugat del Valles",
"longitude":"2.085410",
"latitude":"41.473469",
"description":""
},
...
]

Action

Describe city

Method
GET

Resource
/cities/{id}

Request parameters
Parameter Description Type Compulsory
id City identification number Integer Yes
Returns

A full description of the city with ID {id}.

Sample JSON response
{
"cityID":"1",
"sos_nickname":"abertis",
"name":"Abertis Smart Zone",
"longitude":"2.126110",
"latitude":"41.340618",
"description":""
}

Action

List all devices from city

Method
GET

Resource
/cities/{id}/devices

Request parameters
Parameter Description Type Compulsory
id City identification number Integer Yes
Returns

A full list of all available devices from a certain city with ID {id} in the specified format.

Sample JSON response
[
{
"sensorID":"16",
"platformID":"2",
"latitude":"41.471882",
"longitude":"2.085344",
"offering":"urn:OFF02:208",
"procedure":"urn:santcugat:PLTWRS00002:SNS1146",
"name":"SNS1146",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
{
"sensorID":"17",
"platformID":"2",
"latitude":"41.472031",
"longitude":"2.085223",
"offering":"urn:OFF02:209",
"procedure":"urn:santcugat:PLTWRS00002:SNS1177",
"name":"SNS1177",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
...
]


Manufacturers


Action

List all manufacturers

Method
GET

Resource
/manufacturers?manufacturerName={manufacturerName}
&infrastructureID={infrastructureID}&infrastructureName={infrastructureName}
&cityID={cityID}&cityName={cityName}
&propertyName={propertyName}

Request parameters
Parameter Description Type Compulsory
manufacturerName Manufacturer name String No
infrastructureID Infrastructure identification number Integer No
infrastructureName Infrastructure name String No
cityID City identification number Integer No
cityName City name String No
propertyName Property name String No

Returns

A full list of all available manufacturer objects in the specified format.

Sample JSON response
[
{
manufacturerID":"1",
sos_nickname":"WRS",
name":"Worldsensing",
location":"Barcelona",
website":"http://www.worldsensing.com"
},
{
manufacturerID":"2",
sos_nickname":"URB",
name":"Urbiotica",
location":"Barcelona",
website":"http://www.urbiotica.com"
},
...
]

Action

Describe manufacturer

Method
GET

Resource
/manufacturers/{id}

Request parameters
Parameter Description Type Compulsory
id Manufacturer identification number Integer Yes
Returns

A full description of the manufacturer with ID {id}.

Sample JSON response
{
manufacturerID":"2",
sos_nickname":"URB",
name":"Urbiotica",
location":"Barcelona",
website":"http://www.urbiotica.com"
}

Action

List all devices from manufacturer

Method
GET

Resource
/manufacturers/{id}/devices

Request parameters
Parameter Description Type Compulsory
id Manufacturer identification number Integer Yes
Returns

A full list of all available devices from a certain manufacturer with ID {id} in the specified format.

Sample JSON response
[
{
"sensorID":"16",
"platformID":"2",
"latitude":"41.471882",
"longitude":"2.085344",
"offering":"urn:OFF02:208",
"procedure":"urn:santcugat:PLTWRS00002:SNS1146",
"name":"SNS1146",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
{
"sensorID":"17",
"platformID":"2",
"latitude":"41.472031",
"longitude":"2.085223",
"offering":"urn:OFF02:209",
"procedure":"urn:santcugat:PLTWRS00002:SNS1177",
"name":"SNS1177",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
...
]


Collections


Action

List all collections

Method
GET

Resource
/collections

Request parameters
none

Returns

A full list of all available collection objects in the specified format.

Sample JSON response
[
{
collectionID":"1",
name":"My favourite sensors",
description":"A collection of my favourite sensors",
creation_date":"2013-01-20 16:55:30",
userID":"1"
},
{
collectionID":"2",
name":"Parking sensors",
description":"Street parking sensors",
creation_date":"2013-01-20 16:58:30",
userID":"1"
},
...
]

Action

Describe collection

Method
GET

Resource
/collections/{id}

Request parameters
Parameter Description Type Compulsory
id Collection identification number Integer Yes
Returns

A full description of the collection with ID {id}.

Sample JSON response
{
collectionID":"1",
name":"My favourite sensors",
description":"A collection of my favourite sensors",
creation_date":"2013-01-20 16:55:30"
}

Action

List all devices from a collection

Method
GET

Resource
/collections/{id}/devices

Request parameters
Parameter Description Type Compulsory
id Collection identification number Integer Yes
Returns

A full list of all available devices from a certain collection with ID {id} in the specified format.

Sample JSON response
[
{
"sensorID":"16",
"platformID":"2",
"latitude":"41.471882",
"longitude":"2.085344",
"offering":"urn:OFF02:208",
"procedure":"urn:santcugat:PLTWRS00002:SNS1146",
"name":"SNS1146",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
{
"sensorID":"17",
"platformID":"2",
"latitude":"41.472031",
"longitude":"2.085223",
"offering":"urn:OFF02:209",
"procedure":"urn:santcugat:PLTWRS00002:SNS1177",
"name":"SNS1177",
"city":"Sant Cugat del Valles",
"manufacturer":"Worldsensing",
"properties":["urn:parking"]
},
...
]


Apps


Action

List all apps

Method
GET

Resource
/apps

Request parameters
none

Returns

A full list of all available app objects in the specified format.

Sample JSON response
[
{
appID":"1",
name":"My app",
status":"Preproduction",
},
{
appID":"2",
name":"My app 2",
status":"Production",
},
...
]

Action

Describe app

Method
GET

Resource
/apps/{id}

Request parameters
Parameter Description Type Compulsory
id App identification number Integer Yes
Returns

A full description of the app with ID {id}.

Sample JSON response
{
appID":"1",
name":"My app",
status":"Preproduction",
}

Action

List all infrastructures from an app

Method
GET

Resource
/apps/{id}/infrastructures

Request parameters
Parameter Description Type Compulsory
id App identification number Integer Yes
Returns

A full list of all available infrastructures from a certain app with ID {id} in the specified format.

Sample JSON response
[
{
"infrastructureID":"1",
"name":"PLTLDN001",
"cityID":"3,
"manufacturerID":"7",
"longitude":"0.000000",
"latitude":"0.000000",
"description":"Plataforma London Air Quality",
"status":"Enabled",
},
{
"infrastructureID":"2",
"name":"PLTBOL0001",
"cityID":"9,
"manufacturerID":"11",
"longitude":"0.000000",
"latitude":"0.000000",
"description":"Plataforma Weather Bolonia",
"status":"Disabled",
},
...
]

Observations




Action

List observations by samples

Method
GET

Resource
/observations/last?id={id}&infrastructureid={infrastructureid}&property={property}&n={n}&filter={filter}

Request parameters
Parameter Description Type Compulsory
id Device identification number Integer This is required if no infrastructureid is provided
infrastructureid Infrastructure identification number Integer This is required if no id is provided
property urn of the requested observation String Yes
filter The structure of the filter string depends on the property of the observation request:

urn:bus:expected_arrival: {stop};{line};{time}
urn:bus:expected_arrival:ivr: {stop};{line};{time}
urn:bus:sales_point: {stop;{salespoint}
urn:infocity:topic: {NAME};{TAG}
urn:infocity:office: {AREA};{NAME}
urn:infocity:topic:data: {TOPIC}
urn:infocity:office:data: {OFFICE}
urn:infocity:trip: {name1=value1%26name2=value2...}
urn:iris:state{token}
String No
n number of requested samples Integer Yes
Returns

Description of the observation samples.

Sample JSON response
[
{
"time":"2013-01-19T17:49:35",
"value":14.306,
"units":"C"
},
{
"time":"2013-01-19T18:09:41",
"value":14.187,
"units":"C"
},
{
"time":"2013-01-19T18:29:52",
"value":14.068,
"units":"C"
},
...
]


Action

List observations by time interval

Method
GET

Resource
/observations/interval?id={id}&infrastructureid={infrastructureid}&property={property}&from={from}&to={to}&filter={filter}

Request parameters
Parameter Description Type Compulsory
id Device identification number Integer This is required if no infrastructureid is provided
infrastructureid Infrastructure identification number Integer This is required if no id is provided
property urn of the requested observation String Yes
from Start of the interval ISO-8601 date (yyyy-mm-ddThh:mm:ss) Yes
to End of the interval ISO-8601 date (yyyy-mm-ddThh:mm:ss) Yes
filter The structure of the filter string depends on the property of the observation request:

urn:bus:expected_arrival: {stop};{line};{time}
urn:bus:expected_arrival:ivr: {stop};{line};{time}
urn:bus:sales_point: {stop;{salespoint}
urn:infocity:topic: {NAME};{TAG}
urn:infocity:office: {AREA};{NAME}
urn:infocity:topic:data: {TOPIC}
urn:infocity:office:data: {OFFICE}
urn:infocity:trip: {name1=value1%26name2=value2...}
urn:iris:state{token}
String No
Returns

Description of the observation samples.

Sample JSON response
[
{
"time":"2013-01-19T17:49:35",
"value":14.306,
"units":"C"
},
{
"time":"2013-01-19T18:09:41",
"value":14.187,
"units":"C"
},
{
"time":"2013-01-19T18:29:52",
"value":14.068,
"units":"C
},
...
]