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).
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
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}
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.
Input
Parameter | Description |
---|---|
logVariableId | the id of the required log variable |
granularity | Can be: – Raw 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. |
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) |
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": 3499, "fromDate": "2016-09-01T00:00:00", "toDate": "2016-09-13T00:00:00", "granularity": "Day" }, "continuationFilter": null, "unit": { "name": "kNm", "caption": "kNm" }, "data": { "2016-09-01T00:00:00": 2463.4286963497857, "2016-09-02T00:00:00": 2408.1803276441228, "2016-09-03T00:00:00": 2122.8905488472487, "2016-09-04T00:00:00": 2116.2124188225689, "2016-09-05T00:00:00": 2217.9016160586225, "2016-09-06T00:00:00": 706.60062184242372, "2016-09-07T00:00:00": 818.148051854473, "2016-09-08T00:00:00": 1646.2477744173952, "2016-09-09T00:00:00": 1286.1039910525938, "2016-09-10T00:00:00": 358.67164813017638, "2016-09-11T00:00:00": 968.20380937224127, "2016-09-12T00:00:00": 1065.7295540954956 } }
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.
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 |
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": [3499,3501], "fromDate": "2016-09-01T00:00:00", "toDate": "2016-09-13T00:00:00", "granularity": "Day" }, "continuationFilter": null, "units": [ { "name": "kNm", "caption": "kNm" }, { "name": "Kg/Hr", "caption": "kg/hr" } ], "data": { "2016-09-01T00:00:00": [2463.4286963497857, 32.308885075501721], "2016-09-02T00:00:00": [2408.1803276441228, 33.292893472405979], "2016-09-03T00:00:00": [2122.8905488472487, 32.1528548679246171], "2016-09-04T00:00:00": [2116.2124188225689, 31.552885962422339], "2016-09-05T00:00:00": [2217.9016160586225, 31.4895685777179839], "2016-09-06T00:00:00": [706.60062184242372, 32.7113501904682611], "2016-09-07T00:00:00": [818.148051854473, 33.256489236202981], "2016-09-08T00:00:00": [1646.2477744173952, 32.7122071428511951], "2016-09-09T00:00:00": [1286.1039910525938, 32.273755518875433], "2016-09-10T00:00:00": [358.67164813017638, 31.1768926132075972], "2016-09-11T00:00:00": [968.20380937224127, 31.5097090124663666], "2016-09-12T00:00:00": [1065.7295540954956, 31.5238385093497744] } }
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.