Release 6.29 - 6.46

This page explains how to create vessel report integration with Dataloy API.

Have you considered using the vessel reporting functionality in our new web client? Get in touch for more information.

Chapter Contents:

• Port Call

• Noon report

• Arrival Report

• In Port Report

• Departure Report

• Example Messages

• Weather Data

• Direction

• Reason For Call

• Adding port calls

The vessel report endpoint is called PositionReport and can be accessed with Base URL + ws/rest/PositionReport

Port Call

A vessel report needs to be connected to a port call. Dataloy recommends to present a list of port calls to the user to make them select the correct one when reporting. To get a list of port calls, the following API call can be used

// Some code
GET ws/rest/PortCall?filter=voyage.vessel.imoNumber(EQ)999&filter=departureFixed(EQ)false&filter=voyage.voyageHeader.voyageStatus.statusTypeCode(IN)(NOM,OPR)&filter=voyage.voyageHeader.isBudget(EQ)false&filter=voyage.voyageHeader.isTemplate(EQ)false&filter=voyage.voyageHeader.isEstimate(EQ)false&filter=voyage.voyageHeader.isUnallocated(EQ)false&filter=voyage.scenarios.scenarioCode(EQ)MASTER&filter=reasonForCall.reasonForCall(NE)DEL&filter=reasonForCall.reasonForCall(NE)RED&sort=portCallSequence(AS) 

HTTP headerfields: {"voyage":{"key":"*"},"reasonForCall":{"reasonForCall":"*", "reasonForCallDesc":"*"}, "portCallSequence":"*", "port":{"portName":"*"},"eventLogs":{"eventLogDate":"*","event":{"eventCode":"*"}}}

Remarks will be connected to the Position Report. To send remarks requires:

• the set-up of a remark template in the database with a title and the extraction of the remark_id. Note: This construction is usually met with various various challenges with e-mail based vessel reporting (more information: contact Dataloy).

IMPORTANT: This type of construction causes various challenges with e-mail based vessel reporting (more information: contact contact Dataloy).

Noon report

Noon reports at sea should be connected to the next port call

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length	Example	Client validation
	A port call key		Yes
	Vessel Report Type Value = NOON for Noon Report		Yes	String	4
	Report Date Local Time		Yes	Date
	Position Latitude (Decimal Degrees)			Double	5	12.575	User input should be degrees, minutes and seconds. For example: 12° 34'5 N. Then degrees, minutes and seconds should be converted to decimals. Validation: if (minutes > 60) { return false; } if (direction === 'S' || direction === 'N') { if (degrees > 90) { return false; } if (degrees === 90 && minutes > 0) { return false; } } if (direction === 'E' || direction === 'W') { if (degrees > 180) { return false; } if (degrees === 180 && minutes > 0) { return false; } } return true;
	Position Longitude (Decimal Degrees)			Double	5	123.76	Same validation as for latitude
	Array of EventLog. For noon report this can be estimated time of arrival, berthing and departure. All dates are in local time. It's not necessary to include all 3 types. If you only want to update arrival then only include arrival EventLog Arrival event = ARR Berthing event = BRT Departure event = DEP	Updates ETA, ETB and ETD		Array of EventLogs		[{eventLogDate: "2023-01-03T03:34:00.000Z", event: "ARR"}, {eventLogDate: "2023-01-03T03:34:00.000Z", event: "BRT"}, {eventLogDate: "2023-01-03T03:34:00.000Z", event: "DEP"}]
	True Course			Integer	38
	Distance Sailed Since Last Report			Double			Positive decimal value
	Hours in Service Since Last Report			Double			Positive decimal value
	Distance To Go			Double			Positive decimal value
	Speed Made Good			Double			Positive decimal value
				Integer	38
	Wind Force. Beaufort.			Integer	38		0-12
				Integer	38
	Sea State. Integer from 0 - 9.			Integer	38		0-9
weather				Integer	38
	Main Engine RPM Since Last Report			Double			Positive decimal value
	Daily Fuel Oil Consumption			Double			Positive decimal value
	Daily Diesel Oil Consumption			Double			Positive decimal value
	Daily Fuel Oil Low Sulphur Consumption			Double			Positive decimal value
	Daily Diesel Oil Low Sulphur Consumption			Double			Positive decimal value
	Daily Net Fresh Water Consumption			Double			Positive decimal value
	Fuel Oil Remaining on Board (FO RoB)	Updates FO arrival RoB of the Port Call		Double			Positive decimal value
	Diesel Oil Remaining on Board (DO RoB)	Updates DO arrival RoB of the Port Call		Double			Positive decimal value
	Fuel Oil Low Sulphur Remaining on Board (FO LS RoB)	Updates FO LS arrival RoB of the Port Call		Double			Positive decimal value
	Diesel Oil Low Sulphur Remaining on Board (DO LS RoB)	Updates DO LS arrival RoB of the Port Call		Double			Positive decimal value
	Fresh Water Remaining on Board			Double			Positive decimal value

Arrival report

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length	Example	Client validation
	A port call key		Yes	Integer
	Vessel Report Type Value = ARR for Arrival Report.		Yes	String	4
	Report Date Local Time		Yes	Date
	Array of EventLog. For departure report this can be time of arrival, estimated time of berthing and departure. All dates are in local time. It's not necessary to include all 3 types. If you only want to update arrival then only include arrival EventLog Arrival event = ARR Berthing event = BRT Departure event = DEP	Updates and fixes Arrival Date and Time in Schedule Updates ETB and/or ETD in Schedule	Yes	Array of EventLogs		[{eventLogDate: "2023-01-03T03:34:00.000Z", event: "ARR"}, {eventLogDate: "2023-01-03T03:34:00.000Z", event: "BRT"}, {eventLogDate: "2023-01-03T03:34:00.000Z", event: "DEP"}]
	Distance Sailed Since departure	Updates actual distance sailed		Double			Positive decimal value
	Hours Stoppages			Double			Positive decimal value
	Hours in Service			Double			Positive decimal value
	Speed Made Good Since Last Report			Double			Positive decimal value
	Draft Aft			Double			Positive decimal value
	Draft Forward			Double			Positive decimal value
	Daily Fuel Oil Consumption			Double			Positive decimal value
	Daily Diesel Oil Consumption			Double			Positive decimal value
	Daily Fuel Oil Low Sulphur Consumption			Double			Positive decimal value
	Daily Diesel Oil Low Sulphur Consumption			Double			Positive decimal value
	Daily Net Fresh Water consumption			Double			Positive decimal value
	Fuel Oil Remaining on Board (FO RoB)	Updates and fixes Fuel Oil Remaining on Board (FO RoB) Arrival.		Double			Positive decimal value
	Diesel Oil Remaining on Board (DO RoB)	Updates and fixes Diesel Oil Remaining on Board (DO RoB) Arrival.		Double			Positive decimal value
	Fuel Oil Low Sulphur Remaining on Board (FO LS RoB)	Updates and fixes Fuel Oil Low Sulphur Remaining on Board (FO LS RoB) Arrival.		Double			Positive decimal value
	Diesel Oil Low Sulphur Remaining on Board (DO LS RoB)	Updates and fixes Diesel Oil Low Sulphur Remaining on Board (DO LS RoB) Arrival.		Double			Positive decimal value
	Fresh Water remaining on board			Double			Positive decimal value

In Port Report

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length	Example	Client validation
	A port call key		Yes	Integer
	Vessel Report Type Value = PORT for In Port Report.	Used to insert the correct type of Position Report and to locate the correct port call.	Yes	String	4
	Report Date Local Time		Yes	Date
	Array of EventLog. For in port report this can be time of berthing and estimated time of departure. All dates are in local time. It's not necessary to include all types. If you only want to update arrival then only include arrival EventLog Berthing event = BRT Departure event = DEP	Updates and fixes Berthed Time and Date Updates ETD in Schedule	Yes	Date		[{eventLogDate: "2023-01-03T03:34:00.000Z", event: "BRT"}, {eventLogDate: "2023-01-03T03:34:00.000Z", event: "DEP"}]
	Hours in Service			Double			Positive decimal value
				Integer	38
				Integer	38
	Average Wind Force. Beaufort.			Integer	38		0-12

Departure Report

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length	Example	Client validation
	A port call key		Yes
	Vessel Report Type. Value = DEP for Departure Report.		Yes	String	4
	Report Date Local Time		Yes	Date
	Array of EventLog. Local time. Add Departure Time as an Event Log with "DEP" event code	Updates and fixes Departure Time in Schedule.	Yes	Date		[{eventLogDate: "2023-01-03T03:34:00.000Z", event: "DEP"}]
	Distance To Next Port			Double			Positive decimal value
	Draft Aft			Double			Positive decimal value
	Draft Forward			Double			Positive decimal value
	Fuel Oil Remaining on Board (FO RoB)	Updates and fixes Fuel Oil Remaining on Board (FO RoB) departure.		Double			Positive decimal value
	Diesel Oil Remaining on Board (DO RoB)	Updates and fixes Diesel Oil Remaining on Board (DO RoB) departure.		Double			Positive decimal value
	Fuel Oil Low Sulphur Remaining on Board (FO LS RoB)	Updates and fixes Fuel Oil Low Sulphur Remaining on Board (FO LS RoB) departure.		Double			Positive decimal value
	Diesel Oil Low Sulphur Remaining on Board (DO LS RoB)	Updates and fixes Diesel Oil Low Sulphur Remaining on Board (FO LS RoB) departure.		Double			Positive decimal value
	Fresh Water Remaining on Board			Double			Positive decimal value
	Bunkered Fuel Oil Input Exact Figure According to BDR	Updates Fuel Oil bunkered for departure port call.		Double			Positive decimal value
	Bunkered Fuel Oil Low Sulphur Input exact figure according to the BDR	Updates Fuel Oil Low Sulphur bunkered for departure port call.		Double			Positive decimal value
	Bunkered Diesel Oil Input exact figure according to the BDR	Updates Diesel Oil bunkered for departure port call.		Double			Positive decimal value
	Bunkered Diesel Oil Low Sulphur Input exact figure according to the BDR	Updates Diesel Oil Low Sulphur bunkered for departure port call.		Double			Positive decimal value

Note

Fields that would be fixed will only fixed for voyages that are not estimated, allocated or scheduled

Example Messages

Updated for API version 2.0.0 using the new required date format yyyy-dd-MMThh:mi:ss to conform ISO 8601, (prior version has date format: yyyy-dd-MM hh:mi:ss)

Arrival

Departure

Noon

Port

Weather Data

When inserting weather data, use the ID from the Weather Data table:

Weather ID	Weather Description
	Clear Sky
	Sunny Day
	Partly Cloudy
	Sunny Intervals
	Dust
	Mist
	Fog
	Medium-Level Cloud
	Low-Level Cloud
	Light Rain Shower
	Drizzle
	Light Rain
	Heavy Rain Shower
	Heavy Rain
	Sleet Shower
	Sleet
	Hail Shower
	Hail
	Light Snow Shower
	Light Snow
	Heavy Snow Shower
	Heavy Snow
	Thundery Shower
	Thunder Storm
	Tropical Storm
	Haze

Direction

When inserting direction, use the ID from the Direction Table:

Direction id	Direction Description
	North
	South
	East
	West
	North/East
	North/West
	South/East
	South/West
	Various
	North/North/East
	East/North/East
	East/South/East
	South/South/East
	South/South/West
	West/South/West
	West/North/West
	North/North/West
	East/by/North
	East/by/South
	North/by/East
	North/by/West
	NE/by/East
	NE/by/north
	NW/by/North
	NW/by/West
	SE/by/East
	SE/by/South
	SW/by/South
	SW/by/West
	South/by/East
	South/by/West
	West/by/North
	West/by/South

Reason For Call

Code	Description
L	Loading
D	Discharging
C	Canal Passage
E	Extra Port
DD	Dry Dock
DEL	Delivery
RED	Redelivery
B	Bunkering
R	Repair
CL	Tank / Hold Cleaning
STS	Ship to Ship
W	Waiting
CC	Customs Clearance

Adding port calls

For long TC out voyages you might want to make it possible to add port calls from your vessel client. This section will explain how to do that.

To insert a port call the following API call can be used

POST ws/rest/PortCall { "port": 100949, "reasonForCall": "D", "portCallSequence": 3, "voyage": 8807674, "eventLogs": [ { "event": "BRT", "eventLogDate": "2023-05-09T16:02:13" }, { "event": "DEP", "eventLogDate": "2023-05-09T16:02:13" }, { "event": "ARR", "eventLogDate": "2023-05-09T16:02:13" } ]}

Field explanation: Port

A port key. Get a list of all ports with the below API call. We have over 10,000 ports. Please keep the number of requests to this endpoint as low as possible with caching. We do add new ports so if the vessel needs a newly added port it must be possible to update the cache, this will not happen often.

GET ws/rest/Port?filter=rpCode(NULL)&sort=portName(ASI) HTTP header disablemaxlimit: YES

Reason for call Any of the codes from the reason for call list above Port Call Sequence Should be port call sequence from last port call + 1. The port call sequence is returned in this API call to get port calls Voyage A voyage key. The voyage key is returned in this API call to get port calls. Event Logs There needs to be one eventLog for ARR (arrival), BRT (berthing), DEP (departure). Set the dates to todays date, they will then be calculated by the server. After inserting the port call, get the list of port calls again to get the ETA, ETB and ETD calculated by the server.