Release 8.0
PositionReport is used to update the status of an ongoing voyage's port calls.
Overview
Position reports update a port call's sailing, arrival, in port, and departure status. Most fields in the PositionReport object will only provide information, while a few affect the port call's results.
The following fields will affect the port call's results:
eventLogs
An EventLog captures port events along with their dates and times. The port events include ARRIVAL, BERTHED, UNBERTHED, and DEPARTURE. To record the arrival date of a port call, an event log entry should include the ARRIVAL event along with the corresponding date.
An EventLog is also linked to ROBs to communicate the Remaining on Board (ROB) of a specific bunker during a specific event. For instance, the Rob of Fuel Oil (FO) on arrival will be specified by having the
robs
field on the arrival event log entry, containing the key of the FO bunker category.
Fields impacting the port call's results will have Major Change Factor marked as yes, along with a description, on the details.
PositionReport can be one of these types:
Noon Report
logs the ship's status at sea, updating the estimated arrival date and ROB info
Arrival Report
logs when the ship arrives in the port, fixing the arrival date and ROB info
Berth Report
logs when the ship has berthed in the port, fixing the berthed date and ROB info
Unberth Report
logs when the ship has unberthed in the port, fixing the unberthed date and ROB info
In Port Report
logs supplementary information such as hours in service, weather, wind direction and average wind direction when the ship is docked.
Departure Report
logs when the ship leaves the port, fixing the departure date and ROB info
In order to include a Remark on the position report, a separate API request must be made after the report is created. See here for an example.
Details
Noon Report
Noon report example
Noon Report sailing to a port
Assuming the voyage key, and port call sequence are known, get the PortCall key with this query and headers:
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....
An example of the response could be found here
Generate a Noon Report for the vessel that has sailed 3150 nm to the queried PortCall, with South/West wind direction and partly cloudy weather. Arrival LS MGO robs are also updated to 250
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "NOON",
"reportDateLocal": "2024-08-01T19:00:00",
"portCall": 6130402, //key from the response of the PortCall query
"latitude": 60.2139,
"longitude": 4.5300,
"eventLogs": [
{
"key": 6130395, //arrival event log key
"eventLogDate": "2024-08-02T02:36:00",
"robs": [
{
"key": 6130460, //arrival DL Rob key
"rob": 250
}
]
}
],
"windDirection": 911643,
"weather": 950928,
"distanceSailed": 3150.00
}
Arrival Report
Arrival report example
Arrival report on port call
Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....
Example of the response can be found here
Generate a report for arrival at 2nd August 2024 03:00 with arrival FO ROB at 225.85 mt and arrival LS MGO ROB at 235 mt
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "ARR",
"reportDateLocal": "2024-08-01T19:00:00",
"portCall": 6130402, //key from the response of the PortCall query
"latitude": 60.2139,
"longitude": 4.5300,
"eventLogs": [
{
"key": 6130395, //arrival event log key
"eventLogDate": "2024-08-02T03:00:00",
"robs": [
{
"key": 6130460, //arrival DL Rob key
"rob": 235
},
{
"key": 6130469, //arrival FO Rob key
"rob": 225.85
}
]
}
]
}
Berth Report
Berth report example
Berth report on a port call
Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....
Generate a report that has berthed 3rd August 2024 08:00 with berth FO rob at 225 mt and DL rob at 220 mt
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "BRT",
"reportDateLocal": "2024-08-03T10:36:00",
"portCall": 6130402, //key from the response of the PortCall query
"eventLogs": [
{
"key": 6130394, //berth event log key
"eventLogDate": "2024-08-03T10:36:00",
"robs": [
{
"key": 6130441, //berth DL rob key
"rob": 220
},
{
"key":6130468, //berth FO rob key
"rob": 225
}
]
}
]
}
Unberth Report
Unberth report example
Unberth report on a port call
Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....
Example response can be found here
Generate a report that has unberthed 5th August 2024 08:00, FO unberth ROB at 225 mt, DL unberth at 218.5 mt
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "UBRT",
"reportDateLocal": "2024-08-05T08:00:00",
"portCall": 6130402, //key from the response of the PortCall query
"eventLogs": [
{
"key": 6130393, //unberth event log key
"eventLogDate": "2024-08-05T08:00:00",
"robs": [
{
"key": 6130453, //berth DL rob key
"rob": 218.5
},
{
"key":6130443, //unberth FO rob key
"rob": 225
}
]
}
]
}
In Port Report
In port report example
In port report on a port call
Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....
Generate a report to log sunny weather, East wind direction, hours in service, average wind force status in port
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "PORT",
"reportDateLocal": "2024-08-03T18:00:00",
"portCall": 3345932, //key from the response of the PortCall request
"hoursInService": 225.85,
"weather": 950927,
"windDirection": 911638,
"averageWindForce": 1
}
Departure Report
Departure Report example
Departure report on a port call
Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....
Example of the response can be found here
Generate a report that has fixes the departure date to 5th August 2024 08:30, departure FO rob at 225 mt and departure DL rob at 215 mt
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "DEP",
"reportDateLocal": "2024-08-05T08:30:00",
"portCall": 6130402, //key from the response of the PortCall query
"eventLogs": [
{
"key": 6130397, //departure event log key
"eventLogDate": "2024-08-05T08:30:00",
"robs": [
{
"key": 6130465, //departure DL rob key
"rob": 215
},
{
"key":6130449, //departure FO rob key
"rob": 225
}
]
}
]
}
More examples
PortCall query with "eventLogs" fields response
[
{
"key": 6130402,
"eventLogs": [
{
"key": 6130391,
"event": {
"key": 1000051,
"eventCode": "BRT"
},
"robs": [
{
"key": 6130447,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
},
{
"key": 6130450,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
},
{
"key": 6130462,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130464,
"rob": 249.75,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
}
]
},
{
"key": 6130396,
"event": {
"key": 6088041,
"eventCode": "UBRT"
},
"robs": [
{
"key": 6130444,
"rob": 249.75,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
},
{
"key": 6130452,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130459,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
},
{
"key": 6130470,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
}
]
},
{
"key": 6130392,
"event": {
"key": 1000052,
"eventCode": "DEP"
},
"robs": [
{
"key": 6130440,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
},
{
"key": 6130448,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130454,
"rob": 249.75,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
},
{
"key": 6130458,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
}
]
},
{
"key": 6130395,
"event": {
"key": 1000050,
"eventCode": "ARR"
},
"robs": [
{
"key": 6130451,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130460,
"rob": 250.0,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
},
{
"key": 6130467,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
},
{
"key": 6130469,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
}
]
}
]
},
{
"key": 6130400,
"eventLogs": [
{
"key": 6130394,
"event": {
"key": 1000051,
"eventCode": "BRT"
},
"robs": [
{
"key": 6130441,
"rob": 230.53559444257462,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
},
{
"key": 6130457,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130461,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
},
{
"key": 6130468,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
}
]
},
{
"key": 6130398,
"event": {
"key": 1000050,
"eventCode": "ARR"
},
"robs": [
{
"key": 6130445,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130456,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
},
{
"key": 6130463,
"rob": 230.78559444257462,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
},
{
"key": 6130471,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
}
]
},
{
"key": 6130393,
"event": {
"key": 6088041,
"eventCode": "UBRT"
},
"robs": [
{
"key": 6130442,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130443,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
},
{
"key": 6130453,
"rob": 230.53559444257462,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
},
{
"key": 6130466,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
}
]
},
{
"key": 6130397,
"event": {
"key": 1000052,
"eventCode": "DEP"
},
"robs": [
{
"key": 6130446,
"rob": 0.0,
"bunkerCategory": {
"key": 916945,
"bunkerCategoryCode": "FL"
}
},
{
"key": 6130449,
"rob": 0.0,
"bunkerCategory": {
"key": 916944,
"bunkerCategoryCode": "FO"
}
},
{
"key": 6130455,
"rob": 0.0,
"bunkerCategory": {
"key": 916946,
"bunkerCategoryCode": "DO"
}
},
{
"key": 6130465,
"rob": 230.53559444257462,
"bunkerCategory": {
"key": 916947,
"bunkerCategoryCode": "DL"
}
}
]
}
]
}
]
Arrival report with Remark
Send first this request
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "ARR",
"reportDateLocal": "2024-08-02T02:58:00",
"portCall": 3345932, //key from the response of the PortCall request
"eventLogs": [{"event": "ARR", "eventLogDate": "2024-08-02T03:00:00"}],
"robFo": 225.85,
"robDl": 235.0
}
The response of the query above returns the PositionReport key. Generate a Remark on the arrival position report that says "Arrival on the port remark":
POST /ws/rest/Remark HTTP/1.1
{
source: 5535223, //key from the response of PositionReport request
"remark": "Arrival on the port remark"
}
Arrival report where port call key and voyage key are not known, using voyage.referenceNo and port name
Fetch the port call key
GET /ws/rest/PortCall?filter=voyage.voyageHeader.referenceNo(LKIC)TST001&port.portName(LKIC)Bergen case insensitive HTTP/1.1
Authorization: Bearer ....
Generate arrival report
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
{
"vesselReportType": "ARR",
"reportDateLocal": "2024-08-02T02:58:00",
"portCall": 3345932, //key from the response of the PortCall request
"eventLogs": [{"event": "ARR", "eventLogDate": "2024-08-02T03:00:00"}],
"robFo": 225.85,
"robDl": 235.0
}
Last updated