/v2/enroute-cp-warranty.json

GET

/v2/enroute-cp-warranty.json

EnRoute CP Warranty Data Specification (v2)

• Data Area: Global
• Output Format: JSON
• Update Frequency: Once daily (DailyPerformanceXML pipeline)
• Data Lifecycle: 5 days (automatically expires after voyage completion)
• No Data Value: Field omitted when unavailable

What This API Does

"Is this vessel currently meeting its Charter Party (CP) warranty obligations?"

A Charter Party (CP) is a contract between a shipowner and a charterer that specifies guaranteed
vessel performance — typically a warranted speed (knots) and fuel consumption (MT/day).
This API provides real-time performance data for vessels currently on voyage, showing how
actual performance compares against those contractual warranties.

Only vessels actively on voyage are included. Vessels in port or with no recent data will not appear.

Use Cases

1. Real-time CP Performance Dashboard
Ship managers and charterers use this API to monitor all managed vessels at a glance.
A vessel with saving_time showing a positive (Loss) value is at risk of incurring delay damages
if the current performance trend continues.

2. Fuel Cost Overrun Alert
Integrate into alert systems that trigger when saving_fo (fuel over/under-consumption) exceeds
a threshold. Early detection allows speed or route adjustments to minimize losses.

3. Automated Voyage Performance Reports
Combine with voy_num and loading_condition to auto-generate mid-voyage performance reports.
Both Good Weather and All Weather analyses are included, enabling evaluation of hull performance
independently of weather conditions.

4. Combined Use with cp-performance.json
This API covers in-progress voyages; cp-performance.json covers completed voyages.
Use both together for seamless CP monitoring from departure to arrival.

Understanding the Fields

Good Weather vs All Weather

Prefix	Description
allwx_*	All-weather average including adverse conditions. Reflects actual elapsed time and fuel consumed.
goodwx_*	Good-weather period only, filtered by def_goodwx criteria (wind force, wave height). Measures true hull performance excluding weather impact.

CP warranty obligations are evaluated under good-weather conditions, so goodwx_* fields are
the basis for contract compliance assessment.

saving_time / saving_fo Sign Convention

Value	Meaning
Negative (-)	Saving — performing better than the warranty (ahead of schedule / under fuel budget)
Positive (+)	Loss — performing worse than the warranty (delay / over fuel budget)

Human-readable equivalents appear in damage_info_speed, damage_info_fo, damage_info_dogo
as "saving", "time lost", or "over consumption".

loading_condition

Value	Meaning
L	Laden — vessel carrying cargo
B	Ballast — vessel sailing without cargo

CP contracts typically specify different warranty values for laden and ballast voyages,
making this field essential for correct compliance evaluation.

Backward Compatibility with v1

v2 is backward compatible with v1. Existing v1 clients require no code changes to migrate.

• Response is an array (same as v1): [{...}, {...}]
• All fields present in v1 responses are preserved unchanged
• v2 adds the following fields when available (absent if data unavailable):

Added Field	Description	Source
loading_condition	Laden (L) or Ballast (B)	Metadata DynamoDB
voy_num	Voyage number	Metadata DynamoDB
ship_name	Ship name (enhanced fallback)	Metadata DynamoDB → ShipDB

Changes from v1

Item	v1	v2
Response format	Array [{...}]	Array [{...}] — same
New fields	—	loading_condition, voy_num added when available
Partial failure	Entire response fails	Returns available ships + X-Warning header
JSONP support	Yes (callback param)	Not supported (use CORS instead)
client param	Required	Not needed (extracted from auth token automatically)
ship_name source	Single source	Metadata table + ShipDB fallback

Ship object fields

Field Name	Description	Unit/Format	Sample Value	Type
ship_name	Ship name	-	Ship A	String
imo_num	IMO number	-	9222546	String
voy_num	Voyage number	-	123A	String
loading_condition	Loading condition (L=Laden, B=Ballast)	-	L	String
analyzed_time	Analysis creation time (MMM-dd/yyyy hh:ss UTC)	-	Feb-24/2020 04:06 UTC	String
def_goodwx	Good weather definition	-	BF 4, Sig. Wave 1.25m (DSS3), No adverse Current	String
allwx_avg_speed	All weather average speed	knots	11.91	String
allwx_perf_speed	All weather performance speed	knots	12.23	String
allwx_distance	All weather distance	NM	2850	String
allwx_time	All weather time	hour	239.2	String
allwx_cf	All weather current factor	knots	-0.22	String
allwx_daily_fo	All weather daily fuel oil	MT	18.99	String
allwx_daily_dogo	All weather daily diesel/gas oil	MT	0.1	String
allwx_total_fo	All weather total fuel oil	MT	189.22	String
allwx_total_dogo	All weather total diesel/gas oil	MT	1	String
goodwx_avg_speed	Good weather average speed	knots	12.46	String
goodwx_perf_speed	Good weather performance speed	knots	12.15	String
goodwx_distance	Good weather distance	NM	617	String
goodwx_time	Good weather time	hour	49.5	String
goodwx_sigwave	Good weather definition of significant wave height	meter	1.25	String
goodwx_cf	Good weather current factor	knots	0.31	String
goodwx_bf	Good weather definition of wind beaufort	beaufort	4	String
goodwx_current	Good weather definition of ocean current	-	No adverse Current	String
goodwx_daily_fo	Good weather daily fuel oil	MT	18.98	String
goodwx_daily_dogo	Good weather daily diesel/gas oil	MT	0.1	String
goodwx_total_fo	Good weather total fuel oil	MT	39.15	String
goodwx_total_dogo	Good weather total diesel/gas oil	MT	0.2	String
cp_speed	CP warranty speed	knots	11.5	String
cp_fo	CP warranty fuel oil	MT	20.5	String
cp_dogo	CP warranty diesel/gas oil	MT	0.1	String
cp_fuel_unit	CP warranty fuel unit	-	MT	String
allow_speed	Allowance speed	knots	0.5	String
allow_speed_unit	Allowance speed unit	-	kts	String
allow_fo	Allowance fuel oil	%	5	String
allow_dogo	Allowance diesel/gas oil	%	5	String
allow_fuel_unit	Allowance fuel unit	-	%	String
saving_time	Loss or saving time value ("-"=Saving, "+"=Loss)	Hours	1.3	String
saving_time_unit	Loss or saving time unit	-	hrs	String
saving_fo	Fuel oil over/under-consumption value ("-"=Saving, "+"=Loss)	MT	-24.78	String
saving_fuel_unit	Fuel oil over/under-consumption unit	-	MT	String
saving_dogo	DO/GO over/under-consumption value ("-"=Saving, "+"=Loss)	MT	-0.13	String
damage_info_speed	Time loss or saving information (time lost / no time lost / "")	-	time lost	String
damage_info_fo	Fuel oil over/under-consumption information (over consumption / saving / "")	-	saving	String
damage_info_dogo	DO/GO over/under-consumption information (over consumption / saving / "")	-	saving	String
comment	Comment/remarks	-	-	String

Parameters

Header Parameters

Authorization*

"WniWebApi " + Token ID

Typestring

Required

Query Parameters

ships

Ship filter (Optional). Comma-separated list of 7-digit IMO numbers.
Example: 9222546,9310006
Maximum 50 IMO numbers per request.
If omitted, returns all ships available to the client.

Typestring

pattern^[0-9]{7}(,[0-9]{7})*$

Responses

Successful response with enroute CP warranty data

Content-Type

application/json

{

"ships": [

{

"imo_num": "string",

"ship_name": "string",

"voy_num": "string",

"loading_condition": "string",

"analyzed_time": "string"

}

],

"warning": "string"

}

GET

/v2/enroute-cp-warranty.json

Playground

Headers

Authorization*

Variables

Key

Value

ships

Samples