API – Librerías
Encuentra información detallada sobre las API de SDS, incluyendo la autenticación, los métodos, los parámetros, los formatos de respuesta y los errores. Las guías de usuario y los manuales completos están disponibles para los socios activos.
Las guías de usuario y los manuales completos están disponibles para los socios activos.
DISPOSITIVOS API
El API para dispositivos está basada Sentilo, una plataforma de sensores y actuadores de código abierto liderada por el Ayuntamiento de Barcelona y respaldada por una comunidad de empresas y personas que garantizan la innovación y el apoyo continuos. Puede encontrar una descripción completa de todos sus objetos y métodos aquí.
Recursos
Recursos existentes:
- Sensor (dispositivo): entidad de hardware o software con la capacidad de generar una lectura.
- Componente: elemento de hardware o software, con ubicación geoespacial (fija o móvil) que puede contener uno o más Sensores.
- Proveedor: Entidad que representa un grupo de componentes y les proporciona conectividad con la plataforma. Se utiliza para enviar datos y recibir comandos.
- Aplicación Cliente/Módulo: entidad que consume los datos procesados por la plataforma.
Acciones disponibles:
Aplicaciones/Módulos:
- Enviar las órdenes a los proveedores/sensores (servicio de pedidos).
- Recibir datos de los proveedores/sensores (servicio de datos).
- Suscribirse a eventos del sistema (servicio de suscripción).
Proveedores/sensores:
- Registrarse en la plataforma (servicio de catálogo).
- Suscribirse a eventos del sistema (servicio de suscripción).
- Publicar datos (servicio de datos).
Identificador:
Cada recurso tiene una URL que lo identifica de forma única dentro del sistema según el formato que se describe a continuación:
[code lang=»php»][API URL]/[service] [/code]
Formato de los datos
Actualmente, la API admite JSON como formato de datos predeterminado.
[code lang=»php»][API URL]/service/[id_provider] ?[PARAMETER]=[VALUE] [/code]
Ejemplo de datos en formato JSON:
[code lang=»php»]{«observations»:[
{«value»:«12.3»,«timestamp»:«17/09/2012T12:34:45»}
]} [/code]
APLICACIONES API
Encuentra una descripción general de los métodos y objetos relacionados con los sitios de implementación, los sensores y las mediciones disponibles para los desarrolladores que desean diseñar aplicaciones externas en la plataforma que elijan o integrar las existentes.
La referencia completa de la API está disponible en la interfaz web de la plataforma.
Seguridad
La plataforma validará cualquier solicitud recibida por el sistema en base a la arquitectura AAA (Autenticación, Autorización y Contabilidad).
Los tokens de autenticación se proporcionan cuando un socio se activa en la plataforma.
Instalaciones
INSTALACIONES (Sitios de implementación)
A través de este servicio, puede recuperar la lista de instalaciones y los detalles relacionados asociados con tu usuario. Todas las solicitudes de este servicio deben tener el siguiente formato:
[code lang=»php»][API URL]/installations?[PARAMETER]=[VALUE] [/code]
Parámetros:
| Key | Description | Mandatory |
| id | Used to filter the list by the installation unique identifier | No |
Además del código de estado HTTP, esta acción devuelve la lista de instalaciones para las que tenemos permiso de lectura. Cada elemento de la lista tendrá la siguiente estructura:
| 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 |
Ejemplo: Para recuperar detalles de la instalación con ID 142, tenemos que enviar la siguiente solicitud:
[code lang=»php»][API URL]/installations?id=142[/code]
En la respuesta recibiremos:
[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]
Sensores
A través de este servicio, puedes recuperar la lista de sensores y los detalles relacionados asociados con tu usuario. Todas las solicitudes de este servicio deben tener el siguiente formato:
[code lang=»php»][API URL]/sensors?[PARAMETER]=[VALUE] [/code]
Parámetros:
| 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 |
Además del código de estado HTTP, esta acción devuelve la lista de instalaciones para las que tenemos permiso de lectura. Cada elemento de la lista tendrá la siguiente estructura:
| 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 |
Ejemplo: Para recuperar la lista de sensores asociados a la instalación con ID 142, tenemos que enviar la siguiente solicitud:
[code lang=»php»][API URL]/sensors?installationid=142[/code]
En la respuesta recibiremos:
[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]
Mediciones
A través de este servicio, puedes recuperar la lista de mediciones recibidas a través de la plataforma. Todas las solicitudes de este servicio deben tener el siguiente formato:
[code lang=»php»][API URL]/measurements?[PARAMETER]=[VALUE] [/code]
Parámetros
| 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 |
Formatos de datos de salida disponibles
| 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 |
Además del código de estado HTTP, esta acción devuelve una lista de mediciones. Esta es la estructura de salida si el formato de datos de salida seleccionado es 0 (mediciones individuales):
| Key | Description |
| timestamp | Timestamp of the measurement |
| value | Value of the measurement |
En el caso de que el formato de datos de salida especificado sea 10, 11, 12, 20, 21, 22, 30, 31 o 32, la estructura de salida será la misma, pero con un significado ligeramente diferente:
| Key | Description |
| timestamp | Timestamp of the begin of the sampling interval |
| value | Average, lowest (minimum) or highest (maximum) value received in the sampling interval |
En el caso de que el formato de datos de salida especificado sea 13, 23, 33 o 43, cada elemento de la lista tendrá esta estructura alternativa:
| 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 |
Si no se ha especificado el huso horario, todas las marcas de tiempo y los intervalos de muestreo se referirán a la zona horaria GMT.
Nota: Se incluirán las mediciones con marca de tiempo al comienzo del intervalo de tiempo. Se excluirá la medición con marca de tiempo al final del intervalo de tiempo.
Ejemplo 1: Necesitamos recuperar la lista de mediciones recibidas del sensor con ID 1517, desde el 10 de octubre de 2015 a las 08:00:00 CEST hasta el 10 de octubre de 2015 a las 10:00:00 CEST, y queremos que nuestro resultado esté en la Zona horaria GMT. Entonces, tenemos que enviar la siguiente solicitud:
[code lang=»php»][API URL]/measurements?sensorid=1517&begin=1444456800&end=1444464000[/code]
En la respuesta recibiremos:
[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]
Ejemplo 2: Necesitamos recuperar la lista promedio por hora de mediciones recibidas del sensor con ID 1517, desde el 10 de octubre de 2015 a las 08:00:00 CEST hasta el 10 de octubre de 2015 a las 12:00:00 CEST, y queremos que nuestro resultado esté en nuestra zona horaria CEST local. Entonces, tenemos que enviar la siguiente solicitud:
[code lang=»php»][API URL]/measurements?sensorid=1517&begin=1444456800&end=1444464000[/code]
En la respuesta recibiremos:
[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]
jemplo 3: necesitamos recuperar la lista de mediciones diarias mínima + máxima recibidas del sensor con ID 1517, desde el 8 de octubre de 2015 a las 00:00:00 CEST hasta el 10 de octubre de 2015 a las 00:00:00 CEST, y queremos que nuestro resultado esté en nuestra zona horaria CEST local. Por eso, tenemos que enviar la siguiente solicitud:
[code lang=»php»][API URL]/measurements?sensorid=1517&begin=1444255200&end=1444428000&sampling=23&timeoffset=7200[/code]
En la respuesta recibiremos:
[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]
