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:

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

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

PreviousRelease 7.0 - 7.2NextLegacy version (6.26 - 6.28)

Last updated

Was this helpful?