Overview

The purpose of this guide is to walk through the process of using the Vessel Insight API to retrieve vessel data.

There are three steps involved in using the API:

1. Subscribe to the API and retrieve a subscription key

2. Retrieve an OpenIDConnect token for authentication

3. Call the API using the authentication token and API subscription key

Subscribe to the API and Retrieve API keys

All calls to the API must include an API subscription key. This key provides the necessary authorization to call the API. This key can be acquired by following the steps below:

• Access the developer portal by following this link, https://developer.kognif.ai/ and sign up to get user credentials to log on.

• You will receive an email and are requested to confirm your user credentials.

When you first log in, you won’t have any subscription. In order to get a subscription, do the following:

• Click on the “Data Services”, provide a meaningful name for the subscription in the box and click on ”Subscribe”:

Next, a new page (User profile) will open as shown below:

• On this page you will see information regarding your account and subscription. A notification will be sent to the administrator for approval before the key is activated.

• Upon activation of your key you will receive a confirmation email. Your subscription is now active.

• Reveal your subscription key by clicking on the ”Show” link next to ”Primary key”.

• Use this key in the Http header of each call to the API in the field: Ocp-Apim-Subscription-Key.

NOTE: Keep this key very secure as it is unique for your subscription.

Authenticate with the API

In order to authenticate and retrieve a valid authorization token to use in API calls you need to have the following information at hand:

1. ClientID

2. TenantID

3. ClientSecret

4. Kognifai Resource ID

Information on how to retrieve 1,2 and 3, as well as how to get an authorization token, can be found in https://developer.kognif.ai/identity

The Kognifai resource ID will be provided to you in your welcome email after activating the subscription.

NOTE: Keep the ClientSecret very secure, as this is the password used to authenticate to the API. Use only in confidential applications where the secret can be kept private, do NOT use it in public applications where secrets cannot be kept e.g. Single Page Applications (SPA).

Using the Vessel Insight API

This section describes how to use the Vessel Insight API.

Consider the following scenario: “I should be able to get the most recent Speed through water from my vessel called Simrad Echo.”

In this scenario we will use two endpoints from the Vessel Insight API.

First, a quick introduction to the build-up of the API.

Vessel Insight Common Asset Structure

The Vessel Insight Common Asset Structure is the key to accessing the timeseries data, and data for all vessels are organized according to this structure.

In the picture below we can see an example of parts of this structure:

Note the node in the structure called “STW”; this contains the data we are looking for in our example, the “Speed Through Water”. To provide the absolute reference to this node we would use this as the identifier in the API calls: “/Fleet/SimradEcho/Bridge/Navigation/STW”. This is also referred to as “Node Path” (/Fleet is always the top-level node, which is not shown in the example structure for readability).

To access the vessel data, we first need to use the node path to retrieve the identifier of the timeseries. This is, in turn, used to retrieve the data.

The relationship between the Common Asset Structure and the Timeseries can be explained like shown in the picture below:

From the picture we can see that the node “STW” holds a reference to the corresponding Timeseries with id of 12. The Timeseries can be referenced by 0 or many nodes.

Some asset structure concepts used in the API

Each element in the asset structure is called a node.

Nodes can have child nodes, which are called edges.

Nodes can be of different types, “TimeSeries” is the type typically used.

A node path always starts with /Fleet/<vesselname>/<asset type>/<asset>/…

Getting the data

Getting the data is done in two steps:

1. GetFilteredNodes: we will use this endpoint to find the timeseries identifier of the “Speed through water” node. Input to this endpoint is:

   • NodeType: The type of node that we are looking for. In this case it is “TimeSeries”

   • maxLevelOfEdge: The maximum depth level of node to return. We will use value 1

   • nodePath: This is the node path in the Vessel Insight asset structure. We will use value “/Fleet/SimradEcho/Bridge/Navigation/STW”

   We will get the timeseries id from the output.

2. LatestValue: Get the latest value from a timeseries id: we will use this endpoint to get the latest Speed through water using the timeseries id. Input to this endpoint is

   • TimeseriesId: The id from the previous API call.

Code

Example code can be found on GitHub: https://github.com/kognifai/API_CLient_Examples