The Vessel Insight API lets you connect to vessel data. This guide demonstrates how to make your first API calls by fetching datapoints for a path. For more info on datapoints and paths, please check out the core concepts page Overall dataflow.
There is also a Postman collection for testing the APIs available.
Prerequisites
Before you get started, you need a tenant_id, client_id, client_secret and subscription key (Ocp-Apim-Subscription-Key). How to get them and what they represent is described in this section Accessing the API.
Step 1: Getting a token
We'll use the credentials above to retrieve a token. This guide uses cURL for showing examples, but its recommended to use Postman. Replace the strings inside the square brackets with your values, including the brackets.
curl --location 'https://login.microsoftonline.com/<tenant_id>/oauth2/token'
\--data-urlencode 'grant_type=client_credentials'
\--data-urlencode 'client_secret=[client_secret]'
\--data-urlencode 'client_id=[client_id]'
\--data-urlencode 'resource=[resource_id]'
If the credentials are correct, you should get successful response containing an access_token:
{
"token_type": "Bearer",
"access_token": "YOUR_ACCESS_TOKEN"
}
This token will expire in 1 hour. It will be used in the rest of the examples. We'll use the Ocp-Apim-subscription-key in the headers.
Step 2: Fetch path
The available data is structured in a standard asset structure, where each sensor is mapped to a path in the asset structure.
We'll use the find nodes endpoint to find paths that has data.
The path is used as reference to fetch data:
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": "/Fleet",
"attributeCondition": {
"attributeName": "latestTimestamp",
"operator": "isnotempty"
},
"view": "v1",
"attributeKeys": ["latestTimestamp"]
}'
In short, the response will contain all paths that has data.
Looking a bit closer at the request and the response, it is returning all paths that match the conditional filter in the request. The filter we've applied above represents the scenario: Return all paths under /Fleet where attribute=latestTimestmap is not empty. More info on data path filtering in this section.
We'll use the below path /Fleet/imoXXX/Aux_Engines/1/Generator_Power as example for fetching data. From the response, we can see that the path has these attributes:
[
{
"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-10-31 08:24:18+00",
"streamLink": "76c1f35f-f051-464a-a697-efd04744cc0e_K-Chief%20600_C600.Tag.DG1-LOAD",
"paths2": "[{\"Path\":\"/Fleet/imoXXX/Aux_Engines/1/Generator_Power\",\"DisplayPath\":\"/Fleet/Seagull/Aux Engines/DG1/Generator Power\",\"Views\":[\"FavVessel\",\"all\",\"v2\",\"v1\"],\"Primary\":true,\"Link\":false}]"
}
}, ..
]
Step 3: Fetch data
Now we have a path to vessel data, there is a variety of methods to fetch the data for that path. We'll use the endpoint get latest value by path as first example.
curl --location 'https://api.kognif.ai/assets/v2/timeseries/LatestValue/Paths?includeNaN=true&convertToStdUnit=true'
\--header 'Ocp-Apim-Subscription-Key: [YOUR OCP-APIM-SUBSCRIPTION-KEY]'
\--header 'Content-Type: application/json'
\--header 'Authorization: ••••••'
\--data '[
"/Fleet/imoXXX/Aux_Engines/1/Generator_Power"
]'
The response contains the latest value sent from the vessel to the cloud, along with metadata such as the unit of the data.
{
"/Fleet/imo9307633/Aux_Engines/1/Generator_Power":
{
"timestamp": "2024-10-31T10:56:54.0000000Z",
"values": [452],
"vectorElementData": [{
"name": "Generator_Power",
"displayName": "Generator Power",
"unitId": "kW",
"displayUnitId": "kW"
}]
}}
Completed!
This is a basic example of using the API.
To learn more about integrating with Vessel Insight and the API, check out the integration guides in the next sections and the API reference pages.