New Vessel Report API

This page explains how to create vessel report integration with Dataloy API and is valid from API version 6.29

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

Chapter Contents:

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

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 header
fields: {"voyage":{"key":"*"},"reasonForCall":{"reasonForCall":"*", "reasonForCallDesc":"*"}, "portCallSequence":"*", "port":{"portName":"*"},"eventLogs":{"eventLogDate":"*","event":{"eventCode":"*"}}}

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

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
portCall	A port call key		Yes
vesselReportType	Vessel Report Type Value = NOON for Noon Report		Yes	String	4
reportDateLocal	Report Date Local Time		Yes	Date
latitude	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;
longitude	Position Longitude (Decimal Degrees)			Double	5	123.76	Same validation as for latitude
eventLogs	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"}]
trueCourse	True Course			Integer	38
distanceSailed	Distance Sailed Since Last Report			Double			Positive decimal value
hoursInService	Hours in Service Since Last Report			Double			Positive decimal value
distanceToNextPort	Distance To Go			Double			Positive decimal value
speedMadeGood	Speed Made Good			Double			Positive decimal value
windDirection	Wind Direction (direction)			Integer	38		One of the values from this list: direction
averageWindForce	Wind Force. Beaufort.			Integer	38		0-12
seaDirection	Sea Direction (direction)			Integer	38		One of the values from this list: direction
averageSeaState	Sea State. Integer from 0 - 9.			Integer	38		0-9
weather	Weather. weather			Integer	38		One of the values from this list: weather
bhpMainEngineIndicatedRpm	Main Engine RPM Since Last Report			Double			Positive decimal value
dailyFo	Daily Fuel Oil Consumption			Double			Positive decimal value
dailyDo	Daily Diesel Oil Consumption			Double			Positive decimal value
dailyFl	Daily Fuel Oil Low Sulphur Consumption			Double			Positive decimal value
dailyDl	Daily Diesel Oil Low Sulphur Consumption			Double			Positive decimal value
dailyFw	Daily Net Fresh Water Consumption			Double			Positive decimal value
robFo	Fuel Oil Remaining on Board (FO RoB)	Updates FO arrival RoB of the Port Call		Double			Positive decimal value
robDo	Diesel Oil Remaining on Board (DO RoB)	Updates DO arrival RoB of the Port Call		Double			Positive decimal value
robFl	Fuel Oil Low Sulphur Remaining on Board (FO LS RoB)	Updates FO LS arrival RoB of the Port Call		Double			Positive decimal value
robDl	Diesel Oil Low Sulphur Remaining on Board (DO LS RoB)	Updates DO LS arrival RoB of the Port Call		Double			Positive decimal value
robFw	Fresh Water Remaining on Board			Double			Positive decimal value

Arrival report

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length	Example	Client validation
portCall	A port call key		Yes	Integer
vesselReportType	Vessel Report Type Value = ARR for Arrival Report.		Yes	String	4
reportDateLocal	Report Date Local Time		Yes	Date
eventLogs	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"}]
distanceSailed	Distance Sailed Since departure	Updates actual distance sailed		Double			Positive decimal value
hoursStoppages	Hours Stoppages			Double			Positive decimal value
hoursInService	Hours in Service			Double			Positive decimal value
speedMadeGood	Speed Made Good Since Last Report			Double			Positive decimal value
draftAft	Draft Aft			Double			Positive decimal value
draftForward	Draft Forward			Double			Positive decimal value
dailyFo	Daily Fuel Oil Consumption			Double			Positive decimal value
dailyDo	Daily Diesel Oil Consumption			Double			Positive decimal value
dailyFl	Daily Fuel Oil Low Sulphur Consumption			Double			Positive decimal value
dailyDl	Daily Diesel Oil Low Sulphur Consumption			Double			Positive decimal value
dailyFw	Daily Net Fresh Water consumption			Double			Positive decimal value
robFo	Fuel Oil Remaining on Board (FO RoB)	Updates and fixes Fuel Oil Remaining on Board (FO RoB) Arrival.		Double			Positive decimal value
robDo	Diesel Oil Remaining on Board (DO RoB)	Updates and fixes Diesel Oil Remaining on Board (DO RoB) Arrival.		Double			Positive decimal value
robFl	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
robDl	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
robFw	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
portCall	A port call key		Yes	Integer
vesselReportType	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
reportDateLocal	Report Date Local Time		Yes	Date
eventLogs	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"}]
hoursInService	Hours in Service			Double			Positive decimal value
weather	Weather. weather			Integer	38		One of the values from this list: weather
windDirection	Wind Direction. direction			Integer	38		One of the values from this list: direction
averageWindForce	Average Wind Force. Beaufort.			Integer	38		0-12

Departure Report

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length	Example	Client validation
portCall	A port call key		Yes
vesselReportType	Vessel Report Type. Value = DEP for Departure Report.		Yes	String	4
reportDateLocal	Report Date Local Time		Yes	Date
eventLogs	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"}]
distanceToNextPort	Distance To Next Port			Double			Positive decimal value
draftAft	Draft Aft			Double			Positive decimal value
draftForward	Draft Forward			Double			Positive decimal value
robFo	Fuel Oil Remaining on Board (FO RoB)	Updates and fixes Fuel Oil Remaining on Board (FO RoB) departure.		Double			Positive decimal value
robDo	Diesel Oil Remaining on Board (DO RoB)	Updates and fixes Diesel Oil Remaining on Board (DO RoB) departure.		Double			Positive decimal value
robFl	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
robDl	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
robFw	Fresh Water Remaining on Board			Double			Positive decimal value
foBunkered	Bunkered Fuel Oil Input Exact Figure According to BDR	Updates Fuel Oil bunkered for departure port call.		Double			Positive decimal value
flBunkered	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
doBunkered	Bunkered Diesel Oil Input exact figure according to the BDR	Updates Diesel Oil bunkered for departure port call.		Double			Positive decimal value
dlBunkered	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

{
	"vesselReportType":"ARR",
	"portCall": 1009999,
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "event":"ARR"}, 
			{"eventLogDate":"2013-12-24T00:00:00", "event":"BRT"}, {"eventLogDate":"2013-12-24T00:00:00", "event":"DEP"}],
	"distanceSailed":10,
	"distanceSailedSinceDeparture":10,
	"hoursInService":10,
	"hoursStoppages":10,
	"speedMadeGood":10,
	"draftAft":10,
	"draftForward":10,
	"dailyFo":10,
	"dailyDo":10,
	"dailyFl":10,
	"dailyDl":10,
	"dailyFw":10,
	"robFo":10,
	"robDo":10,
	"robFl":10,
	"robDl":10,
	"robFw":10,
}

Departure

 {
	"vesselReportType":"DEP",
	"portCall": 1009999,
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "event":"DEP"}, {"eventLogDate":"2013-12-24T00:00:00", "event":"ARR"}],
	"distanceToNextPort":10,
	"draftAft":10,
	"draftForward":10,
	"robFo":10,
	"robDo":10,
	"robFl":10,
	"robDl":10,
	"robFw":10,
	"foBunkered":10,
	"flBunkered":10,
	"doBunkered":10,
	"dlBunkered":10,
}

Noon

{
	"reportTypeCode":"NOON",
	"portCall": 1009999,
	"latitude":10.17,
	"longitude":10.17,
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "event":"ARR"}, 
			{"eventLogDate":"2013-12-24T00:00:00", "event":"BRT"}, {"eventLogDate":"2013-12-24T00:00:00", "event":"DEP"}],
	"trueCourse":10,
	"distanceSailed":10,
	"hoursInService":10,
	"distanceToNextPort":10,
	"speedMadeGood":10,
	"windDirection":911638,
	"averageWindForce":0,
	"seaDirection":911638,
	"averageSeaState":1,
	"bhpMainEngineIndicatedRpm":10,
	"dailyFo":10,
	"dailyDo":10,
	"dailyFl":10,
	"dailyDl":10,
	"dailyFw":10,
	"robFo":10,
	"robDo":10,
	"robFl":10,
	"robDl":10,
	"robFw":10,
}

Port

{
	"vesselReportType":"PORT",
	"portCall": 1009999,
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "event":"BRT"}, {"eventLogDate":"2013-12-24T00:00:00", "event":"DEP"}],
	"hoursInService":"20",
	"weather":950936,
	"windDirection":913903,
	"averageWindForce":1,
}

Weather Data

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

Weather ID	Weather Description
950926	Clear Sky
950927	Sunny Day
950928	Partly Cloudy
950929	Sunny Intervals
950930	Dust
950931	Mist
950932	Fog
950933	Medium-Level Cloud
950934	Low-Level Cloud
950935	Light Rain Shower
950936	Drizzle
950937	Light Rain
950938	Heavy Rain Shower
950939	Heavy Rain
950940	Sleet Shower
950941	Sleet
950942	Hail Shower
950943	Hail
950944	Light Snow Shower
950945	Light Snow
950946	Heavy Snow Shower
950947	Heavy Snow
950948	Thundery Shower
950949	Thunder Storm
950950	Tropical Storm
950951	Haze

Direction

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

Direction id	Direction Description
911636	North
911637	South
911638	East
911639	West
911640	North/East
911641	North/West
911642	South/East
911643	South/West
913753	Various
913902	North/North/East
913903	East/North/East
913904	East/South/East
913905	South/South/East
913906	South/South/West
913907	West/South/West
913908	West/North/West
913909	North/North/West
916765	East/by/North
916766	East/by/South
916767	North/by/East
916768	North/by/West
916769	NE/by/East
916770	NE/by/north
916771	NW/by/North
916772	NW/by/West
916773	SE/by/East
916774	SE/by/South
916775	SW/by/South
916776	SW/by/West
916777	South/by/East
916778	South/by/West
916779	West/by/North
916780	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 you 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.