To create data-driven models like Ship Kernels, data is required to create the models.
Below you may find which data sources and variables are required, and how to upload these to our platform.

Once uploaded, we will continuously process, merge and analyze the data to determine whether the quality is sufficient for modeling. The results of these analyses will be made available through our API. See the next step, Data Monitoring.

Data Requirements

Data Sources

Different sources can be used to build a model:

• Sensor data
• Noon report data
• Design data
• Any combination of the above

Only one of the above sources is minimally required to create a model. Still, we recommend sharing as many data sources as available, as it will increase accuracy and usability.

Next, we need to know about any events that might impact the performance of the ship (hull cleanings, propeller cleanings, dry-dockings, ESDs, ...). This ensures the models can capture the changes in performance due to these events.

Lastly, weather data may be provided but is not required. If not provided, we will use our own sources.

Operational data (sensor and/or noon reports)

Allowed variables

The table below shows all supported variables. Variables marked as 'essential' are minimally required to create data-driven models. Sharing non-essential variables will lead to richer and more accurate models and is highly recommended.
These variables can be sourced from sensor data and/or noon reports.

If possible, we recommend sharing both sensor and noon reports for all variables as this increases the reliability of the model.

Sensor sampling rate

We recommend a sampling rate of 1 sample / 5min. Nevertheless, other frequencies (1/sec to 1/hour) are supported too. This doesn't mean that data should be uploaded at this same sampling rate. Preferably, data is uploaded in batches.

Amount of data

Technically sound models can already be made with as little as 1 week of historical data in some cases, but a safe lower threshold would be 3 months of data. Ideally multiple years of historical operational data is shared. This increases model accuracy and provides more conditions to evaluate the model on.

Frequency of sharing

We recommend:

• Initially, uploading a one-off historical batch containing all available historical data.
• Afterwards, periodically upload a new batch once a week as new data becomes available.

The frequency of once a week is merely a suggestion, other frequencies are also possible.

Design data

Apart from operational data (sensor data and/or noon reports), design data can also be shared. This allows to create models in case no or insufficient operational data is available. It also helps improve data-driven models by providing more vessel specifics the model can learn from. It is not a must to share design data, as long as sufficient operational data (sensor data and/or noon report data) is available. It is however highly recommended, as it will improve the data-driven models, and create a fallback option in case of serious data issues or unavailability.

Minimum required variables

Calm water curve: sourced from sea trials, model tests, CFD, or other.

Main Engine Shop Test

Uploading Data

To make a request to our API you must be authorized. Please see Authorization.

Adding a ship

Query the Ships list endpoint to view all ships you have access to.

A new ship can be added through the Add a new ship endpoint. Only name and IMO number are strictly required. MCR and Max RPM should be added to limit the model to the operational range of the vessel.

Data Sources

Each data source has its own API endpoint:

• Sensor data
• Noon reports
• Event data
• Weather data
• Design data (sea trial, shop tests, ...): not yet supported through the API. Only supported through manual transfer (e.g. via email).

Data can be uploaded by sending a POST request to these endpoints. The details of what such a request should look like and the exact unit each parameter should have is documented in each endpoint. For clarity, an example is also given further below.

Data Format

For uploading data, we impose a few format constraints.

• Each sample should at least have a timestamp in ISO8601 format.
• Each variable should have the correct data type, as defined in the endpoint reference. For example, text won't be accepted where a number should be.
• Variables may be missing or null.

Example

As a manner of example, please find an example JSON file containing two rows of sensor data below, and an example Python script that uploads this data through the API.

{
  "datetime_end": [
    "2022-08-02T09:21:24.0000000+00:00",
    "2022-08-02T09:26:24.0000000+00:00"
  ],
  "lat": [
    24.69452,
    24.60452
  ],
  "lng": [
    128.10483,
    128.20483
  ],
  "sog": [
    14.1,
    15
  ],
  "stw": [
    14.1,
    15
  ],
  "me_power": [
    20000,
    20010.5
  ],
  "me_rpm": [
    60,
    61
  ],
  "me_fo_consumption": [
    25.3,
    26
  ],
  "ship_heading": [
    222.3,
    30.6
  ],
  "draft_avg": [
    21.1,
    21
  ],
  "trim": [
    -0.15,
    -0.1
  ],
  "sea_depth": [
    200.5,
    30.1
  ]
}

import requests

url = "https://api.toqua.ai/ships/ship_uuid_or_imo/data/sensors"

payload = {
    "datetime_end": ["2022-08-02T09:21:24.0000000+00:00", "2022-08-02T09:26:24.0000000+00:00"],
    "lat": [24.69452, 24.60452],
    "lng": [128.10483, 128.20483],
    "sog": [14.1, 15],
    "stw": [14.1, 15],
    "me_power": [20000, 20010.5],
    "me_rpm": [60, 61],
    "me_fo_consumption": [25.3, 26],
    "ship_heading": [222.3, 30.6],
    "draft_avg": [21.1, 21],
    "trim": [-0.15, -0.1],
    "sea_depth": [200.5, 30.1]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "X-API-Key": "your_api_key"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

In tabular form, the above JSON would look as follows:

Correcting Data

Data can be corrected by re-uploading samples with the exact same timestamp. We will always use the values of the latest uploaded sample.

In case erroneous timestamps were uploaded, contact us to fix the issue.