This section describes methods and endpoints for fetching data from the VI APIs. The guide assumes you have a list of paths ready, as the paths are used as parameters to select which data to return in the API calls as explained in Get asset model info.
Get data for multiple paths in one request
A recommended practice is to request data for multiple paths in one request, instead of one request for each path.
To get data for multiple paths, you can use the POST OnGridByPath endpoint.
It will take a list of paths along with the query parameters, and return synchronized datapoints, meaning that the timestamps for each timeseries are aligned to common timestamps by some aggregate method. This is handy for analytics purposes due to the fact that the sensors in the data source side may have different sampling frequency and datapoints could be irregularly distributed.
Request curl:
curl -L 'https://api.kognif.ai/assets/v2/timeseries/OnGridByPath'
\ -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'
\ -H 'Content-Type: application/json'
\ -H 'Authorization: ••••••'
\ -d '{BODY}'
The request body below contains the query parameters. They are:
Name | Description and allowed values |
|---|
from | From datetime in ISO 8601 format. YYYY-DD-MMTHH:MM:SSZ. The Z indicates zulu/UTC time. |
to | To datetime in ISO 8601 format. YYYY-DD-MMTHH:MM:SSZ. The Z indicates zulu/UTC time. |
interval | Specifies the interval period for each aggregate. 1s, 5s, 10s, 1m, 5m, 10m, 1h, 6h, 1d, 1w, 1M, 3M, 1y |
resamplingMethods | Specifies which aggregate to be returned for each interval. avg, sum, count, min, max |
Paths | Array with the paths you want to fetch data from |
The parameters allow shaping the query to meet various needs.
Note that the max number of items in the OnGridByPath response is 10 000, so if you're exceeding this limit, try reducing either the timeperiod or the number of paths. Typically, we recommend to set up a recurring scheduled API call with an poll interval of 1 hour, using 1 minute aggregate intervals in the queries. Assuming you have 100 paths, this will return 6000 items.
An example request body:
{
"from":"2023-10-13T00:00:00.0000000Z",
"to":"2023-10-14T00:00:00.0000000Z",
"interval":"1h",
"resamplingMethods":[
"avg"
],
"paths":[
"/Fleet/imoXXX/Aux_Boilers/FO_Flow",
"/Fleet/imoXXX/Machinery_Systems/Fuel_Oil_System/Storage_Tanks/9/Volume",
"/Fleet/imoXXX/Power_Management/MSB_Load_Total"
]
}
The response contains time parameters along with the aggregated datapoints for each path.
The timestamps are implicitly given by the time and interval parameters to reduce response size, and can be generated from this information and indexing. The first value in samples corresponds to time + 0*interval, the second value corresponds to time+1*interval and so on to the latest item in the samples.
In the below example response, for path=/Fleet/imoXXX/Machinery_Systems/Fuel_Oil_System/Storage_Tanks/9/Volume, the timestamp logic looks like this:
- the 1st sample 199.574 corresponds to timestamp 2023-10-13T00:00:00Z,
- the 2nd sample 198.293 corresponds to timestamp 2023-10-13T00:00:00Z
- ..
- the 24th sample 168.932 corresponds to timestamp 2023-10-14T00:00:00Z
The samples contains the calculated aggregate for the interval period, which in this example is 1 hour. That means that for each interval, its calculating the average of all raw data points within the hourly interval bounds. If there are no raw data points within the interval, the returned value will be NaN for that interval.
{
"intervalInSeconds":3600,
"resamplingMethod":"avg",
"time":"2023-10-13T00:00:00Z",
"interval":"1h",
"columns":[
{
"path":"/Fleet/imoXXX/Machinery_Systems/Fuel_Oil_System/Storage_Tanks/9/Volume",
"unit":"m3",
"samples":[
199.57423076923078,
198.29383429672447,
196.3337890625,
..
168.93255813953488
]
},
{
"path":"/Fleet/imoXXX/Aux_Boilers/FO_Flow",
"unit":"L/h",
"samples":[
81.34661354581674,
83.62641509433962,
..
24.6
]
},
{
"path":"/Fleet/imoXXX/Power_Management/MSB_Load_Total",
"unit":"kW",
"samples":[
496.9865771812081,
470.5814479638009,
..
483.42120911793853
]
}
],
"errors":[
]
}
Another example request body, fetching max, min and the count aggregates of two paths:
{
"from":"2023-10-13T00:00:00.0000000Z",
"to":"2023-10-13T01:00:00.0000000Z",
"interval":"1h",
"resamplingMethods":[
"max",
"min",
"count"
],
"paths":[
"/Fleet/imoXXX/Aux_Boilers/FO_Flow",
"/Fleet/imoXXX/Machinery_Systems/Fuel_Oil_System/Storage_Tanks/9/Volume"
]
}
Response:
{
"intervalInSeconds":3600,
"resamplingMethods":[
"max",
"min",
"count"
],
"time":"2023-10-13T00:00:00Z",
"interval":"1h",
"columns":[
{
"path":"/Fleet/imoXXX/Machinery_Systems/Fuel_Oil_System/Storage_Tanks/9/Volume",
"unit":"m3",
"samples":[
{
"max":226.9,
"min":157,
"count":520
},
{
"max":222.7,
"min":163.8,
"count":519
}
]
},
{
"path":"/Fleet/imoXXX/Aux_Boilers/FO_Flow",
"unit":"L/h",
"samples":[
{
"max":273,
"min":0,
"count":251
},
{
"max":301,
"min":0,
"count":265
}
]
}
],
"errors":[
]
}
Getting latest value for multiple paths
To get the latest data points received in the VI cloud, we'll use the POST GetLatestValue.
This endpoint is useful to see if fresh data is streaming from the vessel to the cloud.
Request cURL:
curl -L 'https://api.kognif.ai/assets/v2/timeseries/LatestValue/Paths?includeNaN=true&convertToStdUnit=true'
\ -H 'Ocp-Apim-Subscription-Key: 44d5ad4a4a7540738f9a338cafdce2ea'
\ -H 'Content-Type: application/json'
\ -H 'Authorization: ••••••'
\ -d 'body'
The request body contains the list of paths you want to get the latest value for:
[
"/Fleet/imoXXX/Aux_Boilers/FO_Flow",
"/Fleet/imoXXX/Engines/Main/1/FO_Flow"
]
Response:
{
"/Fleet/imoXXX/Aux_Boilers/FO_Flow":{
"timestamp":"2024-11-01T12:04:27.0000000Z",
"values":[
0
],
"vectorElementData":[
{
"name":"FO_Flow",
"displayName":"FO Flow",
"unitId":"kg/h",
"displayUnitId":"L/h"
}
]
},
"/Fleet/imoXXX/Engines/Main/1/FO_Flow":{
"timestamp":"2024-11-01T12:04:47.0000000Z",
"values":[
798
],
"vectorElementData":[
{
"name":"FO_Flow",
"displayName":"FO Flow",
"unitId":"kg/h",
"displayUnitId":"L/h"
}
]
}
}