🖍️
Dataloy VMS API Documentation
API Release 8.5
API Release 8.5
  • Dataloy VMS API
  • Dataloy Rest API
    • What is it?
    • Authentication / Authorization
    • Getting Started
    • Data Model
    • Filtering
    • Sorting
    • Pagination
    • Adjust Number of Fields to be Returned from a Request
    • Webhooks
      • Webhook example
      • Expressions Made Easy
      • Webhooks - New functionalities
    • Master data Objects
    • Attachments
    • Audit Log
  • User Guides
    • Accounting Integration API
      • Invoicing
      • Payments/Receipts
      • Voyages
      • Business Partners
      • Exchange Rates
      • Bunker Transactions
      • Actuals
      • Autopost Invoices
      • Accruals
    • Schedule API
    • Bunker Order Integration API
    • Service Order Integration API
    • Vessel Report
      • Release 8.5
      • Release 8.0
      • Release 7.3 - 7.12
      • Release 7.0 - 7.2
      • Release 6.29 - 6.46
      • Legacy version (6.26 - 6.28)
      • Vessel report master data
    • Bunker Consumption API
    • Left join in API queries
    • Enterprise functionalities
      • Versioning
      • Endpoint access control
      • Data access control via target object
      • Data access control via target object and security role
      • Data access control at object level
      • Fields access control
      • Alert Scripts
      • Websockets
      • Bulk Deletion
      • Copy objects
      • OR and AND operators in API queries
      • Sub queries
      • XML Transformation
      • Expressions
      • Bulk Update
Powered by GitBook
On this page
  • Port Call
  • Noon report
  • Arrival report
  • In Port Report
  • Departure Report
  • Example Messages
  • Port
  • Weather Data
  • Direction
  • Reason For Call
  • Adding port calls

Was this helpful?

Export as PDF
  1. User Guides
  2. Vessel Report

Release 6.29 - 6.46

PreviousRelease 7.0 - 7.2NextLegacy version (6.26 - 6.28)

Was this helpful?

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? 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:

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

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

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

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

Wind Direction ()

One of the values from this list:

Sea Direction ()

One of the values from this list:

Weather.

One of the values from this list:

Weather.

One of the values from this list:

Wind Direction.

One of the values from this list:

Updated for 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)

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 Voyage A voyage key. The voyage key is returned in . 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, again to get the ETA, ETB and ETD calculated by the server.

portCall
vesselReportType
reportDateLocal
latitude
longitude
eventLogs
trueCourse
distanceSailed
hoursInService
distanceToNextPort
speedMadeGood
windDirection
averageWindForce
seaDirection
averageSeaState
bhpMainEngineIndicatedRpm
dailyFo
dailyDo
dailyFl
dailyDl
dailyFw
robFo
robDo
robFl
robDl
robFw
portCall
vesselReportType
reportDateLocal
eventLogs
distanceSailed
hoursStoppages
hoursInService
speedMadeGood
draftAft
draftForward
dailyFo
dailyDo
dailyFl
dailyDl
dailyFw
robFo
robDo
robFl
robDl
robFw
portCall
vesselReportType
reportDateLocal
eventLogs
hoursInService
weather
windDirection
averageWindForce
portCall
vesselReportType
reportDateLocal
eventLogs
distanceToNextPort
draftAft
draftForward
robFo
robDo
robFl
robDl
robFw
foBunkered
flBunkered
doBunkered
dlBunkered
{
    "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,
}
{
    "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,
}
{
    "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,
}
{
    "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
}
950926
950927
950928
950929
950930
950931
950932
950933
950934
950935
950936
950937
950938
950939
950940
950941
950942
950943
950944
950945
950946
950947
950948
950949
950950
950951
911636
911637
911638
911639
911640
911641
911642
911643
913753
913902
913903
913904
913905
913906
913907
913908
913909
916765
916766
916767
916768
916769
916770
916771
916772
916773
916774
916775
916776
916777
916778
916779
916780
contact Dataloy
contact Dataloy
API version 2.0.0
Get in touch
Port Call
Noon report
Arrival Report
In Port Report
Departure Report
Example Messages
Weather Data
Direction
Reason For Call
Adding port calls
this API call to get port calls
this API call to get port calls
get the list of port calls
direction
direction
direction
direction
weather
weather
weather
weather
direction
direction