WebSocket API and vessel methodology
Weather Routing
Build and submit weather-aware voyage requests, understand the vessel-performance methodology, and validate vessel data visually.
Endpoint
wss://cm5crjt3wf.execute-api.ap-south-1.amazonaws.com/dev/Request lifecycle
Connect
Submit request
Route computation
Completion envelope
Download and display result
How request identifiers work
Current implementation:
request_id and correlation_id are two names for the same canonical server job identifier. At the worker boundary they must match. The job table is keyed by request_id, while result storage and support messages use correlation_id. client_request_id is separate and is owned by the calling application. The WebSocket submission layer uses it as an idempotency identifier: reuse it only when retrying the exact same payload. The downstream worker echoes it and stores it as result metadata, while the canonical job itself is keyed by request_id/correlation_id.| Identifier | Who owns it | Purpose |
|---|---|---|
request_id | Canonical job identifier | Used for DynamoDB job state and returned as the same value as correlation_id in the current flow. |
correlation_id | Server/worker name for the canonical job identifier | Used in S3 result paths, completion/failure events and support diagnostics. It equals request_id. |
client_request_id | Calling application | Client-generated idempotency identifier at the WebSocket submission layer. Reuse it only to retry the exact same payload; use a new value after changing any request field. It is echoed in events and result metadata. |
Request and response JSON
Example input JSON
{
"action": "submitRequest",
"request_id": "b159821d-d823-4369-91fa-ea87dc6cfabb",
"client_request_id": "browser-request-100",
"payload": {
"start": [
0.0,
0.0
],
"end": [
-36.0,
0.0
],
"waypoints": [],
"start_ts": "2026-07-11 11:30:00",
"earliest_ts": "2026-07-18 00:00:00",
"latest_ts": "2026-07-21 00:00:00",
"imo": 9999999,
"objective": "min_cost",
"use_arrival_window": true,
"draft": 20.0,
"bunker_price": 900.0,
"market_hire": 30000.0,
"vessel": {
"vessel_type": "Tanker",
"loa_m": 330.0,
"lbp_m": 320.0,
"beam_m": 60.0,
"depth_m": 30.0,
"displacement_t": 320000.0,
"dwt_t": 280000.0,
"gm_m": 4.5,
"max_power_kw": 23000.0,
"design_rpm": 74.0,
"propulsive_efficiency": 0.7,
"hull_degradation_percent": 8.0,
"sea_trial_speed_kn": [
8.0,
10.0,
12.0,
14.0,
15.0,
16.0
],
"sea_trial_power_kw": [
2200.0,
3900.0,
6800.0,
11500.0,
15000.0,
19500.0
],
"sea_trial_rpm": [
38.0,
45.0,
52.0,
60.0,
65.0,
70.0
],
"sfoc_load_percent": [
40.0,
60.0,
75.0,
90.0,
100.0
],
"sfoc_g_per_kwh": [
188.0,
176.0,
169.0,
170.0,
175.0
],
"natural_roll_period_s": null,
"roll_damping_ratio": 0.06,
"roll_excitation_gain": 1.0,
"motion_position_from_midship_ratio": 0.45,
"kyy_over_l": 0.25,
"block_coefficient": null,
"entrance_length_m": null,
"superstructure_beam_m": 42.0,
"superstructure_height_m": 16.0,
"superstructure_length_m": 46.0
},
"constraints": {
"min_speed": 10.0,
"max_speed": 16.0,
"max_wind": 30.0,
"max_wave": 6.0,
"max_swell": 6.0,
"min_power": 2500.0,
"max_power": 21000.0,
"max_engine_load_fraction": 0.95,
"min_rpm": 40.0,
"max_rpm": 100.0,
"max_roll_deg": 10.0,
"max_pitch_deg": 4.0,
"reject_synchronous_roll": true,
"reject_parametric_roll": true,
"low_risk_significant_wave_height_m": 0.75,
"motion_screen_safety_factor": 2.0,
"daily_consumption_enabled": false
},
"land_distance_threshold": 25.0,
"avoid_eca": false
}
}Example downloaded output JSON
{ "schema_version": "1.2", "status": "completed", "elapsed_s": 4.123, "final_route": [ { "action": "sail", "start": {"lat": 0.0, "lon": 0.0}, "end": {"lat": -3.2259, "lon": -0.25}, "sog": 10.5, "stw": 10.88, "consumption_tons": 27.77, "rpm": 48.07, "total_power_kw": 7983.07, "weather": {"wind_speed_kn": 8.83, "significant_wave_height_m": 1.57}, "motion": {"roll_deg": 0.03, "pitch_deg": 0.60, "edge_feasible": true}, "power_breakdown": { "clean_calm_water_kw": 5170.32, "hull_degraded_calm_water_kw": 5583.95, "wind_added_kw": 332.85, "wave_and_swell_added_kw": 2066.28, "required_shaft_power_kw": 7983.07 } } ]
}Request envelope and voyage fields
| Field | Type / Unit | Required | Possible values / default | Description |
|---|---|---|---|---|
action | string | Yes | submitRequest | WebSocket action used to submit a new weather-routing job. |
request_id | string | Yes | Any non-empty string; UUID v4 is recommended | Canonical job identifier in the current flow. The worker normalizes it to the same value as correlation_id and uses it for job state, result storage and replay. |
client_request_id | string | Recommended | A unique client-generated value, such as browser-request-<timestamp> | Idempotency identifier used by the WebSocket submission layer. Reuse it only for an exact retry of the same payload. Generate a new value whenever any request field changes. |
payload | object | Yes | JSON object | Contains voyage, vessel, commercial and constraint inputs. |
payload.start | array [lat, lon] | Yes | Latitude -90..90; longitude normally -180..180 | Departure coordinate in decimal degrees, ordered latitude then longitude. |
payload.end | array [lat, lon] | Yes | Latitude -90..90; longitude normally -180..180 | Destination coordinate in decimal degrees, ordered latitude then longitude. |
payload.waypoints | array of [lat, lon] | No | Default [] | Ordered mandatory intermediate coordinates. Omit the field or use an empty array when no waypoint is required. |
payload.start_ts | UTC datetime or epoch | Yes | YYYY-MM-DD HH:MM:SS or Unix seconds | Departure time. String parsing is strict and does not accept a trailing Z or timezone suffix. |
payload.earliest_ts | UTC datetime or epoch | No | Default: start_ts | Earliest acceptable arrival. Mainly relevant when use_arrival_window is true. |
payload.latest_ts | UTC datetime or epoch | No | Default: start_ts + 15 days | Latest acceptable arrival. If earliest and latest are reversed, the routing code swaps them. |
payload.imo | integer | No | Normally a valid 7-digit IMO number | Optional vessel metadata. The supplied worker and routing core do not use this field in route calculation. |
payload.objective | string | No | min_cost (default), min_time, min_fuel | Selects the economic objective. Unknown strings currently fall back to minimum-cost behaviour, so clients should send only the documented values. |
payload.use_arrival_window | boolean | No | false (default) or true | Enables arrival-window handling using earliest_ts and latest_ts. |
payload.draft | float, m | No (recommended) | Default: vessel.draft_m, otherwise 16.0; must be positive and below vessel depth | Selects the navigability graph/draft condition and is passed to the vessel model. |
payload.bunker_price | float, currency/t | No | Default 500.0; use a finite non-negative value | Fuel price used by min_cost and min_fuel. Use the same currency basis as market_hire. |
payload.market_hire | float, currency/day | No | Default 25000.0; use a finite non-negative value | Time-related cost used by min_cost and min_time. |
payload.vessel | object | Yes | See Vessel fields below | Required by the complete fuel, power and motion model. |
payload.constraints | object | No | Default {} | Operational and feasibility limits. Every documented constraint has a code default. |
payload.land_distance_threshold | float, NM | No | Default 25.0; use ≥ 0 | Threshold used by waypoint-to-graph connection and near-land penalty logic. It is a routing preference/penalty input, not a guaranteed minimum clearance. |
payload.avoid_eca | boolean | No | false (default) or true | When true, selects the ECA-aware prebuilt routing graph. |
payload.stage1_speed_step | float, kn | No | Default 1.0; must be > 0 | Speed-grid increment used by the coarse Stage-1 corridor search. |
payload.stage2_speed_step | float, kn | No | Default 0.5; must be > 0 | Speed-grid increment used by the refined Stage-2 search. |
Legacy fields: the current routing core does not read
payload.route_objective or payload.speed_range. Use payload.objective, constraints.min_speed, constraints.max_speed, payload.stage1_speed_step and payload.stage2_speed_step instead.Vessel fields
The complete model requires vessel geometry, power/RPM calibration and SFOC data. Sea-trial and SFOC arrays are positional: values at the same index describe one calibrated operating point.
| Field | Type / Unit | Required | Possible values / default | Description |
|---|---|---|---|---|
vessel.vessel_type | string | No (recommended) | Tanker, Bulk Carrier/Bulk, Container/Container Ship, General Cargo | Preferred vessel category selector. Matching is case-insensitive. |
vessel.extra_flag | integer | No | Default 0; legacy mapping: 0 Bulk Carrier, 1 Tanker, 2 Container, 3 General Cargo | Legacy fallback used only when vessel_type is absent. When vessel_type is supplied, this field does not select the model type. |
vessel.loa_m | float, m | Yes | Finite value > 0 | Length overall. |
vessel.lbp_m | float, m | No | Default: loa_m; length_m is also accepted as an alias | Length used by the resistance model, normally length between perpendiculars. |
vessel.beam_m | float, m | Yes | Finite value > 0 | Maximum vessel breadth. |
vessel.depth_m | float, m | Yes | Finite value > 0; must exceed draft | Moulded depth. |
vessel.draft_m | float, m | No | Used only when top-level payload.draft is omitted | Optional vessel-level draft fallback. |
vessel.displacement_t | float, t | Conditional | Finite value > 0, or omit when a valid block coefficient is supplied | Required unless block_coefficient is supplied. DWT is never substituted for displacement. |
vessel.dwt_t | float, t | No | Default 0.0; use ≥ 0 | Retained for compatibility/reporting only; it does not replace displacement. |
vessel.gm_m | float, m | Yes | Finite value > 0 | Metacentric height used in roll-period and motion calculations. |
vessel.max_power_kw | float, kW | Conditional | Finite value > 0; mcr_power_kw is accepted as an alias | Required propulsion MCR/maximum power basis. |
vessel.design_rpm | float, rpm | Yes | Finite value > 0 | Reference design RPM. |
vessel.propulsive_efficiency | float | No | Default 0.70; must be in (0, 1] | Converts effective resistance power to required shaft power. |
vessel.hull_degradation_percent | float, % | No | Default: constraints.hull_degradation_percent, otherwise 0.0; must be ≥ 0 | Additional calm-water power allowance for hull/propeller condition. |
vessel.operational_margin_percent | float, % | No | Default: constraints.operational_margin_percent, otherwise 0.0 | Vessel-level margin added to calculated demand. This value takes precedence over the constraint-level fallback. |
vessel.sea_trial | array of objects | Conditional | At least 3 records containing stw_kn, shaft_power_kw, rpm | Alternative record-list form for the three sea-trial arrays below. |
vessel.sea_trial_speed_kn | array, kn | Conditional | At least 3 finite values, strictly increasing | Required with the paired power and RPM arrays when sea_trial is not supplied. |
vessel.sea_trial_power_kw | array, kW | Conditional | Same length as speed array; at least 3 finite values | Power values aligned positionally with sea-trial speed. |
vessel.sea_trial_rpm | array, rpm | Conditional | Same length as speed array; at least 3 finite values | RPM values aligned positionally with sea-trial speed. |
vessel.sfoc_curve | array of objects | Conditional | At least 3 records containing load_percent and sfoc_g_kwh | Alternative record-list form for the two SFOC arrays below. |
vessel.sfoc_load_percent | array, % | Conditional | At least 3 finite values, strictly increasing | Engine-load points required when sfoc_curve is not supplied. |
vessel.sfoc_g_per_kwh | array, g/kWh | Conditional | Same length as load array; at least 3 finite positive values recommended | SFOC values aligned positionally with load percentage. |
vessel.natural_roll_period_s | float or null, s | No | Positive value, or null/blank to estimate | When absent or non-positive, estimated as 0.86 × beam / √GM. |
vessel.roll_damping_ratio | float or null | No | Value in (0, 1); otherwise a vessel-type default is used | Dimensionless roll damping ratio. |
vessel.roll_excitation_gain | float | No | Default 1.0; positive values recommended | Multiplier applied to calculated roll excitation. |
vessel.motion_position_from_midship_ratio | float | No | Default 0.45; must be in [0, 0.5] | Longitudinal motion-evaluation position. The earlier documentation incorrectly showed a 0–1 range. |
vessel.kyy_over_l | float | No | Default 0.25; must be in [0.10, 0.50] | Pitch radius-of-gyration ratio. |
vessel.block_coefficient | float or null | Conditional | 0.40..0.98, or null when displacement is supplied | If omitted, the model derives block coefficient from displacement, length, beam and draft; the resolved value must remain within the allowed range. |
vessel.entrance_length_m | float or null, m | No | Positive value, or null to estimate | When omitted, estimated from vessel type and constrained to approximately 10–30% of vessel length. |
vessel.superstructure_beam_m | float or null, m | No | Positive value; default 0.70 × beam | Representative exposed breadth used for wind resistance. |
vessel.superstructure_height_m | float or null, m | No | Positive value; default 0.80 × depth | Representative exposed height used for wind resistance. |
vessel.superstructure_length_m | float or null, m | No | Positive value; default 0.14 × length | Representative exposed length used for wind resistance. |
Validation rules that commonly cause rejected requests: draft must be below depth; provide displacement or block coefficient; sea-trial speed/power/RPM inputs must contain at least three aligned points with strictly increasing speed; SFOC load/value inputs must contain at least three aligned points with strictly increasing load; DWT is not accepted as a substitute for displacement.
Constraint fields
| Field | Type / Unit | Required | Possible values / default | Description |
|---|---|---|---|---|
constraints.min_speed | float, kn | No | Default 8.0; non-negative recommended | Authoritative lower candidate SOG. This, not legacy speed_range.start, defines the routing speed grid. |
constraints.max_speed | float, kn | No | Default 16.0; must be ≥ min_speed | Authoritative upper candidate SOG. Keep the requested speed range within the calibrated sea-trial range; the model marks an edge power-infeasible when calculated STW falls outside the sea-trial cache. |
constraints.max_wind | float, kn | No | Default 45.0; use ≥ 0 | Maximum permitted encountered wind speed. |
constraints.max_wave | float, m | No | Default 15.0; use ≥ 0 | Maximum permitted significant combined wave height. |
constraints.max_swell | float, m | No | Default 15.0; use ≥ 0 | Maximum permitted swell height. |
constraints.min_power | float, kW | No | Default 0.0 | Minimum permitted required propulsion power. |
constraints.max_power | float, kW | No | Default: vessel MCR/max_power_kw | Maximum permitted required propulsion power. |
constraints.max_engine_load_fraction | float | No | Default 1.0; must be in (0, 1.25] | Maximum engine load relative to the configured power basis. |
constraints.min_rpm | float, rpm | No | Default 0.0 | Minimum permitted calculated RPM. |
constraints.max_rpm | float, rpm | No | Default 1200.0; should be ≥ min_rpm | Maximum permitted calculated RPM. |
constraints.max_roll_deg | float, ° | No | Default: disabled; if supplied, must be > 0 | Maximum accepted calculated roll amplitude. |
constraints.max_pitch_deg | float, ° | No | Default: disabled; if supplied, must be > 0 | Maximum accepted calculated pitch amplitude. |
constraints.max_vertical_accel_g | float, g | No | Default: disabled; if supplied, must be > 0 | Accepted vertical-acceleration limit passed to the motion constraint model. |
constraints.max_vertical_motion_m | float, m | No | Default: disabled; if supplied, must be > 0 | Accepted vertical-motion limit passed to the motion constraint model. |
constraints.reject_synchronous_roll | boolean | No | false (default) or true | Rejects combinations flagged for synchronous-roll risk. |
constraints.reject_parametric_roll | boolean | No | false (default) or true | Rejects combinations flagged for parametric-roll risk. |
constraints.low_risk_significant_wave_height_m | float, m | No | Default 0.75; non-negative recommended | Below this height the model may use its low-risk motion screening path. |
constraints.motion_screen_safety_factor | float | No | Default 2.0; positive values recommended | Safety multiplier used during motion screening. |
constraints.hull_degradation_percent | float, % | No | Default 0.0; used only when vessel-level value is absent | Fallback hull-degradation allowance. |
constraints.operational_margin_percent | float, % | No | Default 0.0; used only when vessel-level value is absent | Fallback operating margin. |
constraints.daily_consumption_enabled | boolean | No | false (default) or true | Enables daily fuel-consumption tracking and limit enforcement. |
constraints.max_daily_consumption | float, t/day | Conditional | Default effectively unlimited (1e30); positive value when enabled | Maximum daily fuel consumption when daily enforcement is enabled. |
constraints.daily_consumption_penalty_lambda | float | No | Default 0.0; use ≥ 0 | Optional soft penalty weight related to daily consumption. |
constraints.daily_consumption_bucket_size | float, t | No | Default 2.0; positive value recommended | Bucket size used by daily-consumption state tracking. |
Advanced speed-policy fields
Stage-specific keys override the common key. When no stage-specific value is supplied, both stages inherit the common value.
| Field | Type / Unit | Required | Possible values / default | Description |
|---|---|---|---|---|
constraints.max_speed_change | float, kn | No | Default 1.0; must be ≥ 0 | Common per-decision speed-change limit used by both stages unless a stage-specific value is supplied. |
constraints.stage1_max_speed_change | float, kn | No | Default: common value | Stage-1 override. |
constraints.stage2_max_speed_change | float, kn | No | Default: common value | Stage-2 override. |
constraints.speed_decision_interval_nm | float, NM | No | Default 300.0; must be ≥ 0 | Common minimum sailing distance between speed decisions. |
constraints.stage1_speed_decision_interval_nm | float, NM | No | Default: common value | Stage-1 override. |
constraints.stage2_speed_decision_interval_nm | float, NM | No | Default: common value | Stage-2 override. |
constraints.stage2_speed_decision_relaxation_percent | float, % | No | Default 10.0; must be in [0, 100] | Allows a forward speed reduction slightly before the full Stage-2 decision interval. |
constraints.minimum_economic_benefit_usd | float | No | Default 150.0; must be ≥ 0 | Common immediate economic-benefit threshold for speed changes. Despite the legacy _usd name, use the same monetary unit as bunker_price and market_hire. |
constraints.stage1_minimum_economic_benefit_usd | float | No | Default: common value | Stage-1 override. |
constraints.stage2_minimum_economic_benefit_usd | float | No | Default: common value | Stage-2 override. |
constraints.stage2_economic_speed_change_pruning_enabled | boolean | No | true (default) or false | When false, Stage 2 bypasses the immediate economic-pruning test while retaining the selected route objective. |
constraints.prevent_immediate_speed_reversal | boolean | No | true (default) or false | Common rule preventing an immediate increase/decrease reversal. |
constraints.allow_emergency_speed_reduction | boolean | No | true (default) or false | Allows safety-driven reductions that would otherwise violate the ordinary speed-decision policy. |
constraints.speed_policy_distance_bucket_nm | float, NM | No | Default 50.0; must be ≥ 0 | Distance discretization used by the speed-policy state. |
constraints.speed_reversal_interval_multiplier | float | No | Default 2.0; must be ≥ 0 | Multiplier controlling how long the reversal restriction remains active. |
constraints.one_speed_per_resistance_beaufort | boolean | No | false (default) or true | Restricts each resistance-Beaufort class to one selected speed. The legacy ..._bf alias is also accepted. |
constraints.monotonic_speed_vs_resistance_beaufort | boolean | No | false (default) or true | Requires speed not to increase as the resistance-Beaufort class worsens. The legacy ..._bf alias is also accepted. |
The routing module also contains internal graph-search, diagnostics, cache and animation controls. They are intentionally not presented as public client inputs because they are implementation tuning parameters rather than stable API contract fields.
Completion event
{ "type": "route.completed", "correlation_id": "7293d8ca-e49c-4e56-8cf3-dd00d6a16bb1", "client_request_id": "browser-request-100", "status": "COMPLETED", "result_status": "completed", "result_url": "https://temporary-signed-result-url", "result_url_expires_in_sec": 900, "next_action": "OPEN_RESULT_URL"
}The URL is temporary and should be opened or downloaded promptly. Treat it as confidential.
Sample downloaded result
{ "schema_version": "1.2", "environment": "dev", "resource_environment": "dev", "correlation_id": "7293d8ca-e49c-4e56-8cf3-dd00d6a16bb1", "request_id": "7293d8ca-e49c-4e56-8cf3-dd00d6a16bb1", "client_request_id": "browser-request-100", "status": "completed", "generated_at": "2026-07-27T04:23:30.831795+00:00", "elapsed_s": 4.123, "final_route": [ { "action": "sail", "start": { "lat": 0.0, "lon": 0.0 }, "end": { "lat": -3.2259, "lon": -0.25 }, "sog": 10.5, "stw": 10.88, "consumption_tons": 27.77, "time_hours": 18.5, "time": "2026-07-11 11:30:00 UTC", "distance_nm": 194.26, "weather": { "wind_speed_kn": 8.83, "wind_from_deg": 157.14, "significant_wave_height_m": 1.57, "significant_wave_from_deg": 203.49, "current_speed_kn": 0.7, "current_to_deg": 305.14, "swell_wave_height_m": 1.32, "swell_wave_from_deg": 205.03, "wind_wave_height_m": 0.79, "wind_wave_from_deg": 163.18, "wind_wave_period_s": 6.61, "swell_wave_period_s": 12.86 }, "rpm": 48.07, "power": 7983.07, "total_power_kw": 7983.07, "motion": { "roll_deg": 0.03, "pitch_deg": 0.6, "vertical_motion_m": 1.6, "vertical_acceleration_g": 0.18, "synchronous_roll_risk": false, "parametric_roll_risk": false, "calculation_mode": 1, "power_feasible": true, "motion_feasible": true, "edge_feasible": true }, "power_breakdown": { "clean_calm_water_kw": 5170.32, "hull_degraded_calm_water_kw": 5583.95, "wind_added_kw": 332.85, "wave_and_swell_added_kw": 2066.28, "required_shaft_power_kw": 7983.07 } } ]
}
Result document fields
| Field | Type / Unit | Description |
|---|---|---|
schema_version | string | Version of the downloadable result schema. |
environment | string | Execution mode that produced the result, such as local, dev, or prod. |
resource_environment | string | AWS resource environment used for processing. |
correlation_id | string | Canonical route-job identifier used for result storage and diagnostics. It equals request_id in the current implementation. |
request_id | string | Job-table identifier. The worker requires it to match correlation_id. |
client_request_id | string | Optional client-owned reference echoed for UI/workflow reconciliation; not the server idempotency or storage key. |
user_id | integer | Account identifier associated with the request. |
service_id | integer | Service identifier used for subscription and quota processing. |
status | string | Overall route-result status, such as completed or no_feasible_route. |
generated_at | ISO 8601 datetime | UTC timestamp when the result document was generated. |
elapsed_s | float, s | Total route-processing elapsed time. |
final_route | array | Ordered sailing segments forming the optimized route. |
request_payload | object | Original submitted routing payload when returned by the selected environment. |
Route segment fields
| Field | Type / Unit | Description |
|---|---|---|
action | string | Segment action, normally sail. |
start.lat / start.lon | float, ° | Segment start position. |
end.lat / end.lon | float, ° | Segment end position. |
sog | float, kn | Speed over ground after accounting for current. |
stw | float, kn | Speed through water used for propulsion and resistance calculations. |
consumption_tons | float, t | Estimated fuel consumed over the segment. |
time_hours | float, h | Estimated sailing duration for the segment. |
time | UTC datetime | Segment departure or evaluation timestamp. |
distance_nm | float, NM | Great-circle or route-edge distance represented by the segment. |
rpm | float, rpm | Calculated propulsion RPM. |
power | float, kW | Calculated required propulsion power. |
total_power_kw | float, kW | Total required shaft power; retained explicitly in the result schema. |
Weather fields
| Field | Type / Unit | Description |
|---|---|---|
weather.wind_speed_kn | float, kn | Encountered wind speed. |
weather.wind_from_deg | float, ° true | Direction from which the wind is blowing. |
weather.significant_wave_height_m | float, m | Combined significant wave height. |
weather.significant_wave_from_deg | float, ° true | Direction from which the significant wave system arrives. |
weather.current_speed_kn | float, kn | Surface-current speed. |
weather.current_to_deg | float, ° true | Direction toward which the current flows. |
weather.swell_wave_height_m | float, m | Significant swell height. |
weather.swell_wave_from_deg | float, ° true | Direction from which swell arrives. |
weather.wind_wave_height_m | float, m | Significant wind-wave height. |
weather.wind_wave_from_deg | float, ° true | Direction from which wind waves arrive. |
weather.wind_wave_period_s | float, s | Representative wind-wave period. |
weather.swell_wave_period_s | float, s | Representative swell period. |
Motion and feasibility fields
| Field | Type / Unit | Description |
|---|---|---|
motion.roll_deg | float, ° | Calculated roll amplitude. |
motion.pitch_deg | float, ° | Calculated pitch amplitude. |
motion.vertical_motion_m | float, m | Calculated vertical displacement at the configured motion position. |
motion.vertical_acceleration_g | float, g | Calculated vertical acceleration expressed in gravitational units. |
motion.synchronous_roll_risk | boolean | Whether the segment is flagged for synchronous-roll risk. |
motion.parametric_roll_risk | boolean | Whether the segment is flagged for parametric-roll risk. |
motion.calculation_mode | integer | Motion-model mode used for the calculation. |
motion.power_feasible | boolean | Whether required power satisfies the configured limits. |
motion.motion_feasible | boolean | Whether calculated vessel motion satisfies the configured limits. |
motion.edge_feasible | boolean | Combined feasibility flag for the route segment. |
Important: a segment with
edge_feasible: false does not satisfy all configured feasibility checks. Client applications should not interpret every returned segment as operationally acceptable without considering the result status and feasibility flags.Power-breakdown fields
| Field | Type / Unit | Description |
|---|---|---|
power_breakdown.clean_calm_water_kw | float, kW | Baseline clean-hull calm-water power. |
power_breakdown.hull_degraded_calm_water_kw | float, kW | Calm-water power after applying hull degradation. |
power_breakdown.wind_added_kw | float, kW | Power added or reduced by wind resistance; may be negative with strongly assisting wind. |
power_breakdown.wave_and_swell_added_kw | float, kW | Additional power attributed to waves and swell. |
power_breakdown.required_shaft_power_kw | float, kW | Final required shaft power for the segment. |
No feasible route
A request may finish processing without producing an acceptable route. In that case the completion event uses status: COMPLETED with result_status: no_feasible_route. Display the returned message and failure code to the user rather than treating it as a network failure.
Failure event
{ "type": "route.failed", "correlation_id": "server-correlation-id", "client_request_id": "browser-request-100", "status": "FAILED_FINAL", "failure_code": "ROUTE_PROCESSING_FAILED", "message": "The route could not be completed.", "next_action": "CONTACT_SUPPORT"
}
Integration guidance
- Generate a fresh UUID-style
request_idfor each genuinely new route and persist therequest_id/correlation_idreturned by the service. - Treat
client_request_idas the submission idempotency key. Reuse it only for an exact retry of the same payload; generate a new value after changing any field. - Use
constraints.min_speedandconstraints.max_speedas the authoritative speed range; do not rely on the legacyspeed_rangeobject. - Validate vessel geometry, paired sea-trial arrays and paired SFOC arrays before submission.
- Use UTC consistently and send timestamp strings as
YYYY-MM-DD HH:MM:SS. - Download the result before the presigned URL expires and handle duplicate completion events idempotently using the canonical request/correlation identifier.
Interactive request builder
Complete the sections below. The request preview updates automatically. Request identifiers are generated when the page loads, but remain editable.
Connection and request identifiers
Canonical job ID; use a new UUID for a new route.
Client idempotency key; generate a new value whenever the payload changes.
Voyage and commercial inputs
Start coordinate
End coordinate
Waypoints
Add optional intermediate coordinates in sailing order.
| Latitude | Longitude | |
|---|---|---|
Sent as YYYY-MM-DD HH:mm:ss.
Used when arrival window is enabled.
Used when arrival window is enabled.
Vessel particulars and propulsion
Performance and fuel curves
Sea-trial curve
Each row represents one aligned operating point.
| Speed (kn) | Power (kW) | RPM | |
|---|---|---|---|
SFOC curve
Pair each engine-load point with its SFOC value.
| Engine load (%) | SFOC (g/kWh) | |
|---|---|---|
Motion, geometry, and model controls
Operational constraints
Generated request
Browser WebSocket clients cannot set arbitrary HTTP headers. The query-parameter name must match your API Gateway authorizer configuration.
Two-step result retrieval: when processing finishes, the WebSocket sends a
route.completed envelope containing result_url, its expiry duration and checksum metadata. The browser immediately fetches that signed URL, parses the downloaded route document, shows it in the scrollable JSON viewer and plots the ordered final_route segments on the map. A typical URL is valid for 900 seconds. If it expires, the client must request a fresh result link or resubmit through the supported workflow.Route map
A completion event contains a temporary result_url, not the full route. The browser automatically downloads the route JSON from that URL and then plots final_route. The standard link is valid for 900 seconds (15 minutes); download it promptly.
Waiting for a completion event.
Submit a request to display the optimized route.
Result JSON
No result received yet.
Keep the WebSocket connection available for completion or failure events. Persist both request identifiers so results can be matched even when multiple requests are active.
Vessel-performance methodology
Vessel Power, Fuel and Motion Model
A route is evaluated in a clear physical sequence: first determine how fast the vessel moves through the surrounding water, then estimate the forces opposing that motion, determine the propulsion power needed to overcome those forces, convert that power into fuel consumption, and finally check vessel motion and operational feasibility.
The complete calculation flow
1Find STWSeparate vessel motion from ocean-current motion.
→
2Estimate resistanceFind the forces trying to slow the vessel.
→
3Calculate powerDetermine the shaft power needed to overcome resistance.
→
4Estimate fuelConvert power and operating duration into fuel used.
→
5Check motionEstimate roll, pitch, heave and acceleration.
→
6Decide feasibilityAccept or reject the route segment against limits.
Why the order matters: fuel use cannot be understood from vessel speed alone. Current changes the speed through water, weather changes resistance, resistance changes required power, and required power changes fuel consumption.
1. Speed Through Water (STW)
What is the difference between SOG and STW?
Speed Over Ground (SOG) is the vessel's progress across the earth. Speed Through Water (STW) is the speed of the hull relative to the surrounding water. A favourable current can make SOG higher than STW; an opposing current can make SOG lower than STW.
STW is the important value for resistance and propulsion because the hull and propeller interact with water, not with the seabed.
STW and through-water heading = F(SOG, course over ground, current speed, current TO direction)
Earth-referenced directions
Wind, waves and swell use a FROM direction: the direction they arrive from. Current uses a TO direction: the direction the water flows toward.
SOG, current and STW vector relationship
The resulting vector provides both STW and the direction in which the vessel moves through the water. Cross-current is therefore handled correctly, rather than being treated as a simple speed addition or subtraction.
2. Resistance — what tries to slow the vessel
Resistance is the total opposing force the propulsion system must overcome to maintain a chosen speed. Think of it as the marine equivalent of drag on a road vehicle, but with several additional contributors from water, wind, waves and hull condition.
Calm-water resistance
The basic resistance created as the hull pushes water aside and water flows along the hull.
Hull-condition effect
Fouling and surface roughness increase friction, so more effort is needed at the same STW.
Wind resistance
Wind acting on the exposed hull and superstructure can oppose or assist the vessel.
Wind-wave resistance
Locally generated waves create added resistance and vessel motion.
Swell resistance
Longer-period waves from distant weather systems can affect resistance and motion differently from local wind waves.
3. Power required to move the vessel
Resistance is a force. The propulsion system must supply enough shaft power to overcome that force at the selected STW. Higher resistance or higher speed generally requires more power.
Required shaft power = F(calm-water demand, hull condition, wind contribution, wind-wave contribution, swell contribution, propulsion efficiency, operational margin)
Clean calm-water powerThe vessel-specific baseline power at the selected STW.
+Hull-condition allowanceAdditional power associated with fouling or surface condition.
+Weather-added powerPower needed because of wind, wind waves and swell.
+Operational marginAn optional planning allowance applied to the combined demand.
=Required shaft powerThe power the propulsion system must deliver.
A following wind or favourable sea condition can reduce an environmental contribution, but the final power is still checked against vessel and engine limits.
4. From power to fuel consumption
Once required shaft power is known, the model determines how heavily the engine is operating. The engine's fuel-efficiency reference indicates how much fuel is needed to produce each unit of propulsion energy at that load.
Required powerPower needed for the route segment.
Engine loadRequired power compared with rated power.
Fuel efficiencyFuel required per unit of generated energy at that load.
Operating durationHow long the vessel remains at this condition.
Fuel consumedTotal tonnes used over the segment.
Engine load = F(required shaft power, maximum continuous rating)
Fuel efficiency = F(engine load, vessel engine reference)
Fuel consumed = F(required shaft power, fuel efficiency, segment duration)
Fuel efficiency = F(engine load, vessel engine reference)
Fuel consumed = F(required shaft power, fuel efficiency, segment duration)
RPM is estimated from the vessel's operating reference at the selected STW so the reported speed, power, RPM and fuel values describe a consistent operating point.
5. Roll, pitch, heave and vertical acceleration
Weather does more than increase fuel use. Waves also move the vessel. The model estimates the main motions that can affect safety, cargo, equipment and comfort.
Understanding vessel motion
What controls the response?
Encounter directionHead seas tend to increase pitch; beam seas tend to increase roll.
Wave heightLarger waves generally produce larger forces and motions.
Wave periodThe timing between waves can approach the vessel's natural motion periods.
Vessel geometry and loadingLength, beam, draft, displacement and stability influence the response.
Vessel speedSpeed changes how frequently the vessel encounters successive waves.
Roll, pitch, heave and acceleration = F(STW, through-water heading, wave height, wave period, wave FROM direction, vessel geometry, loading and stability)
6. Operational feasibility
A route segment is accepted only when the propulsion demand and vessel motion remain within the submitted operational limits.
Power check
Can the engine provide the required shaft power without exceeding the permitted load?
RPM check
Does the operating point remain within the permitted RPM range?
Motion check
Are roll, pitch, vertical movement and acceleration within the selected limits?
Risk check
Are synchronous-roll or parametric-roll relationships absent or permitted?
Route-segment feasibility = F(power status, RPM status, motion status, risk flags and operational constraints)
Weather inputs and direction conventions
| Weather value | Unit | Direction convention | How it is used |
|---|---|---|---|
| Wind speed and direction | kn and degrees true | FROM | Apparent wind and aerodynamic contribution. |
| Significant wave height and direction | m and degrees true | FROM | Overall sea-state reporting and screening. |
| Current speed and direction | kn and degrees true | TO | SOG-to-STW vector resolution. |
| Swell height, direction and period | m, degrees true and s | FROM | Swell resistance and motion response. |
| Wind-wave height, direction and period | m, degrees true and s | FROM | Local-wave resistance and motion response. |
Avoid double counting: significant wave height describes the combined sea state. Wind-wave and swell partitions are evaluated separately for detailed resistance and motion effects; significant wave height is not added as a third independent wave system.
How to read the returned results
Navigation
SOG, STW, course, through-water heading, segment distance and duration.
Power
Calm-water baseline, hull-condition contribution, wind contribution, wave and swell contribution, and required shaft power.
Engine and fuel
RPM, engine load, fuel efficiency and segment fuel consumption.
Motion
Roll, pitch, vertical movement, vertical acceleration and risk indicators.
Feasibility
Power, motion and overall route-segment feasibility flags.
Proprietary-use disclaimer. The vessel model, methodology, diagrams, response structure and explanatory material are proprietary to Blue Green Intelligence and may not be reproduced or used to recreate a competing implementation without written authorization.
Interactive visualisation
Vessel Model Playground
Enter vessel particulars and performance curves to see the vessel outline and charts respond immediately. This playground is a visual data-quality aid; it does not reproduce the production routing calculation.
Vessel geometry
Responsive vessel outline
Sea-trial and fuel curves
Sea-trial performance
Add or remove aligned speed, power, RPM, and consumption points.
| Speed (kn) | Power (kW) | RPM | Consumption (t/day) | |
|---|---|---|---|---|
SFOC curve
Enter engine load and matching SFOC values.
| Engine load (%) | SFOC (g/kWh) | |
|---|---|---|
Curves update as values change.
Hull condition and 360° Beaufort simulation
Select a Beaufort number and run the simulation. The service evaluates wind and waves approaching from every degree while the vessel heads north. The selected Beaufort wind speed and wave height are shown above.
Total Weather Resistance
Combined added resistance from wind, wind waves and swell.
Weather Power
Power added by wind, wind waves and swell, separate from calm-water demand.
Total Power
Required shaft power after calm-water demand, hull condition, weather and operational margin.
Total Consumption
Estimated daily fuel consumption at the resulting total power and engine load.
Directional convention: the vessel heading is fixed at 000° true. Wind and waves are evaluated as FROM directions from 0° through 359°. The selected Beaufort row supplies representative maximum wind speed and wave height; the API also applies a documented representative wave period for the selected sea state.