Vessel Performance Model API (1.274)

Using this API, customers can submit vessel performance models to ABB. These models can then be used to perform route calculations for the specific vessel via the ABB Vessel Routing API.

Performance model creation and updates are processed asynchronously. When a model is submitted, it is queued for processing. Use the Get performance model status endpoint to track progress.

Model Lifecycle

1. Submit — Upload model configuration and STW data via POST or PUT
2. Pending — Model is queued for processing (returned immediately as 202 Accepted). Processing typically completes within a minute but may take longer for large STW files.
3. Active — Processing succeeded; model is available for usage (e.g., Vessel Routing API), search, download, and testing
4. Rejected — Processing failed; check the status endpoint for the rejection reason, then use the Update performance model endpoint with the existing modelId to correct and resubmit
5. Inactive — A previously active revision that has been superseded by a newer active revision

A performance model defines how a vessel behaves under varying speeds and environmental conditions. It consists of:

• sicw — Speed in Calm Water: the vessel's reference speed range under ideal conditions, used as the primary axis. Ideally this should cover calm water speed range upto 100% MCR.
• domains — Ordered environmental condition dimensions (wind, waves, swell). See list of available domains below.
• calmWaterPerformanceCurves — ME consumption, MCR & RPM curves as function of SICW (indicating calm water performance of the vessel).
• otherFuelConsumption — Should capture all non ME related consumption that are dependent on time or speed. User can provide fixed consumption value per day or speed dependent consumption (for example to account for high aux engine consumption at low engine load in scenarios when the auxiliary blower kicks in to deliver fresh air to the main engine).
• stw (file) — Speed Through Water values across the full SICW × domain grid.
• metadata — Vessel identification and physical characteristics (IMO number, name, dimensions, draft).

Model Assumptions

• Wind speed domain represents true wind speed (not relative to the vessel)
• Wind and wave directions are true ship-fixed directions relative to heading: 0° coming from bow, 180° coming from stern.
• Ocean current effects are applied after STW lookup to calculate Speed Over Ground (SOG).
• It is currently not possible to include the impact of water density and sea temperature in the performance models. These weather domains are not available for now.

Multiple Models per Vessel

A single IMO number can have multiple active performance models (e.g., for various drafts). In the future, SPOS captains will be able to fetch all active models for a vessel and select the one to use for their voyage. To avoid confusion, ensure that each vessel has only a small number of active models and that each model has a clear, human-readable description so captains can easily identify the right one.

SICW Configuration

You can provide a model for just 1 SICW which is sufficient for doing instructed speed routing (the SICW in route request should be the same as SICW for which the model is provided), or models with an SICW range which is needed for variable speed / optimal speed routing (SICW range in route request should be a subset of the SICW range for which the model is provided).

Recommended range: Vessel's set speed at 10% MCR to the vessel's set speed at 100% MCR. Atleast cover the full SICW range in which the crew is willing to operate in.

Examples:

• Sample range 1: { min: 0, max: 14, step: 1 } → 15 steps (0, 1, 2, …, 14 kn)
• Sample range 2: { min: 0, max: 20, step: 2 } → 11 steps (0, 2, 4, …, 20 kn)
• Sample range 3: { min: 14, max: 14, step: 0 } → 1 step (14 kn only)

Other Fuel Consumption Configuration

Single-SICW models (sicw.min = sicw.max): provide exactly 1 entry where speedFrom = speedTo = sicw.min = sicw.max.

Multi-SICW models: provide one or more contiguous entries that together span the full SICW range:

• The first entry's speedFrom must equal sicw.min
• The last entry's speedTo must equal sicw.max
• Consecutive entries must share the same boundary — each entry's speedTo must equal the next entry's speedFrom (when sorted by speedFrom)

Validation rules:

• speedFrom must be ≥ sicw.min
• speedTo must be ≤ sicw.max
• Multi-SICW: speedFrom must be < speedTo
• Multi-SICW: entries must cover the full SICW range — first speedFrom = sicw.min, last speedTo = sicw.max
• Multi-SICW: entries must be contiguous — each entry's speedTo must equal the next entry's speedFrom (sorted by speedFrom)
• Single-SICW: speedFrom must be = speedTo, and array must have exactly 1 entry

✅Example 1 — Single-SICW (sicw.min = sicw.max = 14):

{ speedFrom: 14, speedTo: 14, otherFuel: 2.0 }

✅Example 2 — Multi-SICW, two contiguous entries (sicw.min = 1, sicw.max = 2):

{ speedFrom: 1, speedTo: 1.5, otherFuel: 2.5 }
{ speedFrom: 1.5, speedTo: 2, otherFuel: 3.0 }

❌ Example 3 — Invalid: gap between entries (sicw.min = 1, sicw.max = 2):

{ speedFrom: 1, speedTo: 1.5, otherFuel: 2.5 }
{ speedFrom: 1.6, speedTo: 2, otherFuel: 3.0 }

Domains Reference

WIND_SPEED

True wind speed domain - the speed of wind at 10 m above sea level, observed from a fixed reference frame (not relative to the vessel).

Recommended range: 0-60 kn in steps of 10 kn

Note for WASP vessels: Finer steps may be needed

WIND_WAVE_DIRECTION

Wind and wind-sea direction domain - ship-fixed directions, coming from and according to the nautical convention (0° = head wind/waves).

Recommended range: 0-180° in steps of 30°

Due to port/starboard symmetry assumed by the model, directions only span 0°-180°.

Note for WASP vessels: Finer direction steps may improve accuracy.

WAVE_HEIGHT

Significant wave height of wind sea domain, in meters.

Recommended range: 0-12 m in steps of 1 m

WAVE_PERIOD

Mean absolute wave period of wind sea (Tmm10) domain, in seconds.

This model requires Tm-1,0 (also written as Tmm10, T_{m-1,0}, or the "wave energy period").

Recommended range: 4-16 s in steps of 3 s (giving 5 points: 4, 7, 10, 13, 16 s)

SWELL_HEIGHT

Significant wave height of swell domain, in meters.

Recommended range: 0-12 m in steps of 1 m

SWELL_DIRECTION

Swell direction domain - ship-fixed directions, coming from and according to the nautical convention (0° = head wind/waves).

Recommended range: 0-180° in steps of 30°

SWELL_PERIOD

Mean absolute wave period of swell (Tmm10) domain, in seconds.

Use the mean wave energy period Tm-1,0 (also written as Tmm10).

Recommended range: 4-16 s in steps of 3 s

TOTAL_WAVE_HEIGHT

Total significant wave height domain - the combined significant height of all wave components (wind waves + swell), representing the overall sea state.

Recommended range: 0-12 m in steps of 1 m

TOTAL_WAVE_DIRECTION

Total wave direction domain - the dominant direction of the combined wave field (wind waves + swell), relative to vessel heading. 0° means waves from the bow; 180° means from the stern.

Recommended range: 0-180° in steps of 30°

Note
Recommended ranges and steps are guidelines based on research done by ABB for typical vessels. Adjust them to minimize error between your original model results and the results from the testing endpoint. Changing ranges and steps for weather domains can significantly increase STW file size — ensure it stays under 150 MB.

STW Configuration

STW is a plain text file with one numeric value per line, mapping each sicw × domains grid point to the resulting Speed Through Water.

The total number of required STW values is the product of all step counts:

total = sicw_steps × domain[0]_steps × domain[1]_steps × ... × domain[N]_steps

Step count example:

• sicw: min=8, max=16, step=4 → 3 steps
• domains[0] (WIND_SPEED): min=0, max=60, step=30 → 3 steps
• domains[1] (WIND_WAVE_DIRECTION): min=0, max=180, step=90 → 3 steps
• Total STW values: 3 × 3 × 3 = 27

STW content example (27 lines):

11
11.8
11.6
11.7
11.5
11.3
11.4
11.2
11
13
12.8
12.6
12.7
12.5
12.3
12.4
12.2
12
14
13.8
13.6
13.7
13.5
13.3
13.4
13.2
13

Rule	Detail
Range	-5 to 50 knots (inclusive)
Decimal places	2 decimal places or fewer recommended. Additional decimals are rounded when the model is used
Empty lines	Not allowed — every line must contain a value
Accepted MIME types	text/plain or application/octet-stream
Compression	Gzip supported — detected automatically
Max values	25,000,000
Max file size	150 MB

Values must follow the nested loop order: sicw (outer) → domains[0] → ... → domains[N] (inner)

Validation errors are grouped by type and reported with line numbers, e.g.: Lines 1-10: Value exceeds maximum (50 knots), Line 15: Invalid speed value 'abc'

Model ID Format

Every model is assigned a unique identifier with the format: {IMO}-{MeanDraft}-{WASPStatus}-{UniqueID}

Segment	Description	Example
IMO	7-digit IMO number	1234567
MeanDraft	Mean draft in meters — decimal point replaced by underscore	12_50 (= 12.5 m), 09_00 (= 9.0 m)
WASPStatus	Wind-Assisted Ship Propulsion status: E = Enabled, D = Disabled, N = Not Available	E
UniqueID	Unique identifier	4fc2c963f66afa6b7e2d3c4a5f8e9b0

Example: 1234567-12_50-E-4fc2c963f66afa6b7e2d3c4a5f8e9b0