API REFERENCE

Find detailed information about the SDS APIs including authentication, methods, parameters, response formats and errors.

Full user guides and manuals are available for active partners.

DEVICES API

The Devices API is based on Sentilo, an open source sensor and actuator platform led by Barcelona City Council and backed by a community of companies and individuals that ensure continuous innovation and support.

A complete description of all its objects and methods can be found here.

Resources:

Existing resources:

  • Sensor (device): hardware or software entity with the ability to generate a reading.
  • Component: Element of hardware or software, with geospatial location (fixed or mobile) that can contain one or more Sensors.
  • Provider: Entity that represents a group of components and provides them with connectivity with the platform. Used to send data and receive commands.
  • Client Application/Module: entity that consumes the data processed by the platform.

Available actions:

Applications/Modules:

  • Send orders to providers/sensors (order service).
  • Receive data from providers/sensors (data service).
  • Subscribe to system events (subscribe service).

Providers/sensors:

  • Register to the platform (catalog service).
  • Subscribe to system events (subscribe service).
  • Publish data (data service).

Identifier:

Each resource has a URL that uniquely identifies it within the system based on the format described next.

  1. [API URL]/[service]

Data formats

The API currently supports JSON as default data format.

  1. [API URL]/service/[id_provider] ?[PARAMETER]=[VALUE]

Example data in JSON format:

  1. {"observations":[
  2. {"value":"12.3","timestamp":"17/09/2012T12:34:45"}
  3. ]}

APPLICATIONS API

Find an overview of methods and objects related to deployment sites, sensors and measurements available to developers who want to design external applications in their platform of choice or integrate existing ones.

Full API reference is available on the platform web interface.

SECURITY

The platform will validate any request received by the system based on the AAA architecture (Authentication, Authorization, and Accounting).

Authentication tokens are provided when a partner becomes active on the platform.

SERVICES

INSTALLATIONS (Deployment Sites)

Through this service, you can retrieve the installations list and related details associated with your user. All requests for this service must have the following format:

  1. [API URL]/installations?[PARAMETER]=[VALUE]

Parameters:

Key Description Mandatory
id Used to filter the list by the installation unique identifier No

In addition to the HTTP status code, this action returns the list of installations for which we have read permission. Each list element will have the following structure:

Key Description
id Unique installation identifier
name Installation name
typology Installation typology
address Address of the installation
zip ZIP code of the installation
city City of the installation
State State of the installation
country Country of the installation
latitude GPS coordinates of the installation, latitude
longitude GPS coordinates of the installation, longitude

Example: To retrieve details of the installation with ID 142, we have to send the following request:

  1. [API URL]/installations?id=142

In the response we will receive:

  1. {"installations":[
  2. {
  3. "id":142,
  4. "name":"Demo installation",
  5. "typology":"Datacenter",
  6. "address":"Passeig de Gràcia, 47",
  7. "zip":"08007",
  8. "city":"Barcelona",
  9. "state":"Barcelona",
  10. "country":"España",
  11. "latitude":41.392408931363,
  12. "longitude":2.1645916698617
  13. }
  14. ]}

SENSORS

Through this service, you can retrieve the sensors list and related details associated with your user. All requests for this service must have the following format:

  1. [API URL]/sensors?[PARAMETER]=[VALUE]

Parameters:

Key Description Mandatory
id Used to filter the list by the sensor unique identifier No
installationid Used to filter the list by the installation unique identifier No

In addition to the HTTP status code, this action returns the list of installations for which we have read permission. Each list element will have the following structure:

Key Description
id Unique sensor identifier
installationId Unique installation identifier
name Name of the sensor
measurementUnit Measurement unit associated with the sensor
granularity Time interval (seconds) between two measurements
multiplier Value which any measurement will be multiplied by
offset Constant value added to any measurement after the operation above

Example: To retrieve list of sensors associated with the installation with ID 142, we have to send the following request::

  1. [API URL]/sensors?installationid=142

In the response we will receive:

  1. {"sensors":[
  2. {
  3. "id":1517,
  4. "installationId":142,
  5. "name":"Datacenter temperature",
  6. "measurementUnit":"°C",
  7. "granularity":900,
  8. "multiplier":1,
  9. "offset":0
  10. },{
  11. "id":1518,
  12. "installationId":142,
  13. "name":"Datacenter humidity",
  14. "measurementUnit":"%",
  15. "granularity":900,
  16. "multiplier":1,
  17. "offset":0
  18. }
  19. ]}

MEASUREMENT

Through this service, you can retrieve the measurements list received through the platform. All requests for this service must have the following format:

  1. [API URL]/measurements?[PARAMETER]=[VALUE]

Parameters

Key Description Mandatory
sensorid Used to select the sensor Yes
begin Begin of the time interval, EPOCH format Yes
end End of the time interval, EPOCH format Yes
sampling Output data format (view table below) No
timeoffset Time offset (seconds) applied to any timestamp and sampling interval No

Available output data formats

Value Description
0 (Default) Individual measurements (raw values)
10 Hourly sampling, average value
11 Hourly sampling, minimum value
12 Hourly sampling, maximum value
13 Hourly sampling, minimum and maximum value
20 Daily sampling, average value
21 Daily sampling, minimum value
22 Daily sampling, maximum value
23 Daily sampling, minimum and maximum value
30 Monthly sampling, average value
31 Monthly sampling, minimum value
32 Monthly sampling, maximum value
33 Monthly sampling, minimum and maximum value
40 Yearly sampling, average value
41 Yearly sampling, minimum value
42 Yearly sampling, maximum value
43 Yearly sampling, minimum and maximum value

In addition to the HTTP status code, this action returns a list of measurement. This is the output structure if the selected output data format is 0 (individual measurements):

Key Description
timestamp Timestamp of the measurement
value Value of the measurement

In the case the specified output data format is 10, 11, 12, 20, 21, 22, 30, 31 or 32 the output structure will be the same, but with a slightly different meaning:

Key Description
timestamp Timestamp of the begin of the sampling interval
value Average, lowest (minimum) or highest (maximum) value received in the sampling interval

In the case the specified output data format is 13, 23, 33 or 43, each list element will have this alternative structure:

Key Description
timestamp Timestamp of the begin of the sampling interval
low Lowest (minimum) value received in the sampling interval
high Highest (maximum) value received in the sampling interval

If the time offset hasn’t been specified, all the timestamps and sampling intervals will refer to the GMT time zone.

Note: Measurements with timestamp at the beginning of the time interval will be included. Measurement with timestamp at the end of the time interval will be excluded.

Example 1: We need to retrieve the raw list of measurements received from the sensor with ID 1517, from 10th October 2015 08:00:00 CEST until 10th October 2015 10:00:00 CEST, and we want our output to be in the GMT timezone. So, we have to send the following request:

  1. [API URL]/measurements?sensorid=1517&begin=1444456800&end=1444464000

In the response we will receive:

  1. {"measurements":[
  2. {
  3. "timestamp":"2015-10-10 06:00:01",
  4. "value":27.5
  5. },{
  6. "timestamp":"2015-10-10 06:15:02",
  7. "value":27.9
  8. },{
  9. "timestamp":"2015-10-10 06:30:01",
  10. "value":28.1
  11. },{
  12. "timestamp":"2015-10-10 06:45:02",
  13. "value":27.7
  14. },{
  15. "timestamp":"2015-10-10 07:00:02",
  16. "value":27.4
  17. },{
  18. "timestamp":"2015-10-10 07:15:00",
  19. "value":26.9
  20. },{
  21. "timestamp":"2015-10-10 07:30:01",
  22. "value":26.8
  23. },{
  24. "timestamp":"2015-10-10 07:45:01",
  25. "value":27.3
  26. }
  27. ]}

Example 2: We need to retrieve the hourly average list of measurements received from the sensor with ID 1517, from 10th October 2015 08:00:00 CEST until 10th October 2015 12:00:00 CEST, and we want our output to be in our local CEST timezone. So, we have to send the following request:

  1. [API URL]/measurements?sensorid=1517&begin=1444456800&end=1444464000

In the response we will receive:

  1. {"measurements":[
  2. {
  3. "timestamp":"2015-10-10 08:00:00",
  4. "value":27.6
  5. },{
  6. "timestamp":"2015-10-10 09:00:00",
  7. "value":27.7
  8. },{
  9. "timestamp":"2015-10-10 10:00:00",
  10. "value":28.0
  11. },{
  12. "timestamp":"2015-10-10 11:00:00",
  13. "value":27.9
  14. }
  15. ]}

Example 3: we need to retrieve the daily minimum+maximum list of measurements received from the sensor with ID 1517, from 08th October 2015 00:00:00 CEST until 10th October 2015 00:00:00 CEST, and we want our output to be in our local CEST timezone. So, we have to send the following request:

  1. [API URL]/measurements?sensorid=1517&begin=1444255200&end=1444428000&sampling=23&timeoffset=7200

In the response we will receive:

  1. {"measurements":[
  2. {
  3. "timestamp":"2015-10-08 00:00:00",
  4. "low":25.4
  5. "high":29.6
  6. },{
  7. "timestamp":"2015-10-09 00:00:00",
  8. "low":25.8
  9. "high":30.3
  10. }
  11. ]}