Accessing data with REST API

You need an account to access data from Vicotee's Cloud. If you do not already have an account, click here to create one.

Important: You can only access data for sensors you own or someone shared sensors with you.

In this document, we will use Postman to demonstrate some of the API calls. Click here to download a free Postman application for Windows and Mac OS.

Token

All API requests need a token. To obtain a token, you need to use Login API:

URL:

POST   https://cloud.vicotee.com/api/auth/login

Header:

Content-Type : application/json

Request body:

{
  "email" : "<your-email>",
  "password" : "<your-password>"
}

  • Open your Postman and change method to "POST" and enter following to URL: https://cloud.vicotee.com/api/auth/login
  • Click on "Headers" tab and enter "Content-Type" as key and value as "application/json".
  • Click on "Body", select "raw" and enter the following: { "email" : "<your-email>", "password" : "<your-password>" }
    • NOTE: Please the whole <your-email> (including greater-than and lesser-than sign) with your username (email) and <you-password> with your password. The final JSON may look something like this: { "email" : "john@email.com", "password" : "mySecretPassword" }
  • Click "Send" to send request to the Cloud.

 

Postman - LoginPostman - Login - Body

 

Once you have send the login request, the server will response a token, this is the token you will use for all API calls where you set header:

Authorization : Bearer <replace-your-token-here>

IMPORTANT: Your token is valid for 90 days. Do not share the token with anyone.

 

Retrieve token without exposing email and password

On the 26th November 2018, we introduced login without exposing your email or password.

NOTE: If you created an account at cloud.vicotee.com before 26th November 2018, then you need activate Hashed-Login option by login as normal from website site cloud.vicotee.com or by API (see above). A simple login is enough to active the Hashed-Login option, and you only need to do this once. 

To login without exposing email and password, you simple remove attribute username and password from JSON and replace it with "hashed":

URL:

POST   https://cloud.vicotee.com/api/auth/login

Header:

Content-Type : application/json

Request body:

{
  "hashed" : "<sha256 of <your-email><password>>",
}

You calculate an SHA256 of your email and password with online services such as https://passwordsgenerator.net/sha256-hash-generator.

Example:

sha256 example
  • Copy your SHA256 hashed string and use it request body when calling (POST) https://cloud.vicotee.com/api/auth/login.

Important: If you change password or email, you need to re-hash your credentials and obtain the new hashed string. Do not share the hashed string with anyone!


Retrieve Measurements Data

To retrieve measurements for your device, you need the device UUID. You can find your device UUID on the label behind your sensor or use Vicotee's Cloud to find your device under Device Manager. Once you have your device UUID, the simplest API call to retrieve measurement data is as following:

URL:

GET   https://cloud.vicotee.com/api/mdata/<device-uuid>/measurements?offset=0&limit=25

Header:

Content-Type : application/json

Authorization : Bearer <replace-your-token-here>

Parameters:

<device-uuid> : Your device UUID.

offset : Retrieve data from the offset. If you have set offset=10, the server will skip the first 10 measurements and return from the 11th one.

limit : How many records you want to retrieve. If you want to retrieve 20 records, then set limit=20. Default is 25 if limit is not used. Maximum limit is 1000.

NOTE: This API is very simple, you can only retrieve data based on offset and limit. Example: when offset is 0 (zero), it means you want to retrieve latest measurement. If you set offset to 70, it means you want to retrieve the 70th measurement from the latest one. All measurements (when limit is set to greater than 1) return from this API is sorted by date, from newest to oldest (descending). It's ideal for "paging" allows you to build an application for viewing 50 latest measurements and then the user can navigate to "next page" and view another 50 older measurements.

Example of use with Postman to retrieve data for device with UUID 00170d000030b2e1:

Postman get measurements

Retrieve Datasets For Charts

As you can see, the above API call is very simple. For many users, by setting offset=0 and limit=1, they can retrieve the latest measurement data for a device and present that data on their application.

If you want more advanced API call to retrieve the measurements of your device, especially if you want to draw a chart, then use following:

URL:

GET   https://cloud.vicotee.com/api/mdata/<device-uuid>/datasets?fromDate=<from-date>&toDate=<to-date>&offset=0&limit=1000&type=TIMESERIES&interval

Header:

Content-Type : application/json

Authorization : Bearer <replace-your-token-here>

Parameters:

<device-uuid> : Your device UUID.

offset : Retrieve data from the offset. If you have set offset=10, the server will skip the first 10 measurements and return from the 11th one.

limit : How many records you want to retrieve. If you want to retrieve 20 records, then set limit=20. 

type : TIMESERIES or AGGREGATED.

fromDate : Date and time you want to retrieve your measurements. The format is YYYY-MM-dd HH:mm:ss Example: 2018-10-24 22:00:00. Note you need to URL encode the space with %20 between 'day' and 'hours of the day', the correct input will be 2018-10-24%2022:00:00

toDate : Date and time you want to retrieve your measurements. The format is YYYY-MM-dd HH:mm:ss Example: 2018-10-25 23:59:59. Note you need to URL encode the space with %20 between 'day' and 'hours of the day', the correct input will be 2018-10-25%2023:59:59

interval : Use together with AGGREGATED type. You can set interval as MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR. Note the interval has no effect if type is set as TIMESERIES.

NOTE: Max. limit is 1000.

Timeseries vs Aggregated

With type set as TIMESERIES, you will retrieve raw dataset with values and timestamps for each measurements. By setting type as AGGREGATED, you will retrieve aggregated data of maximum, minimum, average, over time frame such as minute, hourly, daily, weekly, monthly, quarter or yearly.

The advantage of aggregated datasets is the reduction of the amount of data. Let's say you have 10 measurements an hour in a year, that gives at least 864.000 measurements. If it's enough for you to know hourly average, maximum and minimum value for the whole year, the amount of data will be reduced to 8.640. Showing a chart with 8.640 data points make more sense for a user than showing over 864.000 data points.

Example of a Timeseries chart:

Timeseries Chart

Hourly aggregated chart from the same dataset as above:

Aggregated chart

Export CVS Data 

It is possible to export data as CVS, the Cloud will send you an email notification once the files are ready to be download.

Update notes:

  • From 22 January 2019, exported data will also contain hourly aggregated data.

URL:

POST   https://cloud.vicotee.com/api/map/dataexport?deviceUuids=<device-uuids>&fromDate=<from-date>&toDate=<to-date>

Header:

Content-Type : application/json

Authorization : Bearer <replace-your-token-here>

Parameters:

<device-uuids> : Your device UUID. For multiple devices, use comma separated list.

fromDate : Date and time you want to retrieve your measurements. The format is YYYY-MM-dd HH:mm:ss Example: 2018-10-24 22:00:00. Note you need to URL encode the space with %20 between 'day' and 'hours of the day', the correct input will be 2018-10-24%2022:00:00

toDate : Date and time you want to retrieve your measurements. The format is YYYY-MM-dd HH:mm:ss Example: 2018-10-25 23:59:59. Note you need to URL encode the space with %20 between 'day' and 'hours of the day', the correct input will be 2018-10-25%2023:59:59