How to run this?

Go here to instantly run all code below inside of your browser.

Use case

In this starter use case, we will showcase the fundamentals of the Toqua API and introduce some of the terminology used in our documentation. To get the most out of this tutorial, you should have some familiarity with Python.

We will simulate the performance of a ship in a single weather condition, for a single speed.

Authorize

Let's first make sure we're authorized to use the API. Fill in your API key and run the following code.

If everything is alright, you should see a list of ships.

API_KEY = "your-api-key"

import json
import requests

API_URL = "https://api.toqua.ai"

url = "https://api.toqua.ai/ships/"
headers = {"accept": "application/json", "X-API-Key": API_KEY}
response = requests.get(url, headers=headers)

print(json.dumps(response.json(), indent=2))

[
  {
    "name": "Trial Vessel",
    "imo_number": 9999999,
    "type": "Tanker",
    "class": null,
    "country": "SC",
    "build_year": 2015,
    "shipyard": "Toqua Shipyard",
    "dwt": 220000.0,
    "beam": 55.0,
    "loa": 300.0,
    "mcr": null,
    "max_rpm": null,
    "uuid": "eycrYbrzJNsJecGqKraUCn"
  }
]

Fill in the IMO number of the ship you want to analyze.

IMO_NUMBER = 9999999

Conditioning parameters

The conditioning parameters are the factors that influence the relation between the ship's primary operational parameters. These can be provided at the input and will influence the value of the predicted primary operational parameters. We can model the impact of any of the following conditions:

Weather conditions

Wind speed and direction
Wave height and direction
Current speed and direction
Sea surface salinity
Sea surface temperature

Operational conditions

Mean/average draft
Trim
Ship heading
Fuel specific energy / Lower Calorific Value

Let's define these conditions.

wind_speed = 6          # [m/s]
wind_direction = 180    # [degrees]
wave_height = 2         # [m]
wave_direction = 90     # [degrees]
current_speed = 0.5     # [m/s]
current_direction = 0   # [degrees]
mean_draft = 20         # [m]
trim = -1               # [m]
ship_heading = 0        # [degrees]
fuel_specific_energy  = 41.5 # [MJ/kg]

The entrypoint

Now that we have our conditioning parameters, let's specify our entrypoint.

The entrypoint can be any of the below parameters. Given exactly one of these (the entrypoint), the other parameters can be predicted.

Speed Over Ground (sog)
Speed Through Water (stw)
Main Engine RPM (me_rpm)
Main Engine Shaft Power (me_power)
Main Engine Fuel Consumption (me_fo_consumption).

We want to predict the amount of fuel the ship will consume when sailing at a Speed Over Ground of 13 knots in the conditions we described above.

Thus, our entrypoint will be the sog parameter.

sog = 13

Define the API input

The Toqua API expects the model input to look like this:

{
     "date": "...",
     "data": {
          "sog": [...],
          "draft_avg": [...],
          "trim": [...],
          "wave_direction": [...],
          "wave_height": [...],
          "wave_period": [...],
          "current_speed": [...],
          "current_direction": [...],
          "wind_direction": [...],
          "wind_speed": [...],
          "ship_heading": [...],
          "fuel_specific_energy": [...]
     }
}

For the full specification, consult our API reference.

Let's create such an input from the condition and entrypoint we specified. For this use case, we will ignore the date parameter.

Note that all parameters have to be provided as lists of values.

api_input = {
    "data": {
        "sog": [sog],
        "wave_direction": [wave_direction],
        "wave_height": [wave_height],
        "wind_direction": [wind_direction],
        "wind_speed": [wind_speed],
        "current_direction": [current_direction],
        "current_speed": [current_speed],
        "draft_avg": [mean_draft],
        "trim": [trim],
        "fuel_specific_energy": [fuel_specific_energy]
    }
}

Query the API

Now that our input data is in the correct format, let's create a simple function to query the model API and call it.

def query_api(imo_number, payload):
    url = f"https://api.toqua.ai/ships/{imo_number}/models/latest/predict"
    headers = {
        "accept": "application/json",
        "content-type": "application/json",
        "X-API-Key": API_KEY,
    }
    response = requests.post(url, json=payload, headers=headers)
    return response

If everything went fine, the code below should print Status Code: 200.

response = query_api(IMO_NUMBER, api_input)
print("Status Code: ", response.status_code)

Status Code:  200

Let's look at the values that were predicted by the model for the conditions we provided.

print(response.json())

{'sog': [13.0], 'stw': [13.97192], 'me_rpm': [44.913151911934605], 'me_power': [11051.700231111769], 'me_fo_consumption': [46.458430017045956], 'me_fo_emission': [147.29645236904418]}

For the conditions we specified the ship will:

sail at a STW of 14 knots
require a main engine RPM of 45
require a main engine power output of 11051 kW
consume fuel at a rate of 46 mt/day
emit CO2 at a rate of 147 mt/day