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.
DISPOSITIVOS 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).
Proveedores/sensores:
- 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.
[code lang=”php”][API URL]/[service] [/code]
Data formats
The API currently supports JSON as default data format.
[code lang=”php”][API URL]/service/[id_provider] ?[PARAMETER]=[VALUE] [/code]
Example data in JSON format:
[code lang=”php”]{«observations»:[
{«value»:«12.3»,«timestamp»:«17/09/2012T12:34:45»}
]} [/code]
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.
Installations
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:
[code lang=”php”][API URL]/installations?[PARAMETER]=[VALUE] [/code]
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::
[code lang=”php”][API URL]/installations?id=142[/code]
In the response we will receive:
[code lang=”php”]{«installations»:[
{
«id»:142,
«name»:«Demo installation»,
«typology»:«Datacenter»,
«address»:«Passeig de Gràcia, 47»,
«zip»:«08007»,
«city»:«Barcelona»,
«state»:«Barcelona»,
«country»:«España»,
«latitude»:41.392408931363,
«longitude»:2.1645916698617
}
]} [/code]
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:
[code lang=”php”][API URL]/sensors?[PARAMETER]=[VALUE] [/code]
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:
[code lang=”php”][API URL]/sensors?installationid=142[/code]
In the response we will receive:
[code lang=”php”]{«sensors»:[
{
«id»:1517,
«installationId»:142,
«name»:«Datacenter temperature»,
«measurementUnit»:«°C»,
«granularity»:900,
«multiplier»:1,
«offset»:0
},{
«id»:1518,
«installationId»:142,
«name»:«Datacenter humidity»,
«measurementUnit»:«%»,
«granularity»:900,
«multiplier»:1,
«offset»:0
}
]} [/code]
Measurements
Through this service, you can retrieve the measurements list received through the platform. All requests for this service must have the following format:
[code lang=”php”][API URL]/measurements?[PARAMETER]=[VALUE] [/code]
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:
[code lang=”php”][API URL]/measurements?sensorid=1517&begin=1444456800&end=1444464000[/code]
In the response we will receive:
[code lang=”php”][
{«measurements»:[
{
«timestamp»:«2015-10-10 06:00:01»,
«value»:27.5
},{
«timestamp»:«2015-10-10 06:15:02»,
«value»:27.9
},{
«timestamp»:«2015-10-10 06:30:01»,
«value»:28.1
},{
«timestamp»:«2015-10-10 06:45:02»,
«value»:27.7
},{
«timestamp»:«2015-10-10 07:00:02»,
«value»:27.4
},{
«timestamp»:«2015-10-10 07:15:00»,
«value»:26.9
},{
«timestamp»:«2015-10-10 07:30:01»,
«value»:26.8
},{
«timestamp»:«2015-10-10 07:45:01»,
«value»:27.3
}
]} [/code]
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:
[code lang=”php”][API URL]/measurements?sensorid=1517&begin=1444456800&end=1444464000[/code]
In the response we will receive:
[code lang=”php”]{«measurements»:[
{
«timestamp»:«2015-10-10 08:00:00»,
«value»:27.6
},{
«timestamp»:«2015-10-10 09:00:00»,
«value»:27.7
},{
«timestamp»:«2015-10-10 10:00:00»,
«value»:28.0
},{
«timestamp»:«2015-10-10 11:00:00»,
«value»:27.9
}
]} [/code]
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:
[code lang=”php”][API URL]/measurements?sensorid=1517&begin=1444255200&end=1444428000&sampling=23&timeoffset=7200[/code]
In the response we will receive:
[code lang=”php”]{«measurements»:[
{
«timestamp»:«2015-10-08 00:00:00»,
«low»:25.4
«high»:29.6
},{
«timestamp»:«2015-10-09 00:00:00»,
«low»:25.8
«high»:30.3
}
]}[/code]
