Getting Started

Setup

The SDK supports the following python versions: 3.6, 3.7, 3.8, and 3.9

In order to install, run the following:

pip install oceanbolt.sdk

In order to upgrade an existing installation, run the following:

pip install oceanbolt.sdk --upgrade

Setting the API access token

The API key is set when creating a base api client class instance.

It can be set in two different ways:

  1. Setting the API key from ENV:

    The API can set by specifying the OCEANBOLT_API_KEY ENV variable.:

    OCEANBOLT_API_KEY=<your access token>

    If the API key is set through ENV variable, it will automatically be picked up by the SDK when creating a base API client.

from oceanbolt.sdk.client import APIClient
base_client = APIClient()
  1. Setting the API key manually:

    The API key can also be specified manually when creating an API client.

from oceanbolt.sdk.client import APIClient
base_client = APIClient("<your access token>")

If both options are set simultaneously, the manual inputted API key will take precedence.

For users working with the SDK inside a notebook, we also provide the ability to enter the API key manully in the prompt.

This can be done by using the APIClientInteractive helper function:

from oceanbolt.sdk.client import API
base_client = APIClientInteractive()

This will open a promt where you can enter the token.

Connecting and accessing data

When a api base client has been created, this base client can be used to connect to the different data endpoints that are provided in the Oceanbolt API.

For example in order to access the TradeFlowTimeseries data endpoint, we would do the following:

trade_flows = TradeFlowTimeseries(base_client)

Once connection is set up to a data endpoint, data can be access using the get method:

trade_flows.get()

The get method accepts a range of different filter arguments to customize and filter the data returned. All arguments are document on for each of the individual data endpoints. As an example the arguments allowed for the TradeFlowTimeseries is shown here: python

For example we could add filters to limit the date range we are querying for, while also changing the frequency of the data to weekly:

from datetime import date

df = trade_flows.get(
    start_date=date(2020,1,1)
    end_date=date(2020,12,31)
    frequency="weekly"
)

The “get” Method

Data is always accessed through the “get” method. The “get” method is available on all data endpoint classes. The data is returned as a pandas.DataFrame(), allowing for further data processing in an easy and smooth way.

Full code example

The full code for the example above:

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.trade_flows import TradeFlowTimeseries
from datetime import date

base_client = APIClient(<"your access token>") # here we are using the manual method to specify the token
trade_flows = TradeFlowTimeseries(base_client)

df = trade_flows.get(
    start_date=date(2020,1,1)
    end_date=date(2020,12,31)
    frequency="weekly"
)

or in more compact way:

from oceanbolt.sdk.client import APIClient
from oceanbolt.sdk.data.trade_flows import TradeFlowTimeseries
from datetime import date

base_client = APIClient(<"your access token>") # here we are using the manual method to specify the token

df = TradeFlowTimeseries(base_client).get(
    start_date=date(2020,1,1)
    end_date=date(2020,12,31)
    frequency="weekly"
)

Accessing Tanker data

By default the Oceanbolt Python SDK extract data for dry bulk vessels, but it also covers multiple other shipping segments, such as tankers, lng and lpg carriers.

In order to extract tanker data from the platform, you will need to specify the platform to connect to when instantiating the client:

base_client = APIClient(<"your access token>", "tank") #here we are specifying to connect to the tanker platform

If the platform is left out it will default to dry and connect to the dry bulk platform.