To quickly get you up to speed on how to use our API to query ship kernels we will predict a ship's consumption in two different conditions.

We will use Python, but any other language works fine. You can also follow along using nothing but your browser using our API Reference.

Example

We simulate the effect of a ship sailing at 12 knots STW in two conditions: once with head waves of 2m and once with waves of 3m. The conditions are as follows:

📘

The STW parameter here is called the entrypoint parameter. The others are conditioning parameters.

Step 0: Setup

Create a new script predict.py and enter the following. Replace <your_api_key> by the API key provided to you.

import requests
import json

API_URL = "https://api.toqua.ai"
API_KEY = "<your_api_key>"

Step 1: Authentication

We use the X-API-Key header for authentication.

headers = {"X-API-Key": API_KEY}
response = requests.get(API_URL + "/ships", headers=headers)
print(response)

If you run python prediction.py you should see <Response [200]>. Indeed, if you are authenticated you should have access to the /ships endpoint.

Step 2: Create the model input

The input data is formed as follows:

data_json = {
  "data": {
      "stw" : [12, 12],
      "ship_heading": [0, 0],
      "draft_avg": [21, 21],
      "wind_speed": [5, 5],
      "wind_direction": [0, 0],
      "wave_height": [2, 3],
      "wave_direction": [0, 0],
      "current_speed": [0, 0],
      "current_direction": [0, 0],
    }
}

As we want to simulate two different conditions, each array has a length of two, one index for each condition. In the first condition, we set the wave height to 2m. In the second condition we set it to 3m. Note the correspondence to our conditions table above.

As our entrypoint is STW, we provide the "stw" key. If we wanted to start from the ME Power, we would replace this with "me_power". The other possible parameters are "sog", "me_rpm" and "me_fo_consumption".
Only one of these parameters should be provided. In case more are provided, only the first will be used.

Step 3: Query the model

The model can be queried using a POST request to api.toqua.ai/ships/{ship_imo}/models/latest/predict.
Replace <your_ship_imo> below by the ship IMO number.

ship_imo = "<your_ship_imo>"

response = requests.post(
    API_URL + "/ships/" + ship_imo + "/models/latest/predict",
    json=data_json,
    headers=headers,
)
response_dict = response.json()
print(json.dumps(response_dict, indent=4))

Note how the data should be wrapped in another dictionary with a data key. The output should looks as follows:

{
  "sog": [
    12,
    12
  ],
  "stw": [
    12,
    12
  ],
  "me_rpm": [
    45.11625719161,
    47.82748878475
  ],
  "me_power": [
    9543.2361328125,
    11313.909667968
  ],
  "me_fo_consumption": [
    41.094958795256,
    48.577683912423
  ],
  "me_fo_emission": [
    128.77105338493,
    152.21817253958
  ]
}

From this output, we can see that the ship consumes 41.1 t/day for waves of 2m and 48.6 t/day for waves of 3m.