Bunker Consumption API

Consumption and bunker related figures for a given voyage are stored in VoyageBunker and Rob resources

VoyageBunker - Bunker summary of entire voyage

Each voyage is linked to one VoyageBunker object for each bunker category that is used during the voyage. VoyageBunker stores the following information/fields:

• bunkerCategory: the BunkerCategory connected to the VoyageBunker object

• consumption: total consumption of the bunker during the voyage

• cost: total bunker cost during the voyage

• price: average bunker price during the voyage

• priceVoyageStart: average bunker price at voyage start

• priceVoyageEnd: average bunker price at voyage end

• profitLoss: the charterer's total bunker profit/loss

• profitLossTcIn: the owner's total bunker profit/loss

• robDelivery: bunker ROB at delivery port

• robRedelivery: bunker ROB at redelivery port

• robVoyageStart: bunker ROB at voyage start

• voyage: the Voyage connected to the VoyageBunker

The following request fetches all VoyageBunker objects for a given voyage: https://BASE_URL/ws/rest/VoyageBunker?filter=voyage.key(EQ)20012412

Alternatively, a request can be sent against /Voyage/20012412 with voyageBunkers defined in the header fields. The JSON below is an example response of above requests. Two different bunkers are used during this voyage, FO and LS MGO.

[
    {
        "key": 20027578,
        "self": "https://BASE_URL/ws/rest/VoyageBunker/20027578",
        "bunkerCategory": {
            "key": 13575292,
            "self": "https://BASE_URL/ws/rest/BunkerCategory/13575292",
            "bunkerCategoryName": "FO",
        },
        "consumption": 530.0,
        "cost": 359340.0,
        "price": 678.0,
        "priceVoyageStart": 678.0,
        "priceVoyageEnd": 678.0,
        "profitLoss": 0.0,
        "profitLossTcIn": 0.0,
        "robDelivery": 0.0,
        "robRedelivery": 0.0,
        "robVoyageStart": 600.0,
        "voyage": {
            "key": 20012412,
            "self": "https://BASE_URL/ws/rest/Voyage/20012412",
        }
    },
    {
        "key": 20027579,
        "self": "https://BASE_URL/ws/rest/VoyageBunker/20027579",
        "bunkerCategory": {
            "key": 13575293,
            "self": "https://BASE_URL/ws/rest/BunkerCategory/13575293",
            "bunkerCategoryName": "LS MGO",
        },
        "consumption": 120.0,
        "cost": 93240.0,
        "price": 777.0,
        "priceVoyageStart": 777.0,
        "priceVoyageEnd": 777.0,
        "profitLoss": 0.0,
        "profitLossTcIn": 0.0,
        "robDelivery": 0.0,
        "robRedelivery": 0.0,
        "robVoyageStart": 200.0,
        "voyage": {
            "key": 20012412,
            "self": "https://BASE_URL/ws/rest/Voyage/20012412",
        }
    }
]

Rob - Bunkers per leg

Rob = remaining on board. Rob objects stores bunker related numbers for a single leg on the Voyage. A Rob is connected to a PortCall through EventLogs. Each EventLog contains an underlying Event with an eventCode attribute, and there are four eventCodes relevant for Robs - 'ARR', 'BRT', 'UBRT', and 'DEP', corresponding to Arrival, Berth, Unberth, and Departure, respectively.

As an example, the following request can be used to fetch all Robs for a given EventLog:

https://BASE_URL/ws/rest/EventLog/20027578

Assuming this EventLog is linked to the arrival event, the returned Robs contains at-sea consumption from previous port call, and fuel remaining upon arrival (for each bunker). Below is an example JSON response:

{
    "key": 20027578,
    "self": "https://BASE_URL/ws/rest/EventLog/20027578",
    "event": {
        "key": 13575292,
        "self": "https://BASE_URL/ws/rest/Event/13575292",
        "eventCode": "UBRT"
    },
    "robs": [
        {
            "key": 20027642,
            "self": "https://BASE_URL/ws/rest/Rob/20027642",
            "bunkerCategory": {
                "key": 916944,
                "self": "https://BASE_URL/ws/rest/BunkerCategory/916944",
                "bunkerCategoryCode": "FO"
            },
            "robFixed": false,
            "rob": 0.0,
            "consumption": 0.0
        },
        {
            "key": 20027649,
            "self": "https://BASE_URL/ws/rest/Rob/20027649",
            "bunkerCategory": {
                "key": 916947,
                "self": "https://BASE_URL/ws/rest/BunkerCategory/916947",
                "bunkerCategoryCode": "DL"
            },
            "robFixed": false,
            "rob": -4.61125655636663,
            "consumption": 0.0
        },
        {
            "key": 20027651,
            "self": "https://BASE_URL/ws/rest/Rob/20027651",
            "bunkerCategory": {
                "key": 916945,
                "self": "https://BASE_URL/ws/rest/BunkerCategory/916945",
                "bunkerCategoryCode": "FL"
            },
            "robFixed": false,
            "rob": 0.0,
            "consumption": 0.0
        },
        {
            "key": 20027663,
            "self": "https://BASE_URL/ws/rest/Rob/20027663",
            "bunkerCategory": {
                "key": 916946,
                "self": "https://BASE_URL/ws/rest/BunkerCategory/916946",
                "bunkerCategoryCode": "DO"
            },
            "robFixed": false,
            "rob": 0.0,
            "consumption": 0.0
        }
    ]
}

Note! To get the same response, the following header fields must be specified: {"event":{"eventCode":"*"},"robs": {"consumption":"*","robFixed":"*","rob": "*","bunkerCategory":{"bunkerCategoryCode":"*"}}}

To retrieve a list of Robs for a given EventLog, use the "robs" field. The number of Robs returned corresponds to the number of BunkerCategories in the system.

Rob fields

{
  "eventLog": {},
  "robFixed": true,
  "bunkerCategory": {},
  "rob": -1.7976931348623157e+308,
  "consumption": -1.7976931348623157e+308
}

Attributes breakdown:

• bunkerCategory - the BunkerCategory connected to the Rob

• eventLog - the EventLog connected to the Rob

• rob - remaining fuel onboard

• consumption - the bunker consumption between previous event and the connected event

• robFixed - identifies whether the rob value is fixed or not

How do we get the total consumption for a Port Call?

To get total consumption for a Port Call, Robs for all EventLogs on the PortCalls must be acquired.

The list of all EventLogs can be referenced directly from a PortCall:

Header fields: {"eventLogs": {"event":{"eventCode":"*"},"robs": {"consumption":"*","robFixed":"*","rob": "*","bunkerCategory":{"bunkerCategoryCode":"*"}}}}

Response:

{
    "key": 20027590,
    "self": "https://BASE_URL/ws/rest/PortCall/20027590",
    "eventLogs": [
        {
            "key": 20027578,
            "self": "https://BASE_URL/ws/rest/EventLog/20027578",
            "event": {
                "key": 13575292,
                "self": "https://BASE_URL/ws/rest/Event/13575292",
                "eventCode": "UBRT"
            },
            "robs": [
                {
                    "key": 20027642,
                    "self": "https://BASE_URL/ws/rest/Rob/20027642",
                    "bunkerCategory": {
                        "key": 916944,
                        "self": "https://BASE_URL/ws/rest/BunkerCategory/916944",
                        "bunkerCategoryCode": "FO"
                    },
                    "robFixed": false,
                    "rob": 0.0,
                    "consumption": 0.0
                },
                {
                    "key": 20027649,
                    "self": "https://BASE_URL/ws/rest/Rob/20027649",
                    "bunkerCategory": {
                        "key": 916947,
                        "self": "https://BASE_URL/ws/rest/BunkerCategory/916947",
                        "bunkerCategoryCode": "DL"
                    },
                    "robFixed": false,
                    "rob": -4.61125655636663,
                    "consumption": 0.0
                },
                {
                    "key": 20027651,
                    "self": "https://BASE_URL/ws/rest/Rob/20027651",
                    "bunkerCategory": {
                        "key": 916945,
                        "self": "https://BASE_URL/ws/rest/BunkerCategory/916945",
                        "bunkerCategoryCode": "FL"
                    },
                    "robFixed": false,
                    "rob": 0.0,
                    "consumption": 0.0
                },
                {
                    "key": 20027663,
                    "self": "https://BASE_URL/ws/rest/Rob/20027663",
                    "bunkerCategory": {
                        "key": 916946,
                        "self": "https://BASE_URL/ws/rest/BunkerCategory/916946",
                        "bunkerCategoryCode": "DO"
                    },
                    "robFixed": false,
                    "rob": 0.0,
                    "consumption": 0.0
                }
            ]
        },
        {
            "key": 20027584,
            "self": "https://BASE_URL/ws/rest/EventLog/20027584",
            "event": {
                "key": 1000051,
                "self": "https://BASE_URL/ws/rest/Event/1000051",
                "eventCode": "BRT"
            },
            "robs": [
                {
...

The output will consist of four EventLog objects, each containing four robs, making a total of sixteen robs (calculated by multiplying the number of event logs by four bunker categories). By adding up all the consumption attributes, you can get the total consumption per leg