API Documentation

Get asset model info

As mentioned in the concept section, the data is structured in an asset model, where sensors are mapped to system paths. There are two main ways to identify what data is available from a vessel:

Getting a list from KDI containing the mapped paths.
Fetching a filtered list of paths from the POST FindNodes endpoint.

This list of paths will serve as input when querying data from the APIs.

Pulling the list of paths is typically a one-time job, however there could be sensor additions mapped to the asset model after initial setup.

Note that in rare cases, the sensor mapped to the path could be subjected to change, if requested by data owner or a better suited sensor has been identified onboard.

Check which vessels are available

To see which vessels you have access to, we can use the GET Nodes endpoint.

Note the parameters specify the top fleet node and max level of child nodes to return:

path =/Fleet
maxLevelOfEdges=1

curl --location 'https://api.kognif.ai/assets/v2/assetmodel/nodes?path=%2FFleet&maxLevelOfEdges=1' 
\--header 'Ocp-Apim-Subscription-Key: [YOUR-OCP-APIM-SUBSCRIPTION-KEY]' 
\--header 'Authorization: ••••••'

The response contains all parent nodes in the asset structure that represent vessels, excluding the child nodes or paths. For this example, it returns two vessels:

Vessel named Seagull with IMO number imoXXX
Vessel named Simrad Echo with IMO number imoYYY

[ { 
  "id": "2", 
  "name": "Fleet", 
  "displayName": "Fleet", 
  "nodeType": "Unspecified", 
  "path": "/Fleet", 
  "hasEdges": true, 
  "edges": [ 
    { 
    "name": "imoXXX", 
    "displayName": "Seagull", 
    "node": { 
      "id": "109368", 
      "name": "imoXXX", 
      "displayName": "Seagull", 
      "nodeType": "Component", 
      "path": "/Fleet/imoXXX", 
      "hasEdges": true, 
      "edges": [] }, 
    "type": "Child" },
    { 
    "name": "imoYYY", 
    "displayName": "Simrad Echo", 
    "node": { 
      "id": "382172", 
      "name": "imoYYY", 
      "displayName": "Simrad Echo", 
      "nodeType": "Component", 
      "path": "/Fleet/imoYYY", 
      "hasEdges": true, 
      "edges": [] }, 
    "type": "Child" }
    ] 
} ]

Filtering asset model based on conditions

The POST Find Nodes endpoint allows applying conditional filters to return specific paths in the asset model.

The conditional filters can use attributes on the nodes, conditional operators and attribute values as filter inputs. Only one condition can be applied in a request. A generic setup looks like this:

curl --location 'https://api.kognif.ai/assets/v2/assetmodel/nodes' 
\--header 'Ocp-Apim-Subscription-Key: [YOUR OCP-APIM-SUBSCRIPTION-KEY]' 
\--header 'Content-Type: application/json' 
\--header 'Authorization: ••••••' 
\--data '{    
"path": "PARENT NODE PATH",      
"attributeCondition": {            
  "attributeName": "NAME OF ATTRIBUTE",            
  "operator": "OPERATOR",
  "attributeValue": "VALUE"          
},       
"attributeKeys": ["WHICH ATTRIBUTES TO INCLUDE"]
}'

An overview of node path attributes can be found in the Concepts section, while the allowed values for operators can be found in the API reference docs.

Some common scenarios for data users are described below.

For the examples, we've only included the request body for readability.

Filtering: Get all paths with data

To see which paths contains any data for any time period, you can specify the following parameters in the request body:

path=/Fleet:This parameter will specify from which parent node to return all paths under. The example uses parent path=/Fleet, which is the global fleet parent node. To get paths on a specific vessel, you can add the IMO string to the parent node path. E.g. path=/Fleet/imoXXX
attributeName = latestTimestamp
operator = isnotempty

This request will return all paths that has at least one datapoint (latestTimestamp) under path=/Fleet, meaning that all vessels in the fleet are included.

\--data '{    
"path": "/Fleet",    
  "attributeCondition": {        
    "attributeName": "latestTimestamp",        
    "operator": "isnotempty"        
     },    
  "view": "v1",    
  "attributeKeys": ["latestTimestamp"]
}'

Filtering: Get all mapped paths with fresh data

To see which paths have fresh data, its possible to filter out paths that has latestTimestamp greater than a certain time limit defined by the attributeValue.

Request body:

{
   "path":"/Fleet",
   "attributeCondition":{
      "attributeName":"latestTimestamp",
      "operator":">",
      "attributeValue":"2024-10-31T00:00:00Z"
   },
   "view":"v1",
   "attributeKeys":[
      "latestTimestamp"
   ]
}

Response contains all paths with latest timestamp greater than the limit:

{
   "id":109374,
   "name":"Generator_Power",
   "displayName":"Generator Power",
   "nodeType":"TimeSeries",
   "path":"/Fleet/imoXXX/Aux_Engines/1/Generator_Power",
   "hasEdges":false,
   "edges":[   ],
   "attributes":{
      "displayName":"Generator Power",
      "latestTimestamp":"2024-11-01 12:27:37+00",
}