# Release 7.0 - 7.2

## 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 date and time. The port events include ARRIVAL, BERTHED, UNBERTHED, and DEPARTURE. 
    * For example, to record the arrival date of a port call, an event log entry should include the ARRIVAL event along with the corresponding date
* robFo, robFl, robDl, robDo
  * An EventLog is also linked to ROBs to communicate the ROB of a specific bunker during a specific event. 
    * For instance, the robFo linked to the arrival event log is the ROB of FO on arrival. The robFo linked to the departure event log is the ROB of FO on departure, etc.

Fields impacting the port call's results will have **Major Change Factor** marked as yes, along with a description, on the [details](#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
* In Port Report
  * logs when the ship docks in the port. You can update both berthed and departure events here. This fixes the berthed date.
* Departure Report
  * logs when the ship leaves the port, fixing the departure date and ROB info

In order to include a [Remark](https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/remark) on the position report, a separate API request needs to be done after the report is created. 

## Details

### Noon Report 

<table data-full-width="true"><thead><tr><th>Field Name</th><th>Json Attribute</th><th width="154">Description</th><th>Mandatory in json</th><th>Major Change Factor</th><th width="209">Data type</th><th>Notes</th></tr></thead><tbody><tr><td>Report Type</td><td><code>vesselReportType</code></td><td>Determines the type of vessel report</td><td>yes</td><td></td><td>String</td><td>"NOON"</td></tr><tr><td>Noon Report Date</td><td>reportDateLocal</td><td>Date and time of creation of the report</td><td>yes</td><td></td><td>String</td><td>should be in this format:<br>"YYYY-MM-DDTHH:mm:ss"</td></tr><tr><td>Port Call</td><td>portCall</td><td>Port to update</td><td>yes</td><td></td><td>Long</td><td>key of the port call</td></tr><tr><td>Latitude</td><td>latitude</td><td>Current position</td><td>yes</td><td></td><td>Double</td><td></td></tr><tr><td>Longitude</td><td>longitude</td><td>Current position</td><td>yes</td><td></td><td>Double</td><td></td></tr><tr><td>Estimated Time of Arrival</td><td>eventLogs</td><td>Date and time of estimated time of arrival</td><td>yes</td><td>yes, updates PortCall's arrival date</td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/event-log">EventLog</a></td><td></td></tr><tr><td>FO ROB</td><td>robFo</td><td>Remaining bunkers of type FO at the time of reporting</td><td></td><td>yes, updates PortCall's arrival FO rob</td><td>Double</td><td></td></tr><tr><td>MGO ROB</td><td>robDo</td><td>Remaining bunkers of type MGO at the time of reporting</td><td></td><td>yes, updates PortCall's arrival MGO rob</td><td>Double</td><td></td></tr><tr><td>LS FO ROB</td><td>robFl</td><td>Remaining bunkers of type LS FO at the time of reporting</td><td></td><td>yes, updates PortCall's arrival LS FO rob</td><td>Double</td><td></td></tr><tr><td>LS MGO ROB</td><td>robDl</td><td>Remaining bunkers of type LS MGO at the time of reporting</td><td></td><td>yes, updates PortCall's arrival FO rob</td><td>Double</td><td></td></tr><tr><td>Wind Direction</td><td>windDirection</td><td>Determines current wind direction</td><td></td><td></td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/direction">Direction</a></td><td><a href="../vessel-report-master-data#direction-data">Click here for more details</a></td></tr><tr><td>Average Wind Force</td><td>averageWindForce</td><td>General wind conditions</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Sea Direction</td><td>seaDirection</td><td>Current sea direction</td><td></td><td></td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/direction">Direction</a></td><td><a href="../vessel-report-master-data#direction-data">Click here for more details</a></td></tr><tr><td>Average Sea State</td><td>averageSeaState</td><td>General sea conditions</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Weather</td><td>weather</td><td>Determines current weather</td><td></td><td></td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/weather">Weather</a></td><td><a href="../vessel-report-master-data#weather-data">Click here for more details</a></td></tr><tr><td>Distance Sailed</td><td>distanceSailed</td><td>Distance sailed</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Hours in Service</td><td>hoursInService</td><td>Number of hours in operation</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Main Engine RPM</td><td>rpmFromLastPort</td><td>RPM recorded from previous port</td><td></td><td></td><td>Double</td><td></td></tr></tbody></table>

### Noon report example

<details>

<summary>Noon Report sailing to a port</summary>

1. Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

```http
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
Authorization: Bearer ....
```

2. 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.&#x20;

```http
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
```

```json
{
    "vesselReportType": "NOON",
    "reportDateLocal": "2024-08-01T19:00:00",
    "portCall": 3345932, //key from the response of the PortCall query
    "latitude": 60.2139,
    "longitude": 4.5300,
    "eventLogs": [{"event": "ARR", "eventLogDate": "2024-08-02T02:36:00"}],
    "robFo": 234.56,
    "robDl": 250,
    "windDirection": 911643, 
    "weather": 950928, 
    "distanceSailed": 3150.00 

}
```

</details>

### Arrival Report

<table data-full-width="true"><thead><tr><th>Field Name</th><th>Json Attribute</th><th>Description</th><th>Mandatory</th><th>Major Change Factor</th><th>Data Type</th><th>Notes</th></tr></thead><tbody><tr><td>Vessel Report Type</td><td>vesselReportType</td><td>Determines the type of vessel report</td><td>yes</td><td></td><td>String</td><td>"ARR"</td></tr><tr><td>Port Call</td><td>portCall</td><td>Port to update</td><td>yes</td><td></td><td>Long</td><td>key of the port call</td></tr><tr><td>Arrival Date</td><td>eventLogs</td><td>Date and time of arrival on port</td><td>yes</td><td>yes, updates and fixes PortCall's arrival date</td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/event-log">EventLog</a></td><td>date should be in this format:<br>"YYYY-MM-DDTHH:mm:ss"</td></tr><tr><td>Arrival Report Date</td><td>reportDateLocal</td><td>Date and time of creation of the report</td><td></td><td></td><td>String</td><td>should be in this format:<br>"YYYY-MM-DDTHH:mm:ss"</td></tr><tr><td>Actual Distance Sailed Since Departure</td><td>distanceSailed</td><td>Distance in nm sailed from previous port</td><td></td><td>yes, updates the PortCall's actual distance sailed</td><td>Double</td><td></td></tr><tr><td>FO ROB</td><td>robFo</td><td>Remaining bunkers of type FO at the time of arrival</td><td></td><td>yes, updates and fixes PortCall's arrival FO ROB</td><td>Double</td><td></td></tr><tr><td>MGO ROB</td><td>robDo</td><td>Remaining bunkers of type MGO at the time of arrival</td><td></td><td>yes, updates and fixes PortCall's arrival MGO ROB</td><td>Double</td><td></td></tr><tr><td>LS FO ROB</td><td>robFl</td><td>Remaining bunkers of type LS FO at the time of arrival</td><td></td><td>yes, updates and fixes PortCall's arrival LS FO ROB</td><td>Double</td><td></td></tr><tr><td>LS MGO ROB</td><td>robDl</td><td>Remaining bunkers of type LS MGO at the time of arrival</td><td></td><td>yes, updates and fixes PortCall's arrival LS MGO ROB</td><td>Double</td><td></td></tr><tr><td>Hours Stoppage</td><td>hoursStoppages</td><td>Number of hours in stoppage of operation</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Hours In Service</td><td>hoursInService</td><td>Number of hours in operation</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Speed Made Good</td><td>speedMadeGood</td><td>Net speed when sailing to the port</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Draft Aft</td><td>draftAft</td><td>Vessel's draft aft</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Draft Forward</td><td>draftForward</td><td>Vessel's draft forward</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Daily FO</td><td>dailyFo</td><td>Daily FO consumption</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Daily LS FO</td><td>dailyFl</td><td>Daily LS FO consumption</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Daily MGO</td><td>dailyDo</td><td>Daily MGO consumption</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Daily LS MGO</td><td>dailyDl</td><td>Daily LS MGO consumption</td><td></td><td></td><td>Double</td><td></td></tr></tbody></table>

### Arrival Report example

<details>

<summary>Arrival report on port call</summary>

1. Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

```http
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
Authorization: Bearer ....
```

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

```http
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
```

```json
{
    "vesselReportType": "ARR",
    "reportDateLocal": "2024-08-02T02:58:00",
    "portCall": 3345932, //key from the response of the PortCall query
    "eventLogs": [{"event": "ARR", "eventLogDate": "2024-08-02T03:00:00"}],
    "robFo": 225.85,
    "robDl": 235.0
}
```

</details>

### In Port Report

<table data-full-width="true"><thead><tr><th>Field Name</th><th>Json Attribute</th><th>Description</th><th>Mandatory</th><th>Major Change Factor</th><th>Data Type</th><th>Notes</th></tr></thead><tbody><tr><td>Vessel Report Type</td><td>vesselReportType</td><td>Determines the type of vessel report</td><td>yes</td><td></td><td>String</td><td>"PORT"</td></tr><tr><td>Port Call</td><td>portCall</td><td>Port to update</td><td>yes</td><td></td><td>Long</td><td>key of the port call</td></tr><tr><td>In Port Report Date</td><td>reportDateLocal</td><td>Date and time of creation of the report</td><td></td><td></td><td>String</td><td>should be in this format:<br>"YYYY-MM-DDTHH:mm:ss"</td></tr><tr><td>Estimated time of berthing and departure</td><td>eventLogs</td><td>Estimated date and time of berthing and departure from port</td><td></td><td>yes, updates PortCall's berthing and departure dates</td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/event-log">EventLog</a></td><td>date should be in this format:<br>"YYYY-MM-DDTHH:mm:ss"</td></tr><tr><td>Hours In Service</td><td>hoursInService</td><td>Number of hours in operation</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Weather</td><td>weather</td><td>Current weather</td><td></td><td></td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/weather">Weather</a></td><td>Click here for more details</td></tr><tr><td>Wind Direction</td><td>windDirection</td><td>Current wind direction</td><td></td><td></td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/direction">Direction</a></td><td>Click here for more details</td></tr><tr><td>Average Wind Force</td><td>averageWindForce</td><td>General wind conditions</td><td></td><td></td><td>Double</td><td></td></tr></tbody></table>

### In Port report example

<details>

<summary>In port report on a port call</summary>

1. Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

```http
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
Authorization: Bearer ....
```

2. Generate a report to fix the berth date to August 3rd 2024 10:36, and log the estimated departure date August 4th 2024 18:36 to , sunny weather, East wind direction, hours in service, average wind force status in port

```http
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
```

```json
{
    "vesselReportType": "PORT",
    "reportDateLocal": "2024-08-03T18:00:00",
    "portCall": 3345932, //key from the response of the PortCall request
    "hoursInService": 225.85,
    "eventLogs":[{"event": "BRT", "eventLogDate": "2024-08-03T10:36:00"}, 
        {"event": "DEP", "eventLogDate": "2024-08-04T18:36:00"}],
    "weather": 950927,
    "windDirection": 911638,
    "averageWindForce": 1
}
```

</details>

### Depature Report

<table data-full-width="true"><thead><tr><th>Field Name</th><th>Json Attribute</th><th>Description</th><th>Mandatory</th><th>Major Change Factor</th><th>Data Type</th><th>Notes</th></tr></thead><tbody><tr><td>Vessel Report Type</td><td>vesselReportType</td><td>Determines the type of vessel report</td><td>yes</td><td></td><td>String</td><td>"DEP"</td></tr><tr><td>Port Call</td><td>portCall</td><td>Port to update</td><td>yes</td><td></td><td>Long</td><td>key of the port call</td></tr><tr><td>Departure date</td><td>eventLogs</td><td>Date and time of departure from port</td><td>yes</td><td>yes, updates and fixes PortCall's departure date</td><td><a href="https://dataloy-systems.stoplight.io/docs/dataloyModel/branches/API%2F7.0/model/schemas/event-log">EventLog</a></td><td>date should be in this format:<br>"YYYY-MM-DDTHH:mm:ss"</td></tr><tr><td>Departure Report Date</td><td>reportDateLocal</td><td>Date and time of creation of the report</td><td></td><td></td><td>String</td><td>should be in this format:<br>"YYYY-MM-DDTHH:mm:ss"</td></tr><tr><td>FO ROB</td><td>robFo</td><td>Remaining bunkers of type FO at the time of departure</td><td></td><td>yes, updates and fixes PortCall's departure FO ROB</td><td>Double</td><td></td></tr><tr><td>LS FO ROB</td><td>robFl</td><td>Remaining bunkers of type LS FO at the time of departure</td><td></td><td>yes, updates and fixes PortCall's departure FO ROB</td><td>Double</td><td></td></tr><tr><td>MGO ROB</td><td>robDo</td><td>Remaining bunkers of type MGO at the time of departure</td><td></td><td>yes, updates and fixes PortCall's departure FO ROB</td><td>Double</td><td></td></tr><tr><td>LS MGO ROB</td><td>robDl</td><td>Remaining bunkers of type LS MGO at the time of departure</td><td></td><td>yes, updates and fixes PortCall's departure FO ROB</td><td>Double</td><td></td></tr><tr><td>Distance to next port</td><td>distanceToNextPort</td><td>Distance in nm to next port</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Draft Aft</td><td>draftAft</td><td>Vessel's draft aft</td><td></td><td></td><td>Double</td><td></td></tr><tr><td>Draft Forward</td><td>draftForward</td><td>Vessel's draft forward</td><td></td><td></td><td>Double</td><td></td></tr></tbody></table>

### Departure report example

<details>

<summary>Departure report on a port call</summary>

1. Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

```http
GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
Authorization: Bearer ....
```

2. Generate a report that fixes the departure date to 5th August 2024 08:30&#x20;

```http
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
```

```json
{
    "vesselReportType": "DEP",
    "reportDateLocal": "2024-08-05T08:30:00",
    "portCall": 3345932, //key from the response of the PortCall request
    "eventLogs": [{"event": "DEP", "eventLogDate": "2024-08-05T08:30:00"}],
    "robFo": 225.85,
    "robDl": 198.75,
    "distanceToNextPort": 350
}
```

</details>

### More examples

<details>

<summary>Arrival report with Remark</summary>

1. Send first this request

```http
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
```

```json
{
    "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
}
```

2. 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"
}
```

</details>

<details>

<summary>Arrival report where port call key and voyage key are not known, using voyage.referenceNo and port name</summary>

1. Fetch the port call key

{% code fullWidth="true" %}

```
GET /ws/rest/PortCall?filter=voyage.voyageHeader.referenceNo(LKIC)TST001&port.portName(LKIC)Bergen case insensitive HTTP/1.1
Authorization: Bearer ....
```

{% endcode %}

2. Generate arrival report

```http
POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....
```

```json
{
    "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
}
```

</details>