Kyma API Documentation
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 us 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).
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:
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 dataTimeFormat=” 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” |
||
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.
Contact support
Not able to find what you are looking for? Do you require technical support? Please feel free to contact our Technical Support Department.