Integrate, analyze, customize and innovate!

The Kyma Online API is an endpoint allowing you to access your ship performance data online and on demand. The ways in which the API is used are entirely up to you; possibilities include custom dashboards and integration with customer ERP systems.

Integrate

Gain easy access to your ship performance data.
Let Kyma handle the hassle of transferring data from vessels to the Kyma-cloud datastore.

Analyze

Use your preferred analysis tools to gain new insights.

Customize

Create custom views that meet your information needs.

Innovate

Combine data from the Kyma API with other data sources and use it to innovate!

TECHNICAL OVERVIEW

Communication protocol and data format

Communication with the API uses the HTTPS protocol. The data is transferred as structured text in the JSON format.

Security

Data communication uses the HTTPS protocol which offers authentication of the API as well as encryption, and protection against man-in-the-middle attacks, eavesdropping and data tampering attempts.

Each API user is provided with a set of security credentials (client id and password). The credentials are required when making requests from the API, so that each user can be identified and authenticated; ensuring that they have access to only their own data. Without the appropriate security credentials, no third-party be able to access the data. If a user should inadvertently reveal their security credentials, it is straightforward to revoke the existing credentials and issue a replacement set.

Data storage

The data behind the API is stored in a secure data center which holds the data for all Kyma’s customers. No customer has direct access to the data center; all access occurs via the API. Direct access to the data center is available only to designated Kyma employees and data center infrastructure personnel.

Technical requirements

The API provides a specific method for one computer system to talk with another. As such, some development effort will be required on the customers part to integrate their existing computer system(s) with the Kyma API. The API has been designed to be generic enough to meet all anticipated customer needs.

The following requirements must be met:

  • The client system must have online access to the API (https://kspoffice.kyma.no/api/v1).
  • The client system must be able to make custom HTTP requests to both send and receive JSON data.

The development of any client system is the customers responsibility. However, Kyma can provide assistance to IT/software developers in the form of technical support and example code.

Limitations

To ensure that all customers receive an optimum service, Kyma may place performance limitations on the API service.

Limitations may include (but not be limited to):

  • Rate limits (restrictions upon the frequency of consecutive requests).
  • Entity limits (restrictions upon the volume of data returned for a single query).

Time zone

Vessels with KSP 8.9 and earlier does not provide data with time-zone information. This means that all timestamps in the query responses are in local vessel time.

AUTHENTICATION

Authorization: Basic <{user_id}:{api_key} | base64>

Each user receives a set of security credentials (a user id and an API key) that are used when authenticating with the API using the ‘Basic’ authentication scheme [RFC2617]. Each HTTP request requires an authorization header, which is the base64 encoded value of user id and api key joined with :

Example

Given user id aladdin@kyma.no and api key open sesame, the authorization header field would be: Authorization: Basic YWxhZGRpbkBreW1hLm5vOm9wZW4gc2VzYW1l

Note:
The user id is the username (email account) for the Kyma Online Portal, while the API key is generated by the company’s super-user on the user edit page.

Vessels

GET /vessels

Gets a list of vessels with basic information.

Example

Url
https://kspoffice.kyma.no/api/v1/vessels
Request body
None.
Response body

[
    {
        "id": 58,
        "name": "Kyma Oslo",
        "imoNumber": 2345678,
        "logDataMinDate": "2012-02-05T21:00:24.677",
        "logDataMaxDate": "2016-09-13T11:59:49.577",
        "trendDataMinDate": "2007-05-21T00:00:00",
        "trendDataMaxDate": "2013-12-20T00:00:00",
        "lastExportDate": "2016-10-05T11:38:00"
    },
    {
        "id": 107,
        "name": "Kyma Bergen",
        "imoNumber": 3456789,
        "logDataMinDate": "2013-05-14T12:00:17.69",
        "logDataMaxDate": "2016-09-13T11:59:46.907",
        "trendDataMinDate": "1999-11-26T00:00:00",
        "trendDataMaxDate": "2016-10-10T00:00:00",
        "lastExportDate": "2016-09-24T12:00:00"
    },
    {
        "id": 110,
        "name": "Kyma Haugesund",
        "imoNumber": 4567890,
        "logDataMinDate": "2013-01-15T15:00:18.803",
        "logDataMaxDate": "2016-09-06T23:02:47.383",
        "trendDataMinDate": "2014-03-27T00:00:00",
        "trendDataMaxDate": "2016-10-08T00:00:00",
        "lastExportDate": "2015-09-24T12:59:00"
    }
]

Gets a list of log variables for a single vessel with basic information about its log data (logging history data). The same list is available under ‘Logging History’ in the Kyma Online web portal.

Log variables

GET /logvariables/find?vesselId={vesselId}

Variables returned for a given vessel are determined by the KSP software on board.

Input

Parameter Description
vesselId the id of the vessel to get log variables for.

Example

Url
https://kspoffice.kyma.no/api/v1/logvariables/find?vesselId=58
Request body
None.
Response body

[
    {
        "id": 3498,
        "name": "Shaft Thrust",
        "validLimitMinimum": -3200,
        "validLimitMaximum": 3200,
        "displayPrecision": 0,
        "unit": {
            "name": "kNewton",
            "caption": "kN"
        },
        "vesselId": 58,
        "logDataMinDate": "2012-02-05T21:00:24.677",
        "logDataMaxDate": "2016-09-13T14:59:56.11"
    },
    {
        "id": 3499,
        "name": "Shaft Torque",
        "validLimitMinimum": -3000,
        "validLimitMaximum": 3000,
        "displayPrecision": 0,
        "unit": {
            "name": "kNm",
            "caption": "kNm"
        },
        "vesselId": 58,
        "logDataMinDate": "2012-02-05T21:00:24.677",
        "logDataMaxDate": "2016-09-13T14:59:56.11"
    },
    {
        "id": 3501,
        "name": "Ship Speed GPS",
        "validLimitMinimum": 0,
        "validLimitMaximum": 30,
        "displayPrecision": 1,
        "unit": {
            "name": "Knots",
            "caption": "knot"
        },
        "vesselId": 58,
        "logDataMinDate": "2012-02-05T21:00:24.677",
        "logDataMaxDate": "2016-09-13T14:59:56.11"
    },
    {
        "id": 3502,
        "name": "Ship Speed Log",
        "validLimitMinimum": 0,
        "validLimitMaximum": 30,
        "displayPrecision": 1,
        "unit": {
            "name": "Knots",
            "caption": "knot"
        },
        "vesselId": 58,
        "logDataMinDate": "2012-02-05T21:00:24.677",
        "logDataMaxDate": "2016-09-13T14:59:56.11"
    }
]

Log data

GET /logdata/find?logVariableId={logVariableId}&granularity={granularity}&fromDate={fromDate}&toDate={toDate}

Gets log data (logging history data) for the specified variable.

All log data values are returned as floating point numbers.

Input

Parameter Description
logVariableId the id of the required log variable
granularity

Can be:

– Raw
– Minute
– QuarterHour
– Hour
– Day

The KSP system onboard typically collects data every 15 seconds and this data is referred to as the Raw data, meaning every logged value available. The other options are averaged values calculated from the raw data.

When selecting the granularity, consider your data requirements and the time span of the query: If, for instance, you wish to analyze a full year of data, then the Raw granularity might be too fine grained since it would yield approximately 2.1 million values. A granularity of Day (365 values) or Hour (8760 values) might be more appropriate. Naturally, a query for 2.1 million values will also take proportionally longer than a query for 365 values.
unitName If supplied, the API will try to convert to the desired unit. Otherwise, the value is returned using the unit defined for this vessel.
fromDate ISO 8601 formatted date/time string giving the start of the query time span (inclusive)
toDate ISO 8601 formatted date/time string giving the end of the query time span (exclusive)
dateTimeFormat The date and time format of the key in the data object. If omitted, the default is “ISO”, which indicates ISO 8601 format.

Possible values:
“ISO” (default): E.g. 2022-05-01T00:00:00
“UnixEpochMs”: Unix time – i.e. time in milliseconds since January 1, 1970 00:00:00 UTC. Example: 1650412800000
format Optional. When the format parameter is used with the value “csv”, the data will be returned as comma separated values

Example

 

Url
https://kspoffice.kyma.no/api/v1/logdata/Find?logVariableId=3499&granularity=Day&fromDate=2016-09-01&toDate=2016-09-13
Request body
None.
Response body

{
        "filter": {
               "logVariableId": 20576,
               "fromDate": "2022-04-19T22:00:00Z",
               "toDate": "2022-05-01T22:00:00Z",
               "unitName": null,
               "granularity": "Day",
               "dateTimeFormat": "ISO"
        },
        "continuationFilter": null,
        "unit": {
               "name": "Meter",
               "caption": "m"
        },
        "data": {
               "2022-04-20T00:00:00": 0.0,
               "2022-04-21T00:00:00": 0.0,
               "2022-04-22T00:00:00": 0.0,
               "2022-04-23T00:00:00": 0.0,
               "2022-04-24T00:00:00": 0.0,
               "2022-04-25T00:00:00": 0.0,
               "2022-04-26T00:00:00": 0.0,
               "2022-04-27T00:00:00": 0.0,
               "2022-04-28T00:00:00": 0.0,
               "2022-04-29T00:00:00": 0.0,
               "2022-04-30T00:00:00": 0.0,
               "2022-05-01T00:00:00": 0.0
        }
}

Response body with dateTimeFormat=” UnixEpochMs”

{
        "filter": {
               "logVariableId": 20576,
               "fromDate": "2022-04-19T22:00:00Z",
               "toDate": "2022-05-01T22:00:00Z",
               "unitName": null,
               "granularity": "Day",
               "dateTimeFormat": "UnixEpochMs"
        },
        "continuationFilter": null,
        "unit": {
               "name": "Meter",
               "caption": "m"
        },
        "data": {
               "1650412800000": 0.0,
               "1650499200000": 0.0,
               "1650585600000": 0.0,
               "1650672000000": 0.0,
               "1650758400000": 0.0,
               "1650844800000": 0.0,
               "1650931200000": 0.0,
               "1651017600000": 0.0,
               "1651104000000": 0.0,
               "1651190400000": 0.0,
               "1651276800000": 0.0,
               "1651363200000": 0.0
        }
}

Format

When the format parameter is used with the value “csv”, the data will be returned as comma separated values

"Time","Draft Aft (m)"
1650412800000,0
1650499200000,0
1650585600000,0
1650672000000,0
1650758400000,0
1650844800000,0
1650931200000,0
1651017600000,0
1651104000000,0
1651190400000,0
1651276800000,0
1651363200000,0

Remarks on response

filter the id of the required log variable
continuationFilter If the original query time span was reduced by the API (due to query time span limitations), the continuationFilter will hold the query parameters that should be executed to get the remaining results.

Continuation Filter

To ensure good API response times, large queries will result in the response being split into multiple data sets using a continuation filter. The following limitations are imposed:

Raw 1 month
Minute 6 months

This means that if a query for a longer time span is submitted, the response will include a continuation filter so that the complete data set can be retrieved in multiple requests. See example of continuation filter below.

Example (with continuation filter)

Url
https://kspoffice.kyma.no/api/v1/logdata/Find?logVariableId=3499&granularity=Raw&fromDate=2016-08-01&toDate=2016-09-13

Request body
None.
Response body

{
    "filter": {
        "logVariableId": 3499,
        "fromDate": "2016-08-01T00:00:00",
        "toDate": "2016-09-01T00:00:00",
        "granularity": "Raw"
    },
    "continuationFilter": {
        "logVariableId": 3499,
        "fromDate": "2016-09-01T00:00:00",
        "toDate": "2016-09-13T00:00:00",
        "granularity": "Raw"
    },
    "unit": {
        "name": "kNm",
        "caption": "kNm"
    },
    "data": {
        "2016-08-01T00:00:29.113": 293.200012,
        "2016-08-01T00:00:44.12": 286.299988,
        "2016-08-01T00:00:59.123": 310.399994,
        "2016-08-01T00:01:14.133": 325.899994,
        "2016-08-01T00:01:29.137": 300.100006,
        "2016-08-01T00:01:44.147": 300.100006,
        "2016-08-01T00:01:59.153": 329.399994,
        ... // + ~170K more values
}

Remarks on response

filter Since the request was for more than one month of raw data, the response is limited and the time span that is actually returned is shown here.
continuationFilter Since the original query time span was reduced by the API, the continuationFilter holds the query parameters that should be executed to get the remaining results.

The next request to get the next batch of data must use the dates in the continuation filter like this:

Url
https://kspoffice.kyma.no/api/v1/logdata/Find?logVariableId=3499&granularity=Raw&fromDate=2016-09-01&toDate=2016-09-13

Keep sending requests with the dates in the continuation filter until the continuation filter is null, to get the complete set of data from the original request.

Log data (batch find)

GET /logdata/BatchFind?logVariableIds={logVariableId1},{logVariableId2}&granularity={granularity}&fromDate={fromDate}&toDate={toDate}

Gets log data (logging history data) for the given variables.

All log data values are returned as floating point numbers.

Input

Parameter Description
logVariableIds The ids (comma separated list) of the log variables to get log data for. A Maximum 10 ids are supported
granularity See Log Data above
fromDate See Log Data above
toDate See Log Data above
unitName A comma-separated list of units. Units can be skipped by using a empty space. See also Log Data above
dateTimeFormat See Log Data above
format Optional. Can be “csv”. See Log Data above

Query time span limitations

See Log Data above

Example

Url
https://kspoffice.kyma.no/api/v1/logdata/BatchFind?logVariableIds=3499,3501&granularity=Day&fromDate=2016-09-01&toDate=2016-09-13
Request body
None.
Response body

{
      "filter": {
            "logVariableIds": [
                  19739,
                  19721
            ],
            "fromDate": "2022-04-19T22:00:00Z",
            "toDate": "2022-05-02T22:00:00Z",
            "unitNames": null,
            "granularity": "Day",
            "dateTimeFormat": "ISO"
      },
      "continuationFilter": null,
      "units": [
            {
                  "name": "kNm",
                  "caption": "kNm"
            },
            {
                  "name": "Kg/Hr",
                  "caption": "kg/hr"
            }
      ],
      "data": {
            "2022-04-20T00:00:00": [-2.031846869633607,1.5372499943385445],
            "2022-04-21T00:00:00": [-7.256538147631024,1.5325075667727482],
            "2022-04-22T00:00:00": [227.14780519650044,3.3234012357953777],
            "2022-04-23T00:00:00": [743.9870026155879,6.998500871382746],
            "2022-04-24T00:00:00": [731.2278694251907,6.777454491517785],
            "2022-04-25T00:00:00": [448.73439210507515,4.755087743145718],
            "2022-04-26T00:00:00": [37.90751083888146,1.5346087148596397],
            "2022-04-27T00:00:00": [34.98773188087458,1.5367099203039064],
            "2022-04-28T00:00:00": [23.9222350617223,1.525702039484771],
            "2022-04-29T00:00:00": [38.13412246744775,1.5347613056616132],
            "2022-04-30T00:00:00": [235.68699224757467,3.1464571940471637],
            "2022-05-01T00:00:00": [638.2206964408835,6.339327026777352],
            "2022-05-02T00:00:00": [725.8151125258737,6.5473767890690619]
      }
}

Format

When the format parameter is used with the value “csv”, the data will be returned as comma separated values

"Time","ME Shaft Torque (kNm)","Emissions SO2 (kg/hr)"
2022-04-20T00:00:00.0000000,-2.03184686963361,1.53724999433854
2022-04-21T00:00:00.0000000,-7.25653814763102,1.53250756677275
2022-04-22T00:00:00.0000000,227.1478051965,3.32340123579538
2022-04-23T00:00:00.0000000,743.987002615588,6.99850087138275
2022-04-24T00:00:00.0000000,731.227869425191,6.77745449151779
2022-04-25T00:00:00.0000000,448.734392105075,4.75508774314572
2022-04-26T00:00:00.0000000,37.9075108388815,1.53460871485964
2022-04-27T00:00:00.0000000,34.9877318808746,1.53670992030391
2022-04-28T00:00:00.0000000,23.9222350617223,1.52570203948477
2022-04-29T00:00:00.0000000,38.1341224674478,1.53476130566161
2022-04-30T00:00:00.0000000,235.686992247575,3.14645719404716
2022-05-01T00:00:00.0000000,638.220696440883,6.33932702677735
2022-05-02T00:00:00.0000000,725.815112525874,6.54737678906906

Remarks on response

Take particular care with the ordering of the logVariableIds field: The units and data in the response will be in the same order. i.e. In the example above, the second unit Kg/Hr and the second value 32.308885075501721 correspond to the second requested variable id 3501. It is therefore important that the client application matches variables, units and data correctly.

Your partner in ship
performance monitoring

Contact us