Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 39 Next »


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&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
MandatoryTypeLengthExampleClient validation
portCall
A port call key
Yes



vesselReportType
  • Vessel Report Type
  • Value = NOON for Noon Report

YesString4

reportDateLocal
Report Date Local Time
YesDate


latitude
Position Latitude (Decimal Degrees)

Double512.575

User input should be degrees, minutes and seconds. For example: 12° 34'5 N

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)

Double5123.76Same 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

Integer38

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)

Integer38
One of the values from this list: direction
averageWindForce
Wind Force. Beaufort.

Integer38
0-12
seaDirection
Sea Direction (direction)


Integer38
One of the values from this list: direction
averageSeaState
Sea State. Integer from 0 - 9.

Integer38
0-9
weatherWeather. weather

Integer38
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
MandatoryTypeLengthExampleClient validation
portCall
A port call key
YesInteger


vesselReportType
Vessel Report Type
Value = ARR for Arrival Report.
YesString4

reportDateLocal
Report Date Local Time
YesDate


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

YesArray 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 departureUpdates 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
MandatoryTypeLengthExampleClient validation
portCall
A port call key
YesInteger


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.YesString4

reportDateLocal
Report Date Local Time
YesDate


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

YesDate

[{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

Integer38
One of the values from this list: weather
windDirection
Wind Direction. direction 

Integer38
One of the values from this list: direction 
averageWindForce
Average Wind Force. Beaufort.

Integer38
0-12


Departure Report

JSON Field Name
Description
Affects Dataloy VMS
MandatoryTypeLengthExampleClient validation
portCall
A port call key
Yes



vesselReportType
Vessel Report Type.
Value = DEP for Departure Report.
YesString4

reportDateLocal
Report Date Local Time
YesDate


eventLogs

Array of EventLog. Local time.

Add Departure Time as an Event Log with "DEP" event code


Updates and fixes Departure Time in Schedule. 

YesDate

[{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 IDWeather 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 idDirection 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

CodeDescription
LLoading
DDischarging
CCanal Passage
EExtra Port
DDDry Dock
DELDelivery
REDRedelivery
BBunkering
RRepair
CL
Tank / Hold Cleaning
STSShip to Ship
WWaiting
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 this list.

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.
  • No labels