Dark mode
/v2/cp-performance.json (Simulation)
POST
/v2/cp-performance.json
CP Simulation
Recalculate the CP performance result for a specific voyage segment
using hypothetical CP conditions — useful for "what-if" comparisons
(e.g. "What if the CP speed was 11.5 kts instead of 12.0 kts?", "What if the good weather threshold was Bft 5?").
Up to 3 patterns can be compared in a single request. Each pattern represents
a different set of hypothetical CP conditions. Only the fields you want to override
need to be specified — all other values are automatically copied from the original charter party.
How to Use
Step 1 — Get the audit_id
Call GET /v2/cp-performance.json first. Each voyage in the response has an audit_id
(e.g. "sid20250101_000001"). Use this ID to specify which voyage to simulate.
Step 2 — Choose a segment (seg_id)
A voyage may have multiple segments (e.g. laden leg + ballast leg).
Specify seg_id: "1", "2", etc. If omitted, segment "1" is used by default.
Step 3 — Define simulation patterns (1–3)
Each pattern is a named scenario. Specify only what you want to change:
| Field | What it overrides | Notes |
|---|---|---|
name |
Pattern label in results | Required |
cp.speed_kts |
Warranted speed (kts) | Basis for time damage calculation |
cp.fo_mt_day |
Warranted FO consumption (MT/day) | Basis for FO overconsumption calculation |
cp.do_mt_day |
Warranted DO consumption (MT/day) | Basis for DO overconsumption calculation |
allowance.speed |
Speed tolerance (kts) | Damage applies when perf_speed < cp_speed − allowance |
allowance.fuel_pct |
Fuel tolerance (%) | Mutually exclusive with fuel_mt_day |
allowance.fuel_mt_day |
Fuel tolerance (MT/day) | Mutually exclusive with fuel_pct |
good_weather.wind_bf |
Beaufort threshold for good weather | Mutually exclusive with wind_speed |
good_weather.wind_speed |
Wind speed threshold (m/s) | Mutually exclusive with wind_bf |
good_weather.sig_wave_m |
Significant wave height threshold (m) | e.g. 2.0 = up to 2 m is good weather |
good_weather.current |
Current inclusion mode | "all" = include / "exclude" = ignore / "negate" = reverse |
damage_period |
Period used for damage assessment | "whole" = entire voyage / "gw" = good weather only |
Minimal request example
{
"audit_id": "sid20250101_000001",
"seg_id": "1",
"patterns": [
{
"name": "Lower CP speed",
"cp": { "speed_kts": 11.5 }
}
]
}
Response Fields Explained
The response returns one results[] entry per pattern, each containing:
cp — Effective CP conditions used in the simulation
Shows the actual values applied (original values for fields not overridden).
| Field | Description | Unit |
|---|---|---|
speed_kts |
Warranted speed used for damage calculation | kts |
fo_mt_day |
Warranted FO consumption | MT/day |
do_mt_day |
Warranted DO consumption | MT/day |
damage_assessment — Damage result under this pattern
| Field | Sign | Meaning |
|---|---|---|
time_lost_hrs |
positive | Time lost by vessel (owner's burden) |
time_lost_hrs |
negative | Time gained (owner's saving) |
fo_over_mt |
positive | FO overconsumption (owner's burden) |
fo_over_mt |
negative | FO underconsumption (owner's saving) |
do_over_mt |
positive | DO overconsumption |
performance.entire — Full voyage period stats
| Field | Description | Unit |
|---|---|---|
distance_nm |
Total distance sailed | NM |
time_hrs |
Total elapsed time | h |
avg_speed_kts |
Average speed over ground | kts |
weather_factor_kts |
Speed impact from weather (negative = hindrance) | kts |
current_factor_kts |
Speed impact from ocean current (positive = favorable) | kts |
fo_mt |
Total FO consumed | MT |
do_mt |
Total DO consumed | MT |
performance.good_weather — Good weather period stats
Same fields as entire, plus:
| Field | Description | Unit |
|---|---|---|
performance_speed_kts |
Speed corrected for weather & current — compared against CP warranted speed | kts |
Performance speed = avg_speed_kts − weather_factor − current_factor.
This is the key metric for determining whether damage time applies.
co2_emission — CO2 estimate (IMO MEPC.364(79))
| Field | Description | Unit |
|---|---|---|
co2_fo_mt |
CO2 from FO = fo_mt × 3.1144 | t-CO2 |
co2_do_mt |
CO2 from DO = do_mt × 3.206 | t-CO2 |
Parameters
Header Parameters
Authorization*
"WniWebApi " + Token ID
Typestring
RequiredRequest Body
JSON
{
"audit_id": "sid20250101_000010",
"seg_id": "1",
"patterns": [
{
"name": "Pattern A",
"cp": {
"speed_kts": 11.5,
"fo_mt_day": 15,
"do_mt_day": 0.1
},
"allowance": {
"speed": 0.5,
"fuel_pct": 5,
"fuel_mt_day": 0
},
"good_weather": {
"wind_bf": 4,
"wind_speed": 0,
"sig_wave_m": 2,
"current": "string",
"negate_current": false
},
"damage_period": "string"
}
]
}
Responses
Simulation completed successfully
application/json
JSON
{
"audit_id": "sid20250101_000010",
"seg_id": "1",
"results": [
{
"name": "Pattern A",
"cp": {
"speed_kts": 11.5,
"fo_mt_day": 15,
"do_mt_day": 0.1
},
"damage_assessment": {
"time_lost_hrs": -2.3,
"fo_over_mt": -1.8,
"do_over_mt": 0
},
"performance": {
"entire": {
"distance_nm": 725,
"time_hrs": 58.5,
"avg_speed_kts": 12.39,
"weather_factor_kts": -0.3,
"current_factor_kts": 0.12,
"fo_mt": 22.9,
"do_mt": 11.33,
"daily_fo_mt": 9.39,
"daily_do_mt": 4.65
},
"good_weather": {
"distance_nm": 111,
"time_hrs": 8.8,
"avg_speed_kts": 12.61,
"performance_speed_kts": 12.61,
"weather_factor_kts": 0,
"current_factor_kts": 1.06,
"fo_mt": 0,
"do_mt": 5.16,
"daily_fo_mt": 0,
"daily_do_mt": 14.07
}
},
"co2_emission": {
"co2_fo_mt": 71.32,
"co2_do_mt": 36.33
}
}
]
}