API – Quickstart

Get started quickly with and overview of the components involved in a typical solutions and practical examples on how to connect a device and how to integrate an external system to the SDS Platform.

OVERVIEW

Before starting your project, you need to have a clear understanding of the components involved in your solution. The following questions will help you clarify what you may need.

  1. Devices
    From where are you trying to retrieve information or what device will you send instructions to? Common examples are utilities meters, temperature sensors, doors lock/unlock mechanisms, etc.
  2. Connectivity
    Does the device already has connectivity and allows to configure parameters to be sent, or do you need to provide connectivity through a gateway?
  3. SDS Platform
    Will you use the platform as the user interface to provide your solution or will you create or use and external system
  4. External System
    Will you develop your own external application or are you integrating a 3rd party system?

CONNECT A DEVICE

In this example we will send a reading from a device to the platform through the Devices API. PHP has been used as scripting language, but you can select the language of your choice.

[code lang=”php”]
/*

This example sends a numerical measurement (10.5) from sensor

SENSOR001, owned by provider PROVIDER001, identified by token:

79d2dfe9ea9af9dd015befebda62180673314c8abb8898d626c66959448cae0d

And then prints the platform server reply.

*/

$providername = ‘PROVIDER001’;

$sensorname = ‘SENSOR001’;

$token = ’79d2dfe9ea9af9dd015befebda62180673314c8abb8898d626c66959448cae0d’;

$value = ‘10.5’;

$json = ‘{«observations»:[{«value»:»‘.$value.‘»}]}’;

$api_request_url = ‘[DEVICES API URL]/data/’.$providername.‘/’.$sensorname;

$ch = curl_init();

curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

curl_setopt($ch, CURLOPT_HEADER, TRUE);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ‘PUT’);

curl_setopt($ch, CURLOPT_POSTFIELDS, $json);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘IDENTITY_KEY: ‘.$token,‘Content-Type: application/json’));

curl_setopt($ch, CURLOPT_URL, $api_request_url);

$api_response = curl_exec($ch);

$api_response_info = curl_getinfo($ch);

curl_close($ch);

$api_response_header = trim(substr($api_response, 0, $api_response_info[‘header_size’]));

echo $api_response_header;

[/code]

INTEGRATE AN APPLICATION

Let’s read some data from the temperature sensor we have just connected (see “Connect Device”) through the Applications API, and insert into an external database.

[code lang=”php”]
/*

This example gets the list of raw measurements sent by a temperature sensor, which ID is 5123, from 2016-10-10 00:00:00 UTC to 2016-10-11 00:00:00 UTC.

The user who’s sending the request is identified by token:

0a2fb1d34c30dab68c6cf36c7218b4b332059e19db35c6fc9f6c56fd30d0223d

After the request, it prints the list as a HTML table.

*/

$sensorid = ‘5123’;

$begin = ‘1476057600’; // 2016-10-10 00:00:00 UTC

$end = ‘1476144000’; // 2016-10-11 00:00:00 UTC

$apiKey = ‘0a2fb1d34c30dab68c6cf36c7218b4b332059e19db35c6fc9f6c56fd30d0223d’;

$api_request_url = ‘http://api.smartdatasystem.es/v1/measurements?sensorid=’.$sensorid.‘&begin=’.$begin.‘&end=’.$end;

$ch = curl_init();

curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

curl_setopt($ch, CURLOPT_HEADER, TRUE);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ‘GET’);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘apiKey: ‘.$apiKey,‘Content-Type: application/json’));

curl_setopt($ch, CURLOPT_URL, $api_request_url);

$api_response = curl_exec($ch);

$api_response_info = curl_getinfo($ch);

$results = json_decode(trim(substr($api_response, $api_response_info[‘header_size’])))->measurements;

curl_close($ch);

[/code]