Fleet Management

Introduction to Fleets

The FleetManagement service provides an easy way for users to programmatically interact with the Oceanbolt API and manage their fleet resources.

A Fleet is a user defined collection of vessels. Fleets can be used to a group vessels of particular intererst (a users own fleet, or the fleet of a competitor for example).

Fleets are available in various parts of the Oceanbolt platform, facilitating for easy monitoring and querying of the vessels in the fleet.

Fleets consists of Vessels, and Vessels can be added/removed from a Fleet using either the API or the dashboard. Users can define custom metadata for the vessels when they add the vessels. This enables combining Oceanbolt data with internal data on the vessel (such as current route, operator name, current index, Vezon Imos platform link etc.).

Shared Fleets

By default Fleets are private to the user who created them. Fleets can however be shared with the rest of the organization if fleet creator enables sharing the given Fleet.

Batch Methods

The API provides several “batch” methods, which make it easy to modify a fleet using batch operations. This can for example facilite easy updating of an organizations’s fleet list in the Oceanbolt platform.

For example the FleetManagent SDK provides the following convenience functions to easily update a fleet from the basis of a CSV sheet:

FleetManagement Client

class oceanbolt.sdk.fleet.FleetManagement(client: oceanbolt.sdk.client.APIClient)[source]

FleetManagement provides an interface to manage fleets for clients

create_fleet()[source]

Creates a new Fleet for the current user.

list_fleets()[source]

Lists Fleets for the current user (or fleets that are shared with the current user)

describe_fleet()[source]

Retrieves fleet by Fleet id.

delete_fleet()[source]

Deletes a Fleet for the current user.

rename_fleet()[source]

Changes the name of a Fleet.

share_fleet()[source]

Sets the shared status of the Fleet to be shared.

unshare_fleet()[source]

Sets the shared status of the Fleet to be not shared.

list_vessels()[source]

Retrieves list of vessels in a Fleet.

add_vessel()[source]

Adds new vessel to a Fleet. A maximum of 1000 vessels can be added to a fleet.

update_vessel()[source]

Updates existing metadata for a Vessel.

delete_vessel()[source]

Removes a vessel from a Fleet.

batch_add_vessels()[source]

Batch adds vessels into a Fleet. A maximum of 1000 vessels can be added to a fleet.

batch_add_vessels_from_csv()[source]

Batch adds vessels into a Fleet sourced from a CSV file. A maximum of 1000 vessels can be added to a fleet.

drop_vessels()[source]

Drops all the vessels currently in a fleet.

replace_vessels()[source]

Replaces the existing vessels in a Fleet with a batch of new vessels. This is equivalent to first calling DropVessels and then calling BatchAddVessels. A maximum of 1000 vessels can be added to a fleet.

replace_vessels_from_csv()[source]

Replaces the existing vessels in a Fleet with a batch of new vessels sourced from a CSV file. This is equivalent to first calling DropVessels and then calling BatchAddVessels. A maximum of 1000 vessels can be added to a fleet.

batch_add_vessels_from_csv(fleet_id, path)[source]
Parameters
  • fleet_id (str) – Fleet identifier

  • path (str) – path to the csv file with vessels

replace_vessels_from_csv(fleet_id, path)[source]
Parameters
  • fleet_id (str) – Fleet identifier

  • path (str) – path to the csv file with vessels

Methods

Create Fleet

Create a user defined fleet

Example

fleet = FleetManagement(base_client).create_fleet(
    fleet_name="my fleet"
)

Arguments

class oceanbolt.com.fleetmanagement_v3.types.CreateFleetRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for creating a Fleet

fleet_name

The new name of the Fleet.

Type

str

Response

class oceanbolt.com.fleetmanagement_v3.types.Fleet(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Fleet resource

fleet_id

The Fleet identifier.

Type

str

fleet_name

The name of the Fleet.

Type

str

owner_user_id

The user id of the Fleet owner (the user who has created the Fleet).

Type

str

organization

The organization that the user belongs to.

Type

str

vessels_in_fleet

The number of vessels in the Fleet.

Type

google.protobuf.wrappers_pb2.Int32Value

vessels

List of Vessels in the Fleet.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Vessel]

shared_with_org

A flag indicating whether this is a shared fleet.

Type

google.protobuf.wrappers_pb2.BoolValue

List Fleets

Lists all user defined fleets

Example

fleets = FleetManagement(base_client).list_fleets()

Arguments

None

Response

class oceanbolt.com.fleetmanagement_v3.types.Fleets(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Response object for listing Fleets

fleets

List of user defined Fleet resources.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Fleet]

organization_fleets

List of organizational Fleet resources that are shared with the current user.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Fleet]

predefined_fleets

List of system level predefined Fleet resources.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Fleet]

Describe Fleet

Retrieves a user defined fleet

Example

fleet = FleetManagement(base_client).describe_fleet(
    fleet_id="<fleet_id>"
)

Arguments

class oceanbolt.com.fleetmanagement_v3.types.GetFleetRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for retrieving a Fleet

fleet_id

Identifier of the Fleet resource to be retrieved.

Type

str

Response

class oceanbolt.com.fleetmanagement_v3.types.Fleet(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Fleet resource

fleet_id

The Fleet identifier.

Type

str

fleet_name

The name of the Fleet.

Type

str

owner_user_id

The user id of the Fleet owner (the user who has created the Fleet).

Type

str

organization

The organization that the user belongs to.

Type

str

vessels_in_fleet

The number of vessels in the Fleet.

Type

google.protobuf.wrappers_pb2.Int32Value

vessels

List of Vessels in the Fleet.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Vessel]

shared_with_org

A flag indicating whether this is a shared fleet.

Type

google.protobuf.wrappers_pb2.BoolValue

Delete Fleet

Deletes a user defined fleet

Example

FleetManagement(base_client).delete_fleet(fleet_id="<fleet-id>")

Arguments

class oceanbolt.com.fleetmanagement_v3.types.DeleteFleetRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for deleting a Fleet

fleet_id

Identifier of the Fleet resource to be deleted.

Type

str

Response

None

Rename Fleet

Renames a user defined fleet

Example

FleetManagement(base_client).rename_fleet(fleet_id="<fleet-id>",new_fleet_name="new name")

Arguments

class oceanbolt.com.fleetmanagement_v3.types.RenameFleetRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for renaming a Fleet

fleet_id

Identifier of the Fleet resource to be renamed.

Type

str

new_fleet_name

The new name of the Fleet.

Type

str

Response

class oceanbolt.com.fleetmanagement_v3.types.Fleet(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Fleet resource

fleet_id

The Fleet identifier.

Type

str

fleet_name

The name of the Fleet.

Type

str

owner_user_id

The user id of the Fleet owner (the user who has created the Fleet).

Type

str

organization

The organization that the user belongs to.

Type

str

vessels_in_fleet

The number of vessels in the Fleet.

Type

google.protobuf.wrappers_pb2.Int32Value

vessels

List of Vessels in the Fleet.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Vessel]

shared_with_org

A flag indicating whether this is a shared fleet.

Type

google.protobuf.wrappers_pb2.BoolValue

Share Fleet

Shares a user defined fleet with other users in the same organization

Example

FleetManagement(base_client).share_fleet(fleet_id="<fleet-id>")

Arguments

class oceanbolt.com.fleetmanagement_v3.types.ShareFleetRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for sharing a Fleet

fleet_id

Identifier of the Fleet resource to be shared.

Type

str

Response

class oceanbolt.com.fleetmanagement_v3.types.Fleet(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Fleet resource

fleet_id

The Fleet identifier.

Type

str

fleet_name

The name of the Fleet.

Type

str

owner_user_id

The user id of the Fleet owner (the user who has created the Fleet).

Type

str

organization

The organization that the user belongs to.

Type

str

vessels_in_fleet

The number of vessels in the Fleet.

Type

google.protobuf.wrappers_pb2.Int32Value

vessels

List of Vessels in the Fleet.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Vessel]

shared_with_org

A flag indicating whether this is a shared fleet.

Type

google.protobuf.wrappers_pb2.BoolValue

Unshare Fleet

Unshares a user defined fleet, so that it is no longer shared with other users in the same organization

Example

FleetManagement(base_client).unshare_fleet(fleet_id="<fleet-id>")

Arguments

class oceanbolt.com.fleetmanagement_v3.types.ShareFleetRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for sharing a Fleet

fleet_id

Identifier of the Fleet resource to be shared.

Type

str

Response

class oceanbolt.com.fleetmanagement_v3.types.Fleet(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Fleet resource

fleet_id

The Fleet identifier.

Type

str

fleet_name

The name of the Fleet.

Type

str

owner_user_id

The user id of the Fleet owner (the user who has created the Fleet).

Type

str

organization

The organization that the user belongs to.

Type

str

vessels_in_fleet

The number of vessels in the Fleet.

Type

google.protobuf.wrappers_pb2.Int32Value

vessels

List of Vessels in the Fleet.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Vessel]

shared_with_org

A flag indicating whether this is a shared fleet.

Type

google.protobuf.wrappers_pb2.BoolValue

Add Vessel

Adds a vessel to a fleet. All metadata values must be strings.

Example

vessel = FleetManagement(base_client).add_vessel(
    fleet_id="<fleet_id>",
    vessel={
        "imo":1234567,
        "metadata":{
            "key":"value"
        }
    }
)

Arguments

class oceanbolt.com.fleetmanagement_v3.types.AddVesselRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for adding a Vessel to a Fleet

fleet_id

Identifier of the Fleet resource where vessels should be added.

Type

str

vessel

Vessel params for the vessel that should be added.

Type

oceanbolt.com.fleetmanagement_v3.types.VesselParams

Response

class oceanbolt.com.fleetmanagement_v3.types.Vessel(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Vessel object

imo

IMO number of the vessel.

Type

int

dwt

DWT of the vessel.

Type

float

built

The year the vessel was built.

Type

int

vessel_name

Current name of the Vessel.

Type

str

segment

Name of the segment which the vessel belongs to.

Type

str

sub_segment

Flag code of the country where the vessel is currently registered.

Type

str

flag_code

Flag code of the country where the vessel is currently registered.

Type

str

ex_name

Ex name of the Vessel.

Type

str

type_

The type of the vessel.

Type

str

metadata

Metadata object that contains arbitrary data fields defined by the user.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.Vessel.MetadataEntry]

status

Vessel status (livestate data).

Type

oceanbolt.com.fleetmanagement_v3.types.VesselStatus

stoppage_events

Vessel speed events (stopage data).

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.VesselStoppageEvent]

class MetadataEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Delete Vessel

Deletes a vessel from a fleet

Example

FleetManagement(base_client).delete_vessel(
    fleet_id="<fleet_id>",
    imo=1234567
)

Arguments

class oceanbolt.com.fleetmanagement_v3.types.DeleteVesselRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for deleting a single Vessel from a Fleet

fleet_id

Identifier of the Fleet resource where the vessel should be deleted.

Type

str

imo

IMO number of the Vessel to be deleted.

Type

int

Response

None

Batch Add Vessels

Batch adds new vessels from a fleet. All metadata values must be strings.

Example

FleetManagement(base_client).batch_add_vessels(
    fleet_id="<fleet_id>",
    vessels=[
        {
        "imo":1234567,
        "metadata":{
            "key":"value"
        },
        {
        "imo":7654321,
        "metadata":{
            "key":"other_value"
        }
    ]
)

Arguments

class oceanbolt.com.fleetmanagement_v3.types.BatchVesselsRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for batch adding Vessels to a Fleet

fleet_id

Identifier of the Fleet resource where vessels should be added.

Type

str

vessels

List of Vessels to be added.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.VesselParams]

Response

None

Batch Add Vessels From CSV

Batch adds new vessels from a fleet sourced from a CSV file. A maximum of 1000 vessels can be added to a fleet.

The csv file must have a column named ‘imo’.

Example

Example of csv file my_fleet_list.csv:

imo

my_key

other_key

my_link

1234567

val

some value

https://mylink….

7654321

another val

some other value

https://mylink….

FleetManagement(base_client).batch_add_vessels_from_csv(
    fleet_id="<fleet_id>",
    path="path/my_fleet_list.csv"
)

Arguments

class oceanbolt.sdk.fleet.FleetManagement.batch_add_vessels_from_csv
Parameters
  • fleet_id (str) – Fleet identifier

  • path (str) – path to the csv file with vessels

Response

None

Drop Vessels

Removes all vessels from a fleet

Example

FleetManagement(base_client).drop_vessels(
    fleet_id="<fleet_id>"
)

Arguments

class oceanbolt.com.fleetmanagement_v3.types.DropVesselsRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for dropping Vessels in a Fleet

fleet_id

Identifier of the Fleet resource where vessels should be dropped.

Type

str

Response

None

Replace Vessels

Replaces the existing vessels in a Fleet with a batch of new vessels. This is equivalent to first calling DropVessels and then calling BatchAddVessels. A maximum of 1000 vessels can be added to a fleet. All metadata values must be strings.

Example

FleetManagement(base_client).replace_vessels(
    fleet_id="<fleet_id>",
    vessels=[
        {
        "imo":1234567,
        "metadata":{
            "key":"value"
        },
        {
        "imo":7654321,
        "metadata":{
            "key":"other_value"
        }
    ]
)

Arguments

class oceanbolt.com.fleetmanagement_v3.types.BatchVesselsRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Request object for batch adding Vessels to a Fleet

fleet_id

Identifier of the Fleet resource where vessels should be added.

Type

str

vessels

List of Vessels to be added.

Type

Sequence[oceanbolt.com.fleetmanagement_v3.types.VesselParams]

Response

None

Replace Vessels From CSV

Replaces the existing vessels in a Fleet with a batch of new vessels sourced from a CSV file. This is equivalent to first calling DropVessels and then calling BatchAddVessels. A maximum of 1000 vessels can be added to a fleet.

The csv file must have a column named ‘imo’.

Example

Example of csv file my_fleet_list.csv:

imo

my_key

other_key

my_link

1234567

val

some value

https://mylink….

7654321

another val

some other value

https://mylink….

FleetManagement(base_client).replace_vessels_from_csv(
    fleet_id="<fleet_id>",
    path="path/my_fleet_list.csv"
)

Arguments

class oceanbolt.sdk.fleet.FleetManagement.replace_vessels_from_csv
Parameters
  • fleet_id (str) – Fleet identifier

  • path (str) – path to the csv file with vessels

Response

None